Sessions

Every conversation with OpenParallax happens within a session. Sessions track message history, tool call results, and metadata. There are two session types: normal and OTR (Off-the-Record).

Normal Sessions

Normal sessions are the default. When you open the web UI or start a TUI conversation, a new session is created.

Characteristics:

• Persistent — all messages, tool calls, and results are stored in SQLite
• Full tool access — all configured tools are available
• Memory integration — conversations are logged to memory for future context
• Titled automatically — after 3 exchanges, the engine generates a title using the LLM
• Resumable — switch back to any previous session to continue the conversation

Session Lifecycle

1. Creation — a session is created when you send your first message in a new conversation (or use /new)
2. Active — messages flow through the pipeline, tools are called, outputs are generated
3. Title generation — after 3 user-agent exchanges, the LLM generates a concise title for the session
4. Idle — the session remains accessible in the sidebar/session list for future use
5. Deletion — sessions can be explicitly deleted via /delete, the CLI, or the web UI

Session Storage

Normal sessions are stored in the SQLite database at <workspace>/.openparallax/openparallax.db. The database uses WAL mode for concurrent read/write access. Each session record includes:

• Session ID (unique identifier)
• Title (auto-generated or empty before 3 exchanges)
• Creation timestamp
• Last activity timestamp
• Message history (user messages, assistant responses, tool calls, results)
• Metadata (mode, channel source)

OTR Sessions

OTR (Off-the-Record) mode creates a temporary session designed for sensitive or experimental conversations. Start an OTR session with the /otr slash command.

Characteristics:

• Ephemeral — session data is stored in a Go sync.Map in memory, never written to SQLite
• Read-only tools — write operations are filtered out at the tool definition level
• No memory persistence — the conversation is not logged to memory files
• Visual indicator — UI accent colors change from cyan to amber
• Lost on restart — since data lives only in memory, restarting the engine discards OTR sessions

Filtered Tools in OTR Mode

The following tools are removed in OTR sessions:

Category	Filtered Tools
File operations	write_file, delete_file, move_file, copy_file, create_directory, delete_directory, move_directory, copy_directory
Git	git_commit, git_push
Communication	send_email
Memory	memory_write
Canvas	canvas_create, canvas_update, canvas_project
Media	generate_image, edit_image, generate_video
Agents	create_agent
Email management	email_move, email_mark
System	clipboard_write
Utilities	archive_create, spreadsheet_write

Read-only tools remain fully available: read_file, list_directory, search_files, memory_search, git_status, git_diff, git_log, browser_navigate, browser_extract, read_calendar, etc.

OTR Visual Indicator

When OTR mode is active, the web UI applies the .otr CSS class to the document root. This overrides all 8 accent color tokens from cyan to amber:

• Borders, glows, and highlights shift to warm amber tones
• An "OTR" badge appears in the sidebar
• The color change is immediately visible across all UI components

This constant visual reminder prevents accidentally treating an OTR session as a normal session.

Managing Sessions

Listing Sessions

Web UI: Sessions appear in the sidebar, sorted by last activity. Each shows the auto-generated title (or "Untitled" before 3 exchanges) and a relative timestamp.

CLI:

openparallax session list

Slash command:

/sessions

Switching Sessions

Web UI: Click any session in the sidebar to switch to it. The chat panel loads the full message history.

CLI TUI: Use /sessions to list sessions, then start a new TUI connection specifying the session.

Exporting Sessions

Export the current session as JSON:

/export

The export includes all messages, tool calls with parameters and results, Shield verdicts, timestamps, and session metadata. Useful for sharing conversations, debugging, or archival.

Deleting Sessions

From a conversation:

/delete

Deletes the current session and starts a new one.

From the CLI:

# Delete a specific session by ID
openparallax session delete sess_abc123

# Delete all sessions
openparallax session delete --all

Deleting a session removes it from SQLite, including all messages and tool call history. This operation is irreversible. OTR sessions cannot be deleted via the CLI since they do not exist in the database.

Session Titles

Session titles are generated automatically by the LLM after 3 user-agent exchanges. This delay ensures the title reflects the actual conversation topic rather than just the first message.

The title generation happens asynchronously and does not block the conversation. Titles appear in the sidebar and session listings once generated.

Session IDs

Each session has a unique ID in the format sess_<random>. Session IDs are used in:

• WebSocket event filtering (events include a session_id field)
• Audit log entries (linking actions to their session)
• CLI commands for session management
• REST API endpoints

Cross-Channel Sessions

When multiple channels are connected (web UI, CLI TUI, Telegram, etc.), each channel creates independent sessions. Sessions are not shared across channels — a Telegram conversation and a web UI conversation are separate sessions with separate histories.

The engine routes events to the correct channel adapter based on the session's EventSender implementation.

Next Steps

• Memory — how conversations feed into long-term memory
• Security — how OTR affects Shield evaluation
• Web UI — visual features of session management