How capture works

What actually happens between typing paperctl start claude and seeing a session in paper console. Read this to understand where your data flows, which pieces run on your machine, and how the system behaves when something is stopped or offline.

The pieces

• The agent — Claude Code, Codex, or Pi, launched through paperctl start (or shell routing).
• paperctl — the CLI you interact with: login, launch, inspect, search.
• paperd — a local daemon that routes your agent’s model traffic and uploads transcripts in the background.
• Your organization’s gateway — the cloud route your model traffic passes through on its way to the provider. Capture happens here.
• tapes — the service behind the scenes that stores sessions and powers the console, search, and Skills.

The path of a session

agent (Claude Code / Codex / Pi)
   │  model API calls
   ▼
paperd (local proxy)
   │
   ▼
organization gateway ──────────► model provider
   │  each request/response
   │  captured as it passes
   ▼
capture log (immutable)
   │  derive: sessions, traces, spans, status
   ▼
console · search · Insights · Skills

When you launch an agent through paper, its model API calls route through paperd to your organization’s gateway, and on to the model provider you configured. The provider’s answer comes back the same way. As each request/response pair passes through the gateway, it is captured — the conversation, tool activity, model, token usage, and timing. Because capture happens at the gateway, any call that reached your provider through paper has been captured, and nothing needs to be re-sent from your machine for that to be true.

For Claude Code sessions there is a second path: the agent writes a transcript on your machine as it works, and paperd uploads it in the background — typically within about half a minute of a turn finishing, with a final push when the session ends. Transcripts add the harness’s own record of the session, including subagent activity.

What ends up in a captured session

Both paths record content verbatim: the gateway captures each request and response as your agent sent and received it, and Claude Code transcripts are uploaded as the agent wrote them — your prompts, the agent’s responses and reasoning, tool calls, and tool results, subagent transcripts included.

The practical consequence of “verbatim”: anything your agent reads or produces during a paper-launched session becomes part of the record. That includes:

• file contents and diffs, if the agent read or edited those files
• shell command output, if the agent ran those commands
• environment variable values, if they appeared in prompts, commands, or output
• error messages, stack traces, and logs the agent encountered

The boundary runs the other way too: paper is not a monitor of your machine. There is no repository scan or background upload — files the agent never touched, shell activity outside a paper-launched agent, and anything else that never entered the agent’s context is not part of the session.

Alongside the content, paper records session metadata: the working directory path, agent type and version, session identifiers, start and end times, and the authenticated user and organization the session belongs to.

From captured to searchable

Captured data lands in an append-only capture log, and everything you interact with is derived from it:

1. Turns are assembled into sessions, traces, and spans — the structure you see in a session’s detail view — along with a derived status (completed, failed, abandoned, or unknown).
2. The conversation spine of each trace is indexed for semantic search. Indexing runs as a follow-on pass, so a session typically becomes searchable — via paperctl search or the console — within about a minute of its content arriving.
3. Insights, stats, and Skill generation all read from the same derived data, so they agree with what the session detail page shows.

Sessions appear in the console shortly after turns complete; search and aggregate views catch up moments later. If a session looks incomplete, give it a minute — the final transcript push happens when the agent exits.

When something is stopped or offline

• Uploading never blocks your agent. Transcript pushes happen in the background; a slow or failed upload has no effect on the session you’re running.
• If the network is down, model calls fail — they need to reach your provider through the gateway, capture or no capture. Transcript files simply wait on disk; paperd retries with increasing backoff and pushes them when connectivity returns.
• Retries can’t create duplicates. Uploads are deduplicated by content, so retried pushes, daemon restarts, and grown transcript files all land on the same session.
• If paperd isn’t running, paperctl start won’t launch the agent — run paperctl doctor to check and repair the installation. An agent launched directly (plain claude with shell routing disabled) runs normally and is simply not captured.
• If uploads keep failing after a session has ended, retries stop after roughly ninety minutes. The transcript files remain on disk and the session can be recovered later, but recovery is not automatic.