claude-tap
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 · Guide: How to view agent traces locally
It works with Claude Code, Codex CLI, Codex App, Gemini CLI, Kimi CLI, OpenCode, OpenClaw, Pi, Hermes Agent, Cursor CLI, Qoder CLI, Antigravity CLI, and CodeBuddy CLI.
Built with claude-tap
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, Kimi CLI, OpenCode, OpenClaw, Pi, Hermes Agent, Cursor CLI, Qoder CLI, and CodeBuddy.
Supported Clients
| Client | Typical use |
|---|---|
| Claude Code | Anthropic API, AWS Bedrock, Claude-compatible gateways such as DeepSeek / GLM, or local proxy upstreams such as CC Switch |
| Codex CLI | OpenAI API key mode or ChatGPT subscription OAuth |
| Codex App | Local Codex App sessions imported from CODEX_HOME or ~/.codex; automatic best-effort CDP WebSocket enrichment |
| Gemini CLI | Google OAuth / Code Assist traffic |
| Kimi CLI | Legacy kimi-cli and the newer Kimi Code CLI |
| OpenCode | Multi-provider OpenCode sessions |
| OpenClaw | Multi-provider OpenClaw sessions |
| Pi | Pi sessions, including OpenAI Codex OAuth providers |
| Hermes Agent | Multi-provider Hermes TUI or gateway sessions |
| Cursor CLI | Cursor Agent sessions plus readable local transcript import |
| Qoder CLI | Qoder Agent sessions through forward proxy mode |
| Antigravity CLI | Antigravity Agent sessions through forward proxy mode |
| CodeBuddy CLI | Tencent CodeBuddy SaaS or internal Copilot endpoint |
Install
Requires Python 3.11+ and the client you want to trace.
# 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 with the live browser viewer enabled by default
claude-tap
# Restore pre-v0.1.75 behavior: no live viewer server
claude-tap --tap-no-live
# Codex CLI
claude-tap --tap-client codex
# Codex App local session listener
claude-tap --tap-client codexapp
# Gemini CLI
claude-tap --tap-client gemini -- -p "hello"
# Kimi CLI
claude-tap --tap-client kimi
# New Kimi Code CLI
claude-tap --tap-client kimi-code
# Pi
claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark -p "hello"
# Cursor CLI
claude-tap --tap-client cursor -- -p --trust --model auto "hello"
# Qoder CLI
claude-tap --tap-client qoder -- -p "hello" --permission-mode dont_ask
# Antigravity CLI
claude-tap --tap-client agy
# CodeBuddy CLI
claude-tap --tap-client codebuddy
# 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
or ANTHROPIC_BEDROCK_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 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 -- <claude-args>; 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.
Full English guide: Claude Code with DeepSeek API. Simplified Chinese version: Claude Code 搭配 DeepSeek API.
export ANTHROPIC_AUTH_TOKEN="<your DeepSeek API key>"
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
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-tap supports two Bedrock scenarios and auto-detects which applies:
Custom Bedrock gateway (company proxy, no SigV4)
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)
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