Stored session transcripts
Turn on stored session transcripts for a workspace, read them in the web app or from the command line, and learn who can read them and how long they stay.
By default, CodeHerder keeps no copy of what an agent said or ran. The transcript stays on the device that ran the session. The event timeline records what happened, but not the conversation.
A workspace can opt in to stored session transcripts. CodeHerder then keeps the transcript of each work session, so you can read it after the device is gone.
Before you turn it on
A transcript holds code and tool output. That includes any secret a tool prints. Anyone who can read the transcripts can read those secrets. Turn this on only when you are happy to keep that data in CodeHerder.
Turn it on
Only a human workspace admin can change this setting. Agents cannot. It applies to one workspace at a time. A group has no setting, and a workspace does not inherit one from its group.
In the web app:
- Open the workspace and go to Settings, then General.
- In Session transcripts, tick Store session transcripts.
- Optionally change Retention. See Retention.
From the command line:
ch workspace edit <workspace> --session-transcripts true
ch workspace edit <workspace> --session-transcript-retention-days 14
The setting is off by default. It takes effect at the next session. A session that already runs does not start storing, and earlier sessions have nothing stored.
What is kept
CodeHerder stores the transcript of each session that works on a task in the workspace. For each turn it keeps the role, the text, the tool that ran, a clipped copy of the tool’s input and result, and the tokens used.
Evaluation sessions do not follow this setting. They have their own transcripts, which you read from the attempt.
Who can read a transcript
Only people can read transcripts. An agent that tries is refused. You can read the transcript of a session when you operate the session’s agent, or when you are an admin or owner of the workspace. CodeHerder records each read.
On a task, you see only the sessions you can read. If you can read none of them, the task has no transcript for you.
Read a transcript in the web app
The task page and the session page each have a Transcript section. It shows what the agent said and did, stage by stage. On the session page, the section appears for sessions that worked on a task.
- Turns sit under their stage, in workflow order. Each session shows its model, harness, turn count, tokens and cost. A live badge marks a session that still runs.
- A tool call or tool result is folded. Open it to see a clipped copy of the input or result. A failed tool result carries an error badge.
- Subagent turns nest under their session. Use the Subagent toggle to show or hide them.
- While a session runs, new turns appear on their own. If you scroll up to read, Jump to latest takes you back to the end.
- When a finished session has more turns, Load more turns fetches the next batch.
If the workspace has not turned the setting on, the section says that transcripts are not stored. If the setting is on but nothing is stored yet, it says “No transcript stored yet.” The transcript fills in as the agents work.
Read a transcript from the command line
To read every session of a task, grouped by stage in workflow order:
ch task transcript [<taskId>] [--stage <stage>] [--follow]
Each stage lists its sessions. A header shows the agent, harness, model, start time, cost and tokens, and whether the session is live or sealed. The turns follow. Subagent turns print under their session. Use --stage to print one stage only.
To read one session:
ch session transcript [<sessionId>] [--follow]
If you leave out the id, the command reads the task or session of the current sandbox.
Add --follow to keep reading a live session. The command prints new turns as they arrive and stops when no session is live. It waits up to five minutes for the first turns. Add --json to get the whole read as one JSON document. You cannot combine --json with --follow.
If nothing is stored, the command answers not_found. This happens when the setting was off during the session, when the session ended before you turned it on, or when retention removed the transcript. It also happens when you cannot read any session of the task.
Retention
A transcript stays for 30 days by default. Set Retention to any number of days from 0 to 3650. 0 keeps transcripts until the workspace is deleted. CodeHerder removes transcripts that are older than the period.
Turning the setting off stops new capture. It does not delete anything. Stored transcripts stay until retention removes them.
How this differs from ch session tail
ch session tail asks the device for its own copy. It works only while the device is online and still holds the history. A stored transcript lives in CodeHerder, so it outlasts the device.
Related guides
- Sessions from the command line — find, watch and steer a session
- Following a live agent session — watch an agent in real time
- Activity feeds — the durable record of what happened
- Evaluations — transcripts for evaluation attempts
Last updated