claude-tap

# claude-tap [中文文档](README_zh.md) `claude-tap` is a local proxy and trace viewer for AI coding agents. Run your CLI through it, or listen to local app transcripts, then inspect the real API traffic and agent context: system prompts, conversation history, tool schemas, tool calls, streaming responses, token usage, and request diffs. Website: [Local AI Agent Trace Viewer](https://liaohch3.com/claude-tap/) · Guide: [How to view agent traces locally](docs/guides/agent-trace-viewer.md) It works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex), [Codex App](https://openai.com/codex/), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Grok Build CLI](https://docs.x.ai/build/overview), [Kimi CLI](https://github.com/MoonshotAI/kimi-cli), [MiMo Code](https://mimo.xiaomi.com/en/mimocode), [OpenCode](https://opencode.ai), [OpenClaw](https://github.com/openclaw/openclaw), [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent), [Hermes Agent](https://github.com/NousResearch/hermes-agent), [Cursor CLI](https://cursor.com/cli), [Qoder CLI](https://qoder.com/cli), [Antigravity CLI](https://antigravity.google/product/antigravity-cli), and [CodeBuddy CLI](https://www.codebuddy.ai).

Open a real agent run, inspect every request, and compare how context changes between turns.

Light viewer overview

Dark mode for long review sessions

Structured diff across adjacent requests

## 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. Open the prompt diff viewer · View repository

