liaohch3/claude-tap

claude‑tap – Local proxy & trace viewer for AI coding agents

What it is

• A Python‑based command‑line tool that sits between you and an AI coding assistant (Claude Code, OpenAI Codex, Gemini, Grok, Kimi, etc.) and records every HTTP/WebSocket request the agent makes.
• It then serves a lightweight web UI where you can explore the captured trace: full request/response bodies, system prompts, tool definitions, tool calls, streaming chunks, token usage, and a diff view that highlights what changed between consecutive turns.

Why you might want it

• Debugging – See the exact payloads sent to the model, spot missing context or mis‑configured tool schemas.
• Transparency – Keep all traces on your machine; sensitive headers are redacted automatically.
• Sharing – Export a run as a self‑contained HTML file that can be reviewed or archived.
• Unified workflow – One wrapper works with dozens of popular coding‑agent CLIs (Claude Code, Codex CLI/App, Gemini CLI, Grok Build, Kimi, OpenCode, Pi, Hermes Agent, Cursor, Qoder, Antigravity, CodeBuddy, etc.).

Key features

Feature	Description
Live viewer	Starts a local web server (default) that updates in real‑time as the agent runs.
Capture‑only mode	claude‑tap --tap-no-live records a trace without launching the UI, useful for CI or batch jobs.
Diff modal	Structured side‑by‑side diff of two adjacent requests – shows which prompt, message, or tool changed.
Streaming reconstruction	Reassembles SSE/WS streaming responses so you can read the final output as if it were a normal reply.
Token accounting	Shows per‑request token usage extracted from the provider’s response metadata.
Export	Export → HTML bundles the trace into a single file that can be opened anywhere.
Proxy modes	reverse (acts as the provider endpoint) or forward (injects HTTPS_PROXY) to accommodate signed AWS Bedrock, Google Vertex, or other gateways.
Auto‑detection	Detects the correct upstream URL from environment variables or client config (e.g., ANTHROPIC_BASE_URL, OPENAI_API_KEY).

Typical workflow

# Install (requires Python 3.11+)
uv tool install claude-tap   # or: pip install claude-tap

# Run a coding agent through the proxy
claude-tap --tap-client codex          # launches Codex CLI and records traffic
claude-tap --tap-client gemini -- -p "hello"   # Gemini CLI example

# Open the live viewer (usually http://127.0.0.1:5173)
# Inspect prompts, tool calls, token usage, and compare turns.

# Export a run for later review
# (UI button → Export → HTML) or use the CLI flag `--export html`

Supported clients (selected)

• Claude Code (Anthropic, Bedrock, DeepSeek, Vertex)
• OpenAI Codex CLI & desktop app
• Google Gemini CLI
• Grok Build CLI
• Kimi CLI / Kimi Code CLI
• OpenCode, MiMo Code, Pi (multi‑provider agents)
• Hermes Agent, Cursor CLI, Qoder CLI, Antigravity CLI, CodeBuddy CLI
• …and any other tool that respects the system proxy.

Ecosystem

• Phistory – a companion project that uses claude‑tap in capture‑only mode to archive versioned system‑prompt snapshots and provide a diff viewer.
• Documentation site: https://liaohch3.com/claude-tap/
• Guides for special setups (DeepSeek, AWS Bedrock, Google Vertex) are in docs/guides/.

License

• Open‑source under the MIT License (see LICENSE).

---

Bottom line: claude‑tap gives developers a concrete, local way to observe and debug the exact API traffic of modern AI coding assistants, turning opaque model calls into an inspectable, shareable artifact.