Sessions

What a session is

A session is one conversation with one agent. Every message you send, every file the agent touches, and every reply you get belongs to that session.

DorkOS runs sessions on three different agent tools, Claude Code, Codex, and OpenCode, and shows them all in a single list. You stop hunting across terminals and windows to remember what you were doing.

Here's the quick win: start a chat in the DorkOS web app, and if it's a Claude Code session, you can also open that exact conversation from the claude CLI in the same folder. Same conversation, either window. DorkOS just gives every session an ID so it can find it again later.

How to work with sessions day to day

Only one place can send a message at a time. If you have a session open in two windows, DorkOS locks it to whoever's actively using it, and unlocks it again a few minutes after they stop, in case you wandered off mid-turn. Everyone can still watch the conversation; only sending a new message needs the lock.

Approvals survive a refresh. If an agent asks to approve running a command or editing a file, that prompt sticks around even if you reload the page, switch sessions, or open a second window. It picks up right where it left off.

Sessions from other tools show up automatically. Claude Code sessions are just files on your disk, so any tool that can read those files sees the same sessions. Start a task from the claude CLI and it appears in the DorkOS sidebar too, no import step, no sync button. The Obsidian plugin can read the same files as well, though it's still early and under active testing, so expect some rough edges there.

Codex and OpenCode sessions work the same way in spirit: each tool keeps its own session store, and DorkOS reads from all three to build one combined list. If DorkOS can't reach one of them, it still shows you the others and flags which one it missed.

See how full each session's context is. Every row in the list shows a small gauge of how much of its context window is used, so you can spot which agents are running low before they slow down. A line at the top of the list sums it up, "2 near full · 1 auto-compacted", so you know which one to jump into first. Claude Code sessions show this reading even when they're closed; Codex and OpenCode show it once you open the session, and read "unknown" until then, because those tools only report context usage while a session is live.

Reference (for developers)

If you're calling the API directly or debugging DorkOS itself, here's the exact mechanics behind everything above.

Creating and messaging a session

A session is created with a unique ID, a working directory, and a permission mode (whether tool calls need your approval). Sending a message triggers a turn: POST /api/sessions/:id/messages returns 202 Accepted immediately, and the actual response streams over the session's durable event stream, GET /api/sessions/:id/events. That stream carries text deltas, tool calls, approval requests, and task-progress updates in real time.

Session locking

DorkOS acquires an exclusive lock on a session using the requesting client's ID, sent via the X-Client-Id header. If a second client tries to write to the same session, it gets back a 409 conflict response naming the current lock holder. The lock releases when the turn finishes or errors, and auto-expires after 5 minutes as a backstop.

Storage

DorkOS keeps no separate session database of its own. Each runtime owns its storage:

• Claude Code writes each session as a transcript file at ~/.claude/projects/{project-slug}/{session-id}.jsonl, in JSONL (one JSON record per line). That file is the single source of truth for the session.
• Codex and OpenCode keep their own session stores, managed by their own tooling.

DorkOS reads the Claude Code transcript to build the session list, plus per-session metadata and full message history. Metadata is computed fresh on every request, so it always reflects the current file on disk.

Session sync

Each connected client subscribes to GET /api/sessions/:id/events. On connect, the server sends a snapshot: completed history, the in-progress turn, session status, and any pending approvals. From there, every client receives the same live events with monotonic (always-increasing) sequence numbers, including turns triggered by another client or the CLI.

On reconnect, the client resumes from its last sequence number via the Last-Event-ID header, and the server replays exactly what it missed. If that gap can't be served, the server falls back to sending a fresh snapshot instead.

The sidebar list stays live the same way: a single global stream, GET /api/events, announces session_upserted, session_removed, and session_status events as sessions are created, deleted, or change state, across every client and the CLI.

Session metadata

Most people never need this. Here's where each field on a Claude Code session comes from, if you do:

Working directories

Each session runs inside a working directory that determines where the agent can read and write files. It's set when the session is created, persisted in the URL as the ?dir= query parameter in standalone mode, and validated against a configurable boundary so the agent can't wander outside allowed paths. The directory picker in the DorkOS sidebar lets you browse and choose one before you start a session.

Next Steps