Traces
Share the full log of an agent session and let colleagues read or continue it.
A trace is the full chat log of an agent session: your prompts, the agent's replies, and every tool call and result. Shiplet keeps traces next to the work they produced, so a reviewer can see how a change was made and a colleague can pick the session up in their own agent.
Use a trace when the review needs the story behind the work: what was asked, what the agent tried, which checks ran, and what it changed. Reviewers read it beside the artifact, and teammates continue it in their own agent instead of starting over.
A self-hosted server shows the Traces panel when SHIPLET_ENABLED_FEATURE_FLAGS includes traces.
Share the session you are in
The easiest way is to ask your agent: say “Share this session to Shiplet <name or id>” in Claude Code or Codex. Your agent knows which session it is in, including subagents, screenshots, and videos. From a terminal, run:
npx shiplet-cli trace share --current --shiplet <id>
The CLI masks secrets on your computer before anything is sent, and Shiplet scans again when the trace arrives. Screenshots, videos, and PDFs the session produced are attached automatically (up to 20 MiB each). Add --dry-run to see what would be sent, or --no-files to leave the files out.
Any other agent can share its sessions too, by writing the open trace format.
To share a session that has no artifact to review, add --new instead of --shiplet: npx shiplet-cli trace share --current --new --title "Fix the flaky test". Shiplet creates an ordinary Shiplet for it, whose page is the trace viewer.
In a cloud agent with no browser on its computer, sign the CLI in first with npx shiplet-cli login --device, or connect Shiplet MCP with OAuth and let the agent call createTraceUploadLink. See Choosing how to sign in.
No terminal? Drop a session file (.jsonl) onto the drop zone in the Shiplet's Traces panel. The browser masks secrets before uploading. Claude Code keeps sessions in ~/.claude/projects/ and Codex keeps them in ~/.codex/sessions/.
Who sees what
A new trace is private: only you and the Shiplet's owner can open it. Share it with a person or email, a team, the whole organization, or anyone with the link, and choose a level for each audience:
| Level | What that audience sees |
|---|---|
| Full | Everything except secrets. |
| Conversation | Messages and tool steps, without tool output or reasoning. |
| Summary | What was done, files touched, checks, and the outcome. No text. |
A more specific audience wins: a person or email over their team, a team over the organization. Organization administrators can read every shared trace in full, but not private ones. You can also mask extra terms, hide paths, hide reasoning, or hide videos for one audience, and use Preview as this audience before sharing.
npx shiplet-cli trace audiences <trace> --shiplet <id> --audience organization=conversation --audience email:dana@example.com=full
Read a trace and continue it
Open a trace from the Shiplet's Traces panel to read the timeline, images, videos, and files. The page shows which level you are seeing. Your browser cannot write into Claude Code or Codex, so the viewer gives you two ways to continue:
- Copy prompt for your agent: paste it into your agent, which loads the trace over Shiplet MCP.
- Copy CLI command:
npx shiplet-cli trace pull <trace> --shiplet <id> --as contextprints an agent-ready handoff.
Limits and retention
- The session itself can be up to 16 MiB per upload after masking. Files go up separately: up to 20 MiB each and 256 MiB per trace.
- An organization can store up to 10 GiB of traces.
- Deleting a trace or its Shiplet deletes its files. Traces of a Shiplet archived for more than 7 days are deleted.
- API keys need the
traces:readortraces:writescope. See API keys.
Next: run search in Code Mode MCP for the trace operations, or read Access control.