Sessions & the index

Everything in Cockpit starts from the session index: a live, repo-grouped view of every conversation you've had with any of the three agents, on any machine account, in any terminal.

Where sessions come from

Cockpit watches each provider's session root — ~/.claude, ~/.codex, ~/.copilot, plus any extra config homes you add in Settings. Sessions you run in a plain terminal appear and update live; there's no import step and no daemon.

Each session's working directory is resolved to its git repository, worktree-aware: a session run in a linked worktree groups under the main repository, and the sidebar row is named owner/repo from the origin remote. Sessions with no repository land in a flat Chats section at the bottom.

The sidebar

One row per repository, ordered by last activity, with that repo's sessions underneath:

• Width — drag the sidebar's right edge, or focus it and use the arrow keys; double-click it to reset. See Resizing and zoom.
• Pagination — long histories load behind a "more…" row; the full index is never shipped to the UI at once.
• Search — global, across all providers and repos, by title, branch, path or id.
• Names — sessions carry their agent-generated titles where the provider records one.
• PR badges — sessions on a Cockpit-created branch show their pull request state (open, draft, merged, closed) in GitHub's colors.
• Child sessions — a session that another session started sits under that session, indented one step per level. Copilot's app does this when a session creates new sessions for pieces of its work, each in its own workspace. Open a child to get a by <parent> chip in its chat header that takes you back to the session that started it. Fold a family with the ▾ N button after the parent's title (or ← / → on the parent's row); Cockpit remembers the fold. A folded parent still shows when a session inside it is running, finished or waiting for you, and the session you have open is never folded away.

Click a session to read its parsed transcript — messages, tool calls, and results. Type below the transcript to continue the conversation with the same provider; see Chat.

Searching inside transcripts

"Where did I discuss X?" — across every agent at once, which no single vendor can answer. Press ⌘K, type the words, and pick search transcripts for … under the session matches. Cockpit streams through the transcripts on demand (nothing is indexed or uploaded), scoped to the repo you are looking at — a row in the results widens the search to every repo. Each hit shows the message around the match, marked, with who said it; picking one opens that session at that message — scrolled into view and briefly highlighted, however far back it is.

Only what you and the agents said is searched: tool calls and their output stay out, so a file that every session read doesn't match every session. Large transcripts are read only up to a cap and long searches stop after a time budget — the line under the results says how much was read and whether it stopped early, so a partial answer never looks like a complete one. Backspace on an empty query goes back to the normal palette; Esc closes it.

Keyboard

⌘K	command palette
⌘N	new task
⌘[ / ⌘]	back and forward through views you've visited
⌘,	settings
Esc	back out of a secondary view

Backing into the conversation that's currently running just flips the view — the live log keeps streaming, untouched.

Flying and landed

A session whose agent is running right now is flying: a pulsing dot in the agent's color on its row and on the home board. When the turn ends and you haven't opened the session since, it has landed — a solid dot and landed <time> — until you open it. Two more states say a session needs you: an agent that has stopped to ask a question or for a permission shows a question glyph and asks you, on top of the board whatever else is true of it, and an open pull request on the session's branch that has failing checks or changes requested shows GitHub's red x and #57 checks failing. The same set is what the Dock badge counts; see Notifications.

A session you run in a terminal or the provider's own app counts as flying while its log keeps growing — Cockpit reads the tail of the log on every write. When the log goes quiet for a minute and a half it drops back to the ground without landing; while the last thing written is a tool call still waiting for its result (a test suite, a build), Cockpit waits ten minutes instead, since those write nothing until they finish.

Archiving

Two kinds of "gone", handled differently:

• Archived in Cockpit — you can archive sessions in-app; they collapse into a dimmed per-repo section. Provider logs have no archive flag, so this state lives in Cockpit's own config.
• Archived or deleted in the provider's own app — Cockpit reads each provider's native archived/deleted state (Copilot's data.db, Codex's archived_sessions/, the Claude desktop app's session store) and hides those sessions entirely.

The history window

By default Cockpit shows your full history. If years of sessions make the sidebar noisy, set a history window in Settings › View — sessions idle for longer than N days disappear from the index (the files on disk are never touched). The presets run from Last day, for when you only want what you touched today, out to a year.

Why it's fast

The index stays snappy on huge histories because of a few deliberate constraints:

• Only per-provider session roots are walked and watched — never package caches, cloned repos, logs, or SQLite files.
• Meta parsing reads at most 256 KB per file, and parsers are failure-tolerant: session formats are provider-internal and drift between releases, so anything unreadable is skipped rather than failing the scan.
• A stat-cache (mtime + size) persists across restarts, so relaunching only re-parses files that actually changed.
• Scans yield to the event loop, so the UI never blocks behind indexing.

Sessions missing?

If a provider's sessions don't show up — most commonly Copilot, whose log format is the least documented — see Troubleshooting.