## Why use it - **See the exact context**: inspect prompts, messages, tool definitions, tool calls, tool results, reconstructed streaming responses, and token usage. - **Debug behavior with evidence**: compare adjacent requests and pinpoint which prompt, message, tool, or parameter changed. - **Share one portable artifact**: each run writes a local trace session that can be exported to a self-contained HTML viewer for review or archiving. - **Keep traces on your machine**: no hosted dashboard is required, and common auth headers are redacted before recording. - **Use one workflow across clients**: trace 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, and CodeBuddy. ## Supported Clients | Client | Typical use | |--------|-------------| | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Anthropic API, AWS Bedrock, Claude-compatible gateways such as DeepSeek / GLM, or local proxy upstreams such as CC Switch | | [Codex CLI](https://github.com/openai/codex) | OpenAI API key mode or ChatGPT subscription OAuth | | [Codex App](https://openai.com/codex/) | Desktop app launched through forward proxy mode so backend HTTP/WebSocket request bodies are captured | | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Google OAuth / Code Assist traffic | | [Grok Build CLI](https://docs.x.ai/build/overview) | Grok subscription OAuth sessions through the official CLI chat proxy | | [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | `dsh` headless tasks and custom profiles using DeepSeek or compatible gateways | | [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) | Legacy kimi-cli and the newer Kimi Code CLI | | [MiMo Code](https://mimo.xiaomi.com/en/mimocode) | MiMo Code sessions (OpenCode fork with multi-provider support) | | [OpenCode](https://opencode.ai) | Multi-provider OpenCode sessions | | [OpenClaw](https://github.com/openclaw/openclaw) | Multi-provider OpenClaw sessions | | [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) | Pi sessions, including OpenAI Codex OAuth providers | | [Hermes Agent](https://github.com/NousResearch/hermes-agent) | Multi-provider Hermes TUI or gateway sessions | | [Cursor](https://cursor.com/cli) CLI / IDE Agent | Launch `cursor-agent` + live transcript watch (`claude-tap --tap-client cursor`) | | [Qoder CLI](https://qoder.com/cli) | Qoder Agent sessions through forward proxy mode | | [Antigravity CLI](https://antigravity.google/product/antigravity-cli) | Antigravity Agent sessions through forward proxy mode | | [CodeBuddy CLI](https://www.codebuddy.ai) | Tencent CodeBuddy SaaS or internal Copilot endpoint | ## Install Requires Python 3.11+ and the client you want to trace. ```bash # Recommended uv tool install claude-tap # Or with pip pip install claude-tap ``` Upgrade: `claude-tap update`, `uv tool upgrade claude-tap`, or `pip install --upgrade claude-tap` ## Quick Start Run the client you want to inspect through `claude-tap`. Flags after `--` are passed to the selected client. ``` … ``` Claude Code examples ```bash # Pass flags through to Claude Code claude-tap -- --model claude-opus-4-6 claude-tap -c # continue last conversation # Skip all permission prompts (auto-accept tool calls) claude-tap -- --dangerously-skip-permissions # Live viewer is on by default; pass Claude flags after -- claude-tap -- --dangerously-skip-permissions --model claude-sonnet-4-6 ``` `claude-tap` auto-detects custom Claude Code upstreams from `ANTHROPIC_BASE_URL`, `ANTHROPIC_BEDROCK_BASE_URL`, or `ANTHROPIC_VERTEX_BASE_URL` in your environment or Claude settings. Use `--tap-target` only when you want to override that detected target. Local proxy upstreams are supported too: if a tool such as [CC Switch](https://github.com/farion1231/cc-switch) points Claude Code at a local `ANTHROPIC_BASE_URL`, `claude-tap` detects that value from Claude settings and records the traffic before forwarding it upstream. Use `claude-tap` in place of `claude`, such as `claude-tap -- `; no separate `--tap-client` value is needed. For the Claude Code VS Code extension, set `Claude Code: Claude Process Wrapper` to `claude-tap`; on Windows, use the full `claude-tap.exe` path if VS Code cannot find it. Claude Code with DeepSeek API Full English guide: [Claude Code with DeepSeek API](docs/guides/deepseek-claude-code.md). Simplified Chinese version: [Claude Code 搭配 DeepSeek API](docs/guides/deepseek-claude-code.zh.md). ```bash export ANTHROPIC_AUTH_TOKEN="" unset ANTHROPIC_API_KEY export ANTHROPIC_MODEL="deepseek-v4-pro[1m]" export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]" export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]" export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash" export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash" export CLAUDE_CODE_EFFORT_LEVEL=max export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic ``` ```bash claude-tap -- --permission-mode bypassPermissions ``` `claude-tap` reads the DeepSeek upstream from `ANTHROPIC_BASE_URL`, then launches Claude Code against the local proxy. Use `--tap-target https://api.deepseek.com/anthropic` only as a manual override. Claude Code with AWS Bedrock `claude-tap` supports three Bedrock scenarios and auto-detects which applies: **Anthropic-compatible Bedrock gateway (New API or similar, no SigV4 in Claude Code)** ```bash export ANTHROPIC_AUTH_TOKEN="" unset ANTHROPIC_API_KEY export ANTHROPIC_BASE_URL="https://new-api.example.com" export ANTHROPIC_MODEL="bedrock/claude-opus-4-6" export ANTHROPIC_DEFAULT_OPUS_MODEL="bedrock/claude-opus-4-6" export ANTHROPIC_DEFAULT_SONNET_MODEL="bedrock/claude-opus-4-6" export ANTHROPIC_DEFAULT_HAIKU_MODEL="bedrock/claude-opus-4-6" claude-tap -- --model bedrock/claude-opus-4-6 ``` `claude-tap` records the normal Claude Code `/v1/messages` HTTP/SSE traffic, then forwards it to the gateway. For model names prefixed with `bedrock/`, it removes Claude Code beta-only request options that AWS Bedrock rejects while preserving the captured trace. **Custom Bedrock gateway (company proxy, no SigV4)** ```bash export CLAUDE_CODE_USE_BEDROCK=1 export ANTHROPIC_BEDROCK_BASE_URL="https://your-gateway.company.com/bedrock" claude-tap ``` `claude-tap` detects the non-AWS host, redirects both `ANTHROPIC_BASE_URL` and `ANTHROPIC_BEDROCK_BASE_URL` to the local proxy, and decodes the AWS EventStream binary response format to extract token usage and model info. **AWS native Bedrock (SigV4-signed requests)** ```bash export CLAUDE_CODE_USE_BEDROCK=1 export ANTHROPIC_BEDROCK_BASE_URL="https://bedrock-runtime.us-east-1.amazonaws.com" export AWS_REGION="us-east-1" claude-tap --tap-proxy-mode forward ``` When the endpoint is a real AWS domain (`*.amazonaws.com`), `claude-tap` does **not** rewrite `ANTHROPIC_BEDROCK_BASE_URL` to localhost — doing so would break AWS SigV4 signature validation. Use forward proxy mode (`--tap-proxy-mode forward`) to capture this traffic without modifying the signed request. Use `--tap-target` only as a manual override when auto-detection does not apply. Claude Code with Google Vertex AI `claude-tap` supports Claude Code Vertex pass-through gateways that expose the Vertex `rawPredict`, `streamRawPredict`, and `count-tokens:rawPredict` paths. ```bash export CLAUDE_CODE_USE_VERTEX=1 export CLOUD_ML_REGION="us-east5" export ANTHROPIC_VERTEX_PROJECT_ID="your-project-id" export ANTHROPIC_VERTEX_BASE_URL="https://your-gateway.company.com/vertex" export CLAUDE_CODE_SKIP_VERTEX_AUTH=1 # when your gateway handles auth claude-tap ``` When `CLAUDE_CODE_USE_VERTEX=1` and `ANTHROPIC_VERTEX_BASE_URL` is set, `claude-tap` detects that upstream, redirects both `ANTHROPIC_BASE_URL` and `ANTHROPIC_VERTEX_BASE_URL` to the local proxy, and records Vertex rawPredict HTTP/SSE traffic. If Claude Code uses native Google Vertex without `ANTHROPIC_VERTEX_BASE_URL`, use forward proxy mode or set the base URL explicitly so reverse mode has a single target to forward to. Codex CLI auth modes and examples Codex CLI supports two authentication modes with different upstream targets: | Auth Mode | How to authenticate | Upstream target | Notes | |-----------|-------------------|-----------------|-------| | **OAuth** (ChatGPT subscription) | `codex login` | `https://chatgpt.com/backend-api/codex` | Default for ChatGPT Plus/Pro/Team users | | **API Key** | Set `OPENAI_API_KEY` | `https://api.openai.com` (default) | Pay-per-use via OpenAI Platform | `claude-tap` auto-detects the Codex target from your auth state when possible. In the default reverse-proxy mode, it launches Codex with a temporary sibling provider whose `supports_websockets` setting is disabled. This produces one HTTP/SSE trace record per request with the complete request context and does not modify `~/.codex/config.toml`. ``` … ``` Codex App backend capture examples Codex App is launched through claude-tap's forward proxy so the final `/backend-api/codex/responses` HTTP and WebSocket request bodies can be captured in the same trace viewer as other clients. Current macOS installs ship as `ChatGPT.app` (bun