Summary

Add tapes start <agent> — a single command that boots the tapes proxy, API server, and agent harness together. No separate terminals, no configuration. The proxy is invisible to the user.

Problem

Running tapes today requires the user to start the proxy and API server first (tapes serve), then separately launch their agent with the right settings. This is two steps, two terminals, and requires understanding tapes internals. It also only supports one agent and one provider (Anthropic) at a time.

We want to support multiple agents (Claude Code, OpenCode, Codex) and multiple providers (Anthropic, OpenAI) with zero setup.

Target DX

tapes start claude

That's it. Proxy starts, agent launches, telemetry flows. When the agent exits, cleanup happens automatically.

Multiple agents work across terminals:

Terminal 1: tapes start claude    → captures all Claude Code traffic
Terminal 2: tapes start codex     → captures all Codex traffic, same proxy
Terminal 3: tapes deck            → live dashboard showing both agents

tapes start without an agent argument starts just the proxy and API server. New agent sessions connect to it from other terminals:

Terminal 1: tapes start              → proxy + API running
Terminal 2: tapes start claude       → connects to existing proxy, launches claude
Terminal 3: tapes start codex        → connects to existing proxy, launches codex

Both workflows are equivalent — tapes start claude will start the proxy itself if one isn't already running.

Backward Compatibility

tapes serve continues to work exactly as it does today — single provider, single upstream, manual configuration. tapes start is a new command that builds on top of the existing proxy and API server, not a replacement for tapes serve.

Constraint: Agents Must Be Launched Through Tapes

Only agents launched via tapes start <agent> are captured. Running an agent directly (e.g., claude without tapes start) bypasses the proxy entirely — the agent talks straight to the provider over TLS and tapes never sees the traffic.

This is a deliberate tradeoff. By redirecting agents at launch rather than intercepting TLS, we avoid all certificate and trust store complexity. The cost is that tapes start is the only entry point for observed sessions.

How It Works

tapes start manages the proxy lifecycle automatically:

• First tapes start — no proxy running. Starts the tapes proxy and API server in the background, then launches the agent (if one was specified).
• Additional tapes start — proxy already running. Connects to the existing proxy and launches the agent.
• Agent exits — if it's the last agent, the proxy shuts down. Otherwise, proxy stays up for remaining agents.
• Crash recovery — if a process dies unexpectedly, the next tapes start detects the stale state and starts fresh.

Port selection is automatic. The OS assigns an available port — no collisions, no configuration.

Avoiding TLS MITM

A traditional forward proxy would need to intercept TLS traffic — generating fake certificates, managing a local certificate authority, and requiring sudo to add it to the system trust store. This is complex and fragile.

Instead, tapes start redirects agents before TLS enters the picture. It configures each agent's base URL to point at the local tapes proxy over plain HTTP. The agent sends requests to http://localhost:<port>/... thinking it's the real provider. The tapes proxy reads the plaintext request, stores it, then forwards it to the actual provider (api.anthropic.com, api.openai.com) over real TLS.

The result: full visibility into all agent traffic with no certificate generation, no trust store changes, and no interception of encrypted connections.

Agent Support

The proxy routes traffic to the correct upstream based on the agent. Each request is tagged with the agent name for filtering and comparison.

What This Unlocks

Multi-agent observation. Run two agents on the same task and observe token usage and behavior side by side in tapes deck.

Terminal 1: tapes start claude    → "refactor auth.go"
Terminal 2: tapes start codex     → "refactor cache.go"
Terminal 3: tapes deck            → live dashboard showing both agents

Schema Changes

The existing schema already captures provider and model on every node. The only addition is an agent_name field to distinguish which harness (Claude Code, OpenCode, Codex) sent the request. Agent statistics are computed via a database view — no denormalized counters to drift.