claude-tap: a local proxy and trace viewer for AI coding agent API traffic

The problem claude-tap addresses: you cannot see what the agent sent

A coding agent builds a request out of many parts. There is a system prompt, a growing message history, a set of tool schemas, the tool calls the model returned, and the results fed back on the next turn. When the agent behaves badly, the visible symptom is a wrong edit or a stalled loop, and the cause is usually one changed line somewhere in that payload. The CLI does not show it.

claude-tap is aimed at that gap. It is a local reverse and forward proxy plus a trace viewer, per the project description in pyproject.toml, and it records the real API traffic rather than a summary. The README lists what you can inspect: system prompts, conversation history, tool schemas, tool calls, streaming responses, token usage and request diffs. The intended user is an engineer debugging agent behaviour, not an end user running an agent to finish a task.

The supported client list is unusually wide for a tool of this kind: Claude Code, Codex CLI, Codex App, Gemini CLI, Grok Build CLI, DeepSeek Harness, Kimi CLI, MiMo Code, OpenCode, OpenClaw, Pi, Hermes Agent, Cursor CLI, Qoder CLI, Antigravity CLI and CodeBuddy CLI. That breadth is the main reason to pick it over writing a one-off logging shim for a single client.

How the proxy and trace viewer work together

The mechanism is a man-in-the-middle on localhost. claude-tap starts a proxy, points the selected client at it, and records the HTTP exchanges as they pass through. The README distinguishes two modes. Reverse proxy mode covers clients it launches itself, which is what happens when you run claude-tap with a --tap-client value. Forward proxy mode is used for clients the tool does not launch directly, such as Codex App, Qoder CLI and Antigravity CLI, so that backend HTTP and WebSocket request bodies are still captured.

Each run writes a local trace session. The README describes that session as exportable to a self-contained HTML viewer for review or archiving, which is the part that matters for sharing: you can hand a colleague one file instead of asking them to reproduce your environment. A live browser viewer is on by default in current versions; the README notes that claude-tap --tap-no-live restores the pre-v0.1.75 behaviour of no live viewer server.

Two design choices are worth naming. First, the diff view compares adjacent requests, which is the only practical way to answer "what changed between turn 3 and turn 4". Second, redaction happens before recording, and the README says common auth headers are redacted. That ordering is correct, but it also means the trace you keep is not byte-identical to what went over the wire. If you need the exact header bytes for a support ticket, this is the wrong instrument.

The Python dependencies are narrow: aiohttp pinned to 3.14.1, cryptography, and backports-zstd on Python below 3.14. The package requires Python 3.11 or newer and ships a console entry point named claude-tap.

Installing claude-tap and capturing a first trace

Installation is a normal Python tool install. The README recommends uv and gives pip as the alternative. You also need the client you intend to trace, already installed and working.

uv tool install claude-tap

If you prefer pip, the README gives pip install claude-tap. Upgrades go through claude-tap update, uv tool upgrade claude-tap, or pip install --upgrade claude-tap.

With no arguments, claude-tap launches Claude Code through the proxy and enables the live browser viewer by default. Anything after -- is passed to the client, so this is the shortest useful invocation:

claude-tap -- --model claude-sonnet-4-6

For a different client, name it with --tap-client. The README shows Gemini CLI being driven with a one-shot prompt, which is a good way to produce a small trace before you try a long session:

gemini --tap-client gemini -- -p "hello"

That last line is how the README presents the Gemini example, with the client name and flags after the separator. Expect a trace session to appear locally and the viewer to open; the README states the live viewer is on by default. If you only want the recorded session and no server, add --tap-no-live. For Claude Code specifically, the README notes that claude-tap auto-detects custom upstreams from environment variables including ANTHROPIC_BASE_URL and ANTHROPIC_BEDROCK_BASE_URL, which is what makes Bedrock and gateway setups traceable without extra configuration.

Where claude-tap stops being the right tool

The first limitation is coverage. The README lists specific clients and specific modes for each. A client that is not on that list is not traced, and a client on the list may only be traceable in one mode: Codex App, Qoder CLI and Antigravity CLI go through forward proxy mode rather than direct launch. If your workflow depends on a client outside the list, this tool has nothing to offer you.

The second is the redaction trade-off described above. Traces are sanitised before they are written, so they are evidence of structure and content, not a faithful copy of the wire format.

The third is that a local proxy is a local process holding your credentials in the request path. The README's framing is that traces stay on your machine and no hosted dashboard is required, which is a real advantage over sending logs to a service, but it is not the same as saying the tool is sandboxed. Anyone who can read the trace directory can read your prompts and conversation history.

Finally, the project is labelled Beta in its own classifiers, and the version numbers in the changelog run through the 0.1.x range with several releases per week in August 2026. The last push was on 2026-08-16. Rapid point releases on a 0.1 line mean interfaces and flags can move; pinning a version is reasonable if you script around it.

claude-tap compared with OpenTelemetry-based tracing

The obvious alternative approach is instrumenting the agent with OpenTelemetry and shipping spans to a collector such as Jaeger or Grafana Tempo. That approach is better when you already run an observability stack, when you need traces from production services alongside agent calls, or when several people must query the same data centrally.

The difference in method is fundamental. OpenTelemetry requires the agent to emit spans, which means either the agent supports it or you patch it. claude-tap requires no cooperation from the agent at all: it sits in the network path and reads the HTTP traffic, so it works with a closed-source CLI binary. In exchange, you get HTTP-level detail rather than semantic spans, and you get it only on the machine running the proxy. There is no cross-machine aggregation and no long-term retention story in the README.

A second, lighter alternative is a plain logging proxy you write yourself with mitmproxy or a few lines of aiohttp. That gives you raw bytes and full control, and it is a fair choice if you only ever trace one client. What you would have to build yourself is the viewer: the request diff, the reconstructed streaming responses, the token accounting and the HTML export are the parts of claude-tap that a hand-rolled proxy does not give you.

Maintenance, licence and what a version bump costs you

The licence is MIT, declared both in the repository and in pyproject.toml. That permits commercial use, modification and redistribution provided the copyright notice and licence text are retained. It offers no patent grant and no warranty, and it says nothing about the terms of the APIs you are proxying. Running traffic through a local proxy does not change your obligations to Anthropic, OpenAI, Google or any other upstream provider, and the README does not discuss that question. Treat licence compliance for the upstream services as a separate matter from the MIT grant.

On maintenance: the repository is not archived, and the last push was on 2026-08-16, which is inside six months of a normal review window, so the codebase has moved recently. The release history shows v0.1.143, v0.1.144 and v0.1.145 within four days in mid-August 2026. That cadence suggests active work, and it also means the surface you integrate against is not stable. If you wrap claude-tap in scripts, pin the version you install and read CHANGELOG.md before upgrading, because a flag like --tap-no-live exists precisely because behaviour changed at v0.1.75 and some users needed the old default back.

The upgrade path itself is cheap: claude-tap update, or the equivalent uv or pip command. There is no server to migrate and no database schema in the README. The cost is in re-verifying that your client is still traced correctly after a bump, since client-side changes are outside this project's control.

Editorial conclusion

Adopt claude-tap if you debug prompt or tool-call behaviour in a supported coding CLI and want the raw request bodies on your own disk. Do not adopt it if your traffic goes to a client the README does not list, or if your threat model forbids a local process holding your API credentials. Before relying on it, install with uv tool install claude-tap, run one short session, and open the generated trace to confirm that redaction removed your auth headers and that the export produces a self-contained HTML file.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes