Claude Tap Local Trace Viewer
Capture and inspect real API traffic and context from AI coding clients on your own machine.
- Source repo
- liaohch3/claude-tap
- Stars
- ★ 3.2k
- Last updated
- 8d ago
- License
- MIT
- Primary language
- Python
- FA score
- 53/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API · Claude APIChatGPT (Partial support)
- You'll need
- Typical use
- A Claude Code developer needs to verify the exact system prompt, messages, and tool definitions sent during a problematic run.
- Main limitation
- Requires Python 3.11+, a shell environment, network access, and an installed and authenticated target client.
- Source review
- 53/100 · Major gaps 1 safety controls not found
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.
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.
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-clientvalues and proxy modes must be selected. - Raw SSE and WebSocket events are not retained unless
--tap-store-stream-eventswas 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 does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Claude Tap Local Trace Viewer This agent | 53 · Major gaps | ★ 3.2k | 8d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| ccxray | 73 · Some gaps | ★ 295 | 3d ago | JavaScript | Claude Code · Claude API |
| OrcaReplay | 84 · Good | ★ 261 | today | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| Agent Skills Library | 67 · Some gaps | ★ 240 | 25d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence: The project acts as a local proxy, intercepting and recording API traffic, but does not explicitly state least-privilege principles; user confirmation is present via options like --permission-mode, but not explicitly required; data flow transparency is partially addressed in README, but not detailed; sensitive data handling mentions redacting auth headers, but lacks detail; dependency security pins versions but lacks vulnerability scanning evidence; external effects include modifying environment variables and trusting CA, but impact is not fully explained; rollback is not mentioned; source attribution includes author info but is unverified. Deductions: least privilege not explicit, user confirmation unclear, data flow transparency insufficient, sensitive data handling lacks detail, dependency security evidence insufficient, external effects not fully explained, rollback missing, source attribution unverified.
Evidence: CI tests exist across multiple Python versions, but results are not provided; dependency availability is pinned but not guaranteed; failure messages are not detailed. Deductions: test results not provided, dependency availability unverified, failure messages unclear.
Evidence: Supports many clients and scenarios; capability boundaries are implied but not explicit; trigger precision is provided via --tap-client options but not detailed; environment fit supports multiple platforms but lacks detail. Deductions: capability boundaries not explicit, trigger precision lacks detail, environment fit lacks detail.
Evidence: Information architecture is clear with README and docs; install notes are detailed; naming is stable with versioning; examples and FAQ are rich; known limitations are not explicitly listed; license is MIT; changelog exists; maintenance responsibility is implied but not explicit. Deductions: known limitations not explicit, maintenance responsibility unclear.
Evidence: Output usability is supported by trace viewer and HTML export; marginal value is provided by unique debugging features; cost-benefit is favorable as it runs locally without hosting. Deductions: output usability lacks detail, marginal value not quantified, cost-benefit not detailed.
Evidence: README includes screenshots and demos, but no verifiable test results; cross-source corroboration is absent; fact-inference separation is not explicit. Deductions: claim traceability insufficient, cross-source corroboration missing, fact-inference separation unclear.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- The project intercepts and records API traffic, which may contain sensitive data; use with caution.
- The project modifies environment variables and trusts CA, which may affect system security; test in an isolated environment.
- Dependencies are pinned but no vulnerability scanning evidence is provided; regularly check dependency security.
FAQ
Are traces uploaded to a cloud service?
Can it inspect Codex traffic authenticated through a ChatGPT subscription?
codex login first, then use claude-tap --tap-client codex; the tool attempts to detect the target from the local auth state.Can I retain every raw streaming event?
--tap-store-stream-events must be enabled during capture. It is off by default.Do I need a paid API key?
OPENAI_API_KEY modes; other clients use their own authentication setup.