Agent integrations

Tapes captures an agent in one of two ways. The client launches the agent under a just-in-time capture proxy that dies with the process, or — for an agent that launches itself — the client binds the address the agent was installed against and captures whatever runs in that window.

Harness	Lane	Plugin needed first
claude	tapesctl start claude	none
codex	tapesctl start codex	none
pi	tapesctl start pi	tapesctl plugin install pi
codex-app	tapesctl capture codex-app	tapesctl plugin install codex-app

Capture commands address the private ingest API, :8082 by default — not the read API on :8081. A capture pointed at the read port reports success and stores nothing.

Start the server and its local dependencies before these examples:

tapes local up
tapes serve

Then install the client:

curl -sSfL https://download.tapes.dev/tapesctl/install | bash

The agent brings its own provider credentials. tapes auth stores credentials for the server-side features that call a provider themselves — span embedding and skill generation — and is not part of capturing an agent.

Claude Code

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

tapesctl starts a loopback capture proxy, sets Claude Code’s ANTHROPIC_BASE_URL to it, launches claude, and ships the captured turns to the server. Pass Claude flags after --:

tapesctl start claude --ingest-url http://localhost:8082 -- --worktree

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

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

For a manually managed, fixed-port proxy instead of the just-in-time one:

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

Gateway capture protocols

The Tapes extproc adapter captures Anthropic Messages, OpenAI Responses, and OpenAI Chat Completions (/v1/chat/completions). Chat Completions supports JSON and SSE responses, text/refusals, streamed function-call arguments (including parallel calls), tool-result history, completion usage and cached input tokens. It keeps the provider’s model ID after any gateway routing rewrite. Explicit Chat Completions tool exchanges are derived as conversation calls even when non-streaming, so tool results link back to their function calls.

Responses and Chat Completions use distinct shared reducers. The captured request selects the format (input versus messages), including when ingest reduces raw-only turns or the derive read path recovers a missing reduction. Deploy the updated Tapes ingest/derive image before enabling raw-only capture with the updated extproc image; dual retains the adapter’s reduction as well as the original wire bytes.

A stream missing [DONE], a finish reason, or valid frames is retained as partial, not represented as a completed answer. Invalid function arguments remain attached to the tool call without a partially decoded object; valid argument numbers retain their JSON precision. Choice zero is the canonical answer; additional choices are preserved in response metadata rather than merged. If zero is absent, only the indexed alternatives are retained and the response is marked partial. Null optional fields are treated as absent. Audio and custom-tool streaming deltas are not yet normalized; they are marked partial and require the raw lane for full-fidelity replay. Request parameters are forwarded unchanged; this adds capture, not API translation or execution.

The wire contract follows the OpenAI Chat Completions reference.

Codex

The terminal CLI is launched like Claude:

tapesctl start codex --ingest-url http://localhost:8082

The ChatGPT desktop app launches itself, so it is captured through lifecycle hooks instead. Install the plugin once, then run a capture window and start a session in the app:

tapesctl plugin install codex-app
tapesctl capture codex-app --ingest-url http://localhost:8082

plugin install codex-app writes the handoff file and points the app’s Codex configuration at the capture address; capture reads that handoff and binds it. Running capture first fails and tells you to install. Unlike start, capture prints no turn counts when it stops — it reports the number of sessions it saw.

plugin uninstall codex-app removes the provider entry and the handoff, but the plugin stays registered with Codex; the command prints the codex plugin remove line that finishes the job.

pi

pi is captured by an installed extension, so the install is a prerequisite rather than a convenience:

tapesctl plugin install pi
tapesctl start pi --ingest-url http://localhost:8082

start pi refuses to run when the extension is absent, before anything is bound or launched. pi redirects several providers to one endpoint, so it is the one harness that takes --schema:

tapesctl start pi --ingest-url http://localhost:8082 --schema openai

--schema on claude or codex is an error rather than a silent no-op: each speaks exactly one schema, taken from the harness.

Ollama and generic clients

With default configuration, Tapes forwards Ollama-compatible traffic to http://localhost:11434:

tapes serve
curl http://localhost:8080/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen3-coder:30b","messages":[{"role":"user","content":"hello"}],"stream":false}'

Pull a chat model separately; tapes local up pulls the embedding model, not every completion model:

ollama pull qwen3-coder:30b

For another Anthropic-, OpenAI-, or Ollama-compatible application, configure its base URL as http://localhost:8080 and run tapes serve with the matching --provider and --upstream. Preserve the path convention expected by the client and provider.

Verify and stop

The read API health endpoint is separate from the proxy and from ingest:

curl http://localhost:8081/ping
tapes status
tapesctl sessions list --api-url http://localhost:8081

A captured session appears in that list. start prints the harness’s own session id on exit, which is a different id from the one tapesctl sessions get takes — find the session in the list rather than pasting the printed id.

Stop the foreground tapes serve process with Ctrl-C. tapes local down removes bootstrap containers but keeps PostgreSQL data unless --wipe is supplied.