Skip to main content
When you run claude yourself in a repo where you ran orchestra enable, Orchestra captures the session from the transcript Claude Code writes to disk. Claude Code writes that file continuously, line by line, while it works. Orchestra reads it the same way: its work appears in the web app and the terminal client about a second after Claude Code writes it. There is nothing to set up beyond orchestra enable, run once in each repository you want saved, not once per agent.

​
Every agent, in the repositories you enable

orchestra enable turns on the repository you run it in, with its worktrees. From then on, sessions there from Claude Code, Codex, Gemini CLI, Cursor and OpenCode are saved as they work, with no command per agent and no flag. Sessions in any other folder on the machine are never read or sent. It prints what it found:
  • From now on, not before. Sessions written before you ran enable are not imported. orchestra import brings in earlier ones, from enabled repositories only.
  • Only the repositories you enabled. The list lives on your machine. orchestra disable in a repository takes it off. A session counts as in a repository when it ran in the checkout, a folder inside it, or one of its worktrees (including a worktree you have since removed).
  • Claude Code still opts in per repo. Its sessions are followed when their own hooks register them, which happens in repos where you ran orchestra enable. The hooks add what the transcript alone cannot give: each turn saved the moment it ends, teammates’ messages handed to the agent between turns, and prior context at session start.
  • It starts at login. enable starts the tailer right away and registers it to start at login (a launchd agent on macOS, a systemd user unit on Linux), because only Claude Code has hooks that could bring it back.
  • Only into the store you enabled. The machine is enabled for the Orchestra configuration enable ran with. A tailer serving another configuration follows Claude Code only.
  • Never what you kept private. Off-the-record sessions and sessions Orchestra itself launched are skipped before their transcripts are read.
orchestra disable stops following the machine’s agents, removes the login start, and removes this repo’s hooks.

​
How it works

  • One capture tailer per machine. orchestra enable, your login, or the first Claude Code session you start launches it in the background. It follows the sessions in every repository you enabled. Five sessions still mean one tailer.
  • The hooks keep it running. The SessionStart and UserPromptSubmit hooks that orchestra enable installs check for a running tailer. If none is running, they start one and return right away; they never wait for it.
  • It stops when you do, unless the machine is enabled. On a machine where only Claude Code is followed, after 20 minutes with no session activity and nothing running on this machine’s session supervisor, the tailer exits, and your next session start or prompt brings it back. On an enabled machine it keeps running, since nothing else would restart it for the other agents.
  • A large session costs a bounded share of one core. Each pass reads the whole transcript, so after a pass the tailer waits about nine times the CPU that pass took before reading the same session again. An ordinary session waits nothing; a session of hundreds of megabytes is saved every few seconds instead of continuously.
  • It captures only what you opted in. A session is tailed only if its own hooks registered it, which happens only in repos where you ran orchestra enable. It is captured only into the store that repo is configured for. A repo set up for a different store keeps capturing per turn through its own Stop hook.
  • It is the same capture. The tailer runs the same capture as the Stop hook, including secret redaction. Both can capture the same turn; each message is stored once.

​
When capture is per turn

Without a running tailer, a session is still captured, but in one batch when each turn ends. This is the case:
  • between the tailer idling out and your next prompt;
  • when ORCHESTRA_CAPTURE_TAILER=off is set;
  • for sessions in a repository signed in to a different server than the one the tailer is serving.
When a session is captured per turn, the terminal client and the web session page say its work shows when each turn ends, so a quiet screen in the middle of a long turn is not mistaken for an idle agent.

​
Checking it

Doctor reports whether the tailer is running (its pid, uptime and whether it can reach the store) and how many seconds capture trails the newest line of your most recent session:
The second line is the one to read when a session seems missing: it names the harnesses the running tailer actually follows, and when one you enabled is not among them, why. If the store is unreachable, for example a stale SSM tunnel that accepts connections and relays nothing, the tailer backs off and retries (2s, then doubling up to a minute) instead of hanging. Doctor shows the error and when the next attempt is due. The tailer’s log is at ~/.orchestra/capture-tailer.log.

​
After you rebuild or update

The tailer outlives your sessions, so after a rebuild the one already running is still the old code. Every build writes a stamp of the source it was built from (apps/cli/dist/build-stamp.json), and the running tailer records the stamp it started with. When they differ, your next prompt starts a replacement, which asks the old tailer to finish what it is capturing and step aside before it takes over. Nothing in flight is dropped, and a replacement that cannot start leaves the old one capturing. orchestra status and orchestra doctor say when the running build is not the installed one:

​
Subagents

A Claude Code subagent is saved as a session of its own, linked to the session that started it, and only people who can see that session can see it.