claude-tap: A local proxy and trace viewer for AI coding agent traffic
Project brief: Intercept and inspect Coding Agent API traffic from Claude Code, Codex CLI, Gemini CLI, Cursor CLI, OpenCode, Kimi/Kimi Code, Pi, and Hermes in a local trace viewer.
At a glance
- What is it?
- claude-tap intercepts API traffic from Claude Code, Codex CLI, Gemini CLI, and a dozen other coding agents, and renders it in a local trace viewer. It is a debugging and transparency tool for engineers who need to see exactly what context an agent sends.
- Who is it for?
- Adopt claude-tap if you debug agent behavior by inspecting prompts, tool calls, or token usage, and if you want traces to stay on your machine. Skip it if you need a hosted dashboard or if your agent client is not in the supported list.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What claude-tap actually solves
AI coding agents hide their reasoning behind a chat interface. When an agent misbehaves, you cannot tell whether the system prompt changed, a tool schema drifted, or a parameter was altered between turns. claude-tap addresses that by acting as a local proxy between the agent CLI and its API backend, recording the raw HTTP traffic and presenting it in a trace viewer. The README lists support for Claude Code, Codex CLI, Codex App, Gemini CLI, Grok Build CLI, Kimi CLI, MiMo Code, OpenCode, OpenClaw, Pi, Hermes Agent, Cursor CLI, Qoder CLI, Antigravity CLI, and CodeBuddy CLI. That breadth is the project's main selling point: one workflow for inspecting many clients, instead of learning a different debugging tool for each.
How the interception works
The mechanism is a local proxy. You launch the agent through claude-tap, and the proxy sits between the CLI and the API endpoint. The README shows commands like claude-tap --tap-client codex and claude-tap --tap-client gemini -- -p "hello". Flags after -- are passed to the selected client. For some clients, such as Cursor CLI, the approach differs: you launch cursor-agent and then watch the live transcript with claude-tap --tap-client cursor. For desktop apps like Codex App, the README mentions forward proxy mode so that backend HTTP and WebSocket request bodies are captured. The captured data includes system prompts, conversation history, tool schemas, tool calls, streaming responses, token usage, and request diffs. The viewer shows adjacent requests side by side, which helps pinpoint exactly which prompt, message, tool, or parameter changed between turns.
Getting it running
Installation requires Python 3.11 or newer. The recommended method is uv tool install claude-tap, with pip install claude-tap as an alternative. Upgrades use claude-tap update, uv tool upgrade claude-tap, or pip install --upgrade claude-tap. The quick start is minimal: running claude-tap with no arguments launches Claude Code with the live browser viewer enabled by default. To restore pre-v0.1.75 behavior without the live viewer server, use claude-tap --tap-no-live. Client selection happens via --tap-client, and you can pass flags through to the underlying agent. For example, claude-tap -- --model claude-opus-4-6 passes the model flag to Claude Code, and claude-tap -- --dangerously-skip-permissions auto-accepts tool calls. The README also notes that claude-tap auto-detects custom Claude Code upstreams from environment variables like ANTHROPIC_BASE_URL and ANTHROPIC_BEDROCK_BASE_URL, which matters if you route through a gateway or a local proxy such as CC Switch.
The trace viewer and portable artifacts
Each run writes a local trace session. The viewer has a light mode and a dark mode, the latter described as useful for long review sessions. A notable feature is the structured diff across adjacent requests, which is the core debugging aid. The README also mentions exporting a trace to a self-contained HTML viewer for sharing or archiving. That portability is a real advantage: you can send a trace to a colleague without requiring them to install claude-tap. The project states that no hosted dashboard is required, and common auth headers are redacted before recording. That redaction is a security feature, but it also means you cannot inspect the exact auth values if you need to debug an authentication issue; you only see that a header was present.
Limitations and wrong-tool cases
The most obvious limitation is that claude-tap only works with the listed clients. If you use an agent not in the table, the proxy will not know how to intercept it. Even within the supported list, the interception relies on the client's network behavior. Desktop apps like Codex App require forward proxy mode, which is more complex to set up than the CLI path. The README does not document failure modes, such as what happens when a client changes its API endpoint or switches to a different transport. Another limitation is that the trace viewer is local only; there is no hosted dashboard. That is a privacy benefit, but it means you cannot access traces from a different machine unless you export the HTML artifact and transfer it. For teams that want centralized trace storage, claude-tap is the wrong tool.
A real alternative: Phistory
The README itself names an alternative: Phistory, a project built with claude-tap. Phistory archives versioned system prompt snapshots from agent CLIs such as Claude Code, Codex, Kimi, opencode, and Pi. It uses claude-tap's capture-only prompt export to preserve raw HTTP trace evidence and generate comparison-friendly prompt snapshots. The difference in approach is significant. claude-tap is a general-purpose proxy and viewer for all API traffic, while Phistory focuses specifically on system prompt history and diffing. If your primary need is tracking how system prompts evolve over time, Phistory may give you a more specialized workflow. If you need to inspect tool calls, streaming responses, or token usage, claude-tap is the broader tool. They are complementary, not competing in the same niche.
Maintenance, licensing, and upgrade cost
The project is under the MIT license, which allows commercial use and modification with attribution. The repository shows active maintenance: the latest release v0.1.145 was pushed on 2026-08-16, with v0.1.144 and v0.1.143 in the preceding days. That cadence suggests frequent updates, which is good for compatibility but implies an upgrade cost. The README provides three upgrade methods, so the process is straightforward. However, the frequent releases also mean that the interception logic may change as agent CLIs evolve. You should budget time to test claude-tap after upgrading either the tool or your agent client. The project has no homepage, so you rely on the GitHub repository and PyPI page for documentation and release notes.
Editorial conclusion
Adopt claude-tap if you debug agent behavior by inspecting prompts, tool calls, or token usage, and if you want traces to stay on your machine. Skip it if you need a hosted dashboard or if your agent client is not in the supported list. Before relying on it, verify that your client's version still matches the capture method, since CLI changes can break interception, and confirm that the redaction of auth headers covers the credentials you care about.
Community notes