Claude Tap Local Trace Viewer
Capture and inspect real API traffic and context from AI coding clients on your own machine.
What does this agent do, and when should you use it?
claude-tap is a local proxy and trace viewer for AI coding clients. It starts a reverse or forward proxy and launches the selected client, or can run as a proxy-only service for a separately launched client. Request-response pairs and WebSocket sessions are written to local trace storage, then rendered as a self-contained HTML viewer or exported as a compact trace bundle. The viewer exposes system prompts, conversation messages, tool schemas, tool calls, streaming responses, token usage, and structured diffs between adjacent requests. Documented clients include Claude Code, Codex CLI, and Codex App, alongside Gemini CLI, Kimi, OpenCode, Pi, Cursor CLI, and others.
When you run claude-tap, it starts a reverse or forward proxy for the selected client. Base-URL clients are directed to the reverse proxy; other clients use proxy and local-CA environment variables. It forwards SSE chunks and WebSocket messages while recording each request-response pair or WebSocket session locally. Raw SSE/WebSocket event arrays are not stored by default; add --tap-store-stream-events when they must be available in viewer or export output. At exit it produces a self-contained HTML viewer; claude-tap dashboard opens saved traces, while claude-tap export <session-id> -o trace.ctap.json exports a compact bundle that can later be rendered with claude-tap export trace.ctap.json -o trace.html.
- A Claude Code developer needs to verify the exact system prompt, messages, and tool definitions sent during a problematic run.
- A team using Codex CLI wants to compare adjacent requests and identify whether changed behavior came from context, parameters, or tool calls.
- An engineer running multi-provider clients such as OpenCode, Pi, or Hermes needs one local place to inspect their API traffic.
- A developer needs to archive or share a debugging session as a portable HTML file or compact trace bundle for offline review.
- A macOS user testing Codex App wants to capture backend HTTP and WebSocket request bodies through forward-proxy mode.
What are this agent's strengths and limitations?
- Supports both reverse and forward proxy modes, covering clients that accept a custom base URL as well as clients that must use a general HTTPS proxy.
- Combines request and response data, tool schemas and calls, reconstructed streaming output, token usage, and structural adjacent-request diffs in a local viewer.
- Keeps traces on the local machine without a hosted dashboard and automatically redacts common authentication headers before recording.
- Requires Python 3.11+, a shell environment, network access, and an installed and authenticated target client.
- Coverage depends on each client's base-URL or proxy support, and client-specific `--tap-client` values and proxy modes must be selected.
- Raw SSE and WebSocket events are not retained unless `--tap-store-stream-events` was enabled during capture.
- Some macOS forward-proxy flows require trusting the local CA; the first Antigravity launch may prompt to unlock the login keychain.
How do you install or deploy this agent?
Requires Python 3.11+ and an installed, configured client to trace. Recommended installation: uv tool install claude-tap; alternatively: pip install claude-tap. Authenticate the chosen client before tracing. For example, Codex CLI subscription OAuth uses codex login, while API-key mode requires OPENAI_API_KEY.
How do you use this agent?
For Claude Code, run claude-tap. For Codex CLI, run claude-tap --tap-client codex; a Gemini CLI example is claude-tap --tap-client gemini -- -p "hello". The live viewer is enabled by default; add --tap-no-live for scripts or CI. To start only the proxy, use claude-tap --tap-no-launch --tap-port 8080, then connect the client using its documented base-URL or proxy settings.