# Sessions
Source: https://dorkos.ai/docs/concepts/sessions

What a DorkOS session is, how it stays in sync across tools, and how it works under the hood





# Sessions [#sessions]

## What a session is [#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 [#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.

<Callout type="info">
  Want a picture of this? A short clip of a session appearing in the DorkOS sidebar the instant you
  start it from the CLI says more than the paragraph above ever could.
</Callout>

## Reference (for developers) [#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 [#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 [#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 [#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 [#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 [#session-metadata]

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

| Field               | Source                                  |
| ------------------- | --------------------------------------- |
| **ID**              | The unique ID in the JSONL filename     |
| **Title**           | First user message in the transcript    |
| **Preview**         | Beginning of the last assistant message |
| **Created**         | File creation timestamp                 |
| **Updated**         | File modification timestamp             |
| **Permission mode** | Extracted from the SDK's init message   |

### Working directories [#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 [#next-steps]

<Cards>
  <Card title="Architecture" href="/docs/concepts/architecture">
    Understand how sessions fit into the overall DorkOS architecture.
  </Card>

  <Card title="Building Integrations" href="/docs/integrations/building-integrations">
    See how session operations are delivered through the Transport interface, for extension and
    integration authors.
  </Card>

  <Card title="Tool Approval" href="/docs/guides/tool-approval">
    Learn how to review and approve tool calls during a session.
  </Card>
</Cards>