Capture a Claude Code session

Claude Code is the shortest capture journey tapes has: the client launches the harness under a just-in-time proxy, the proxy dies with the process, and the session is waiting on the server when you exit. No Claude Code configuration changes, no plugin.

Before you start

You need a running server and the client on your PATH. The installation page covers both; the short version:

curl -fsSL https://download.tapes.dev/install | bash
curl -sSfL https://download.tapes.dev/tapesctl/install | bash
tapes local up
tapes serve

Claude Code brings its own Anthropic credentials — tapes auth is for server-side features and plays no part in capture.

Capture a session

1. Launch Claude Code through the client:

   tapesctl start claude

   Captured turns ship to the ingest API, http://localhost:8082 by default. Flags for Claude Code itself go after --:

   tapesctl start claude -- --worktree

2. Work the session as usual, then exit Claude Code. The proxy shuts down with it and the captured turns are already on the server:

   ✓ captured session f47ac10b-58cc-4372-a567-0e02b2c3d479
     pass --web-url for a console link
     logs at ~/.tapes/logs/start-20260813-180411-54233.log

3. List sessions. Read commands address the read API, http://localhost:8081 by default:

   tapesctl sessions list

   

   Your session is the top row. The ID column is the tapes session id, the value the next command takes.

4. Read one back:

   tapesctl sessions get 01a0d365-2f42-77a1-8473-bd2e295244a4

   

   Every read command ends by naming the one to run next. traces list is one row per turn; spans list <trace-id> is one row per span under a turn. Add --json to any of them for the server’s document.

   

For a server that is not on the default ports, set the two URLs once — capture commands use the ingest one, read commands use the other:

tapesctl config set ingest-url <url>   # start, capture, sync
tapesctl config set api-url <url>      # sessions, search, export, seed

--ingest-url and --api-url also exist as per-command flags.

Two ids, two ports

start prints the harness’s own session id on exit. That is not the id tapesctl sessions get takes — find the session in sessions list instead of pasting the printed one. And captures address ingest on 8082; a capture pointed at the read port 8081 reports success and stores nothing.

Sweep the transcripts too

Claude sessions also produce transcripts on disk, which carry the subagent structure the wire traffic alone cannot show. start tails them live. For a session no capture was running for, sweep them afterwards:

tapesctl sync

sync sweeps the last seven days by default; --since-days 0 sweeps everything. Re-pushing is safe — the server deduplicates, and a re-run reports the same files as unchanged.

The fixed-port alternative

start runs a proxy just in time and picks its own address. If you want a manually managed proxy on a fixed port instead — to share one across shells, or to capture a client start does not launch — run the server’s proxy against Anthropic and point Claude Code at it yourself:

tapes serve --provider anthropic --upstream https://api.anthropic.com
ANTHROPIC_BASE_URL=http://localhost:8080 claude

Keep the /v1 convention consistent: if the upstream carries a path suffix, the base URL must carry the same one, or requests 404.

Next steps

• Search captured sessions by meaning — find this session again next month.
• Turn captured sessions into skills — extract the pattern it demonstrates.
• Inspecting and exporting data — the full read surface behind sessions list.