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.3k
- Last updated
- 14d ago
- License
- MIT
- Primary language
- Python
- FA score
- 72/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API · Claude APIChatGPT (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- 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.
- Not a fit if
- Users who want a GUI instead of a terminal
- Teams without Python 3.11+ or a shell environment
- Teams that need a hosted dashboard rather than local traces
- Source review
- 72/100 · Some gaps
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 | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Claude Tap Local Trace Viewer This agent | 72 · Some gaps | CLIFree | ★ 3.3k | 14d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| ccxray | 76 · Good | CLIFree + model costs | ★ 296 | 5d ago | JavaScript | Claude Code · Claude API |
| OrcaReplay | 72 · Some gaps | CLIFree + model costs | ★ 428 | 1mo ago | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
| Agent Skills Library | 49 · Major gaps | Agent plugin / skillFree + model costs | ★ 240 | 2mo ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The product is described as a local proxy and trace viewer. The README says requests are forwarded upstream, prompts and responses are recorded, and common auth headers are redacted before recording; the security policy warns that traces can still contain private context. The data flow is described concretely, supporting higher scores there. However, the packet does not show comprehensive redaction rules, access controls, or a complete deletion and recovery path. Examples include options to skip permission prompts, so confirmation and sensitive-data handling earn only partial credit. Automatic trust of a local CA on macOS is disclosed, but a revocation path is not shown. Author and repository details are present, but publisher identity is unverified and does not establish maintenance ownership.
The README gives substantial client-specific guidance on proxy modes and authentication, while project configuration specifies Python and dependencies. CI workflows describe multi-version tests, lint, and coverage. This supports ordinary reliability, but the packet contains many client-specific behaviors that cannot all be checked against the sampled implementation. Evidence about user-facing failure messages and error handling is limited, so those scores remain low.
The product covers many CLI, desktop, and IDE scenarios and distinguishes reverse proxy, forward proxy, and transcript-watching modes. Documentation identifies boundaries such as Cursor being transcript-only and some modes requiring particular environment variables. Scenario and boundary coverage is strong. Target selection depends on client flags, environment variables, and auto-detection; the sample provides less evidence about diagnostics and fallbacks across environments.
The README, bilingual guides, support matrix, security policy, contribution entry point, and maintainer notes provide a clear information structure. Installation, upgrades, client commands, and several limitations are documented; the MIT license text is complete. The version is derived through setuptools-scm, and the release workflow handles changelog updates, but the packet does not include a complete changelog or a clear maintainer response commitment. Product and client names are mostly stable, although readers must distinguish some legacy and newer client names.
The product organizes API requests, context, tool calls, streaming responses, and token usage into local sessions, with export to a standalone HTML viewer and adjacent-request diffs. Those outputs are useful for debugging and review, and unified tracing across clients provides clear added value. Cost-benefit earns less than full credit because proxy and certificate setup plus client-specific authentication require additional work; users also need to review and manage traces containing prompts and responses.
Key README claims can be compared with the support matrix, project configuration, sampled CLI source, test configuration, and CI workflows. The security policy also states what traces may contain. Many claims are concrete and inspectable, but the sample omits full source, all support documentation, and release history, limiting cross-source confirmation. This assessment treats CI configuration as file evidence, not as a test run.
- Traces may contain prompts, tool schemas, file paths, and response bodies. Review exported HTML, logs, and screenshots before sharing, even when common auth headers are redacted.
- Depending on client configuration, the tool may use a local CA, forward traffic, or alter a child process environment. Check the selected proxy mode, upstream target, and CA trust scope before use.
- The packet shows CI test configuration, but this static review did not run tests and cannot verify implementation or support details outside the sample.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/claude-tap)<a href="https://followagents.com/en/agents/claude-tap"><img src="https://followagents.com/badge/claude-tap.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
English Changed - Compute viewer costs using the Python pricing adapter. - Explain prompt cache misses in the viewer turn detail. - Distinguish harness-injected input from human prompts when displaying conversation titles. - Flag tool results large enough to dominate a conversation turn. Fixed - Fix Dashboard records and HTML viewer HTTP 500 errors caused by urlsplit() ValueError, hiding the affected display strings and response text previews while retaining stored captures. …View on GitHub ↗ -
Release notes excerpt
- 901b856 chore: update changelog for v0.1.145 (#439) - 52bb292 fix(codexapp): capture standard Responses API paths (#422)View on GitHub ↗ -
Release notes excerpt
- e8df198 chore: update changelog for v0.1.144 (#434) - e43d34b fix: reconstruct Cursor request tools and keep dashboard viewer mounted (#432)View on GitHub ↗
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.Thanks — we use this to improve the page.