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, pointed at the server’s ingest port. Ingest is 8082; the read API on 8081 accepts nothing:

   tapesctl start claude --tapes-url http://localhost:8082

   Flags for Claude Code itself go after --:

   tapesctl start claude --tapes-url http://localhost:8082 -- --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.

3. Point the client’s read commands at the read API once, then list sessions:

   tapesctl config set tapes-url http://localhost:8081
   tapesctl sessions list

   Your session appears in the list.

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 --tapes-url http://localhost:8082

sync sweeps the last seven days by default; --since-days 0 sweeps everything. Re-pushing is safe — the server deduplicates.

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.