claude-tap 0.1.124

Trace AI CLI API requests via local reverse and forward proxies. Inspect system prompts, messages, tools, and token usage.

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, MiMo Code, OpenCode, OpenClaw, Pi, Hermes Agent, Cursor CLI, Qoder CLI, Antigravity CLI, and CodeBuddy CLI.

_{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, Kimi CLI, MiMo Code, 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
MiMo Code	MiMo Code sessions (OpenCode fork with multi-provider support)
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

# MiMo Code (OpenCode fork)
claude-tap --tap-client mimo

# 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

Claude Code examples

# 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 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.

Claude Code with DeepSeek API

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 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)

export ANTHROPIC_AUTH_TOKEN="<your gateway 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)

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 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.

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.

# OAuth users (ChatGPT Plus/Pro/Team) — auto-detected after `codex login`
claude-tap --tap-client codex

# If auto-detection cannot read your Codex auth file, specify the target explicitly
claude-tap --tap-client codex --tap-target https://chatgpt.com/backend-api/codex

# API Key users — default OpenAI API target works out of the box
claude-tap --tap-client codex

# With specific model
claude-tap --tap-client codex -- --model codex-mini-latest

# Full auto-approval (skip all permission prompts)
claude-tap --tap-client codex -- --full-auto

# OAuth + full auto; live viewer is enabled by default
claude-tap --tap-client codex -- --full-auto

Codex App listener examples

Codex App sessions are imported from local JSONL files under CODEX_HOME/sessions or ~/.codex/sessions. This mode does not launch Codex or create a network proxy; it keeps a claude-tap dashboard session open and appends in-progress and completed Codex App records as they appear.

# Listen to local Codex App sessions and inspect them in the dashboard
claude-tap --tap-client codexapp

# Use a custom Codex home directory
CODEX_HOME=/path/to/codex-home claude-tap --tap-client codexapp

--tap-client codexapp automatically imports the local transcript and silently tries to add CDP WebSocket evidence when a Codex App debug endpoint is available. CDP capture is a side-channel observer, not a proxy; the local session transcript remains the canonical source when the frontend does not expose model traffic through Chrome DevTools Protocol.

Kimi CLI examples

Use --tap-client kimi for legacy kimi-cli, or --tap-client kimi-code for the newer Kimi Code CLI. Both use reverse proxy mode by default.

claude-tap --tap-client kimi
claude-tap --tap-client kimi -- --thinking
claude-tap --tap-client kimi --tap-target https://api.moonshot.ai/v1

claude-tap --tap-client kimi-code
claude-tap --tap-client kimi-code -- --thinking
claude-tap --tap-client kimi-code --tap-target https://api.moonshot.ai/v1

Gemini CLI examples

Gemini CLI uses forward proxy mode by default. Google OAuth / Code Assist traffic goes to several Google endpoints, so forward proxy capture is the safest default. Reverse mode remains available for API-key or Vertex-style flows that honor GOOGLE_GEMINI_BASE_URL or GOOGLE_VERTEX_BASE_URL.

# Google OAuth / Code Assist
claude-tap --tap-client gemini -- -p "hello"

# Live viewer is enabled by default
claude-tap --tap-client gemini -- -p "hello"

# Reverse mode for compatible API-key / Vertex flows
claude-tap --tap-client gemini --tap-proxy-mode reverse -- -p "hello"

OpenCode examples

OpenCode is a multi-provider terminal AI assistant. Because it can talk to many providers, claude-tap defaults to forward proxy mode for opencode: it injects HTTPS_PROXY plus the local CA into the child process so traffic to any provider is captured.

# Forward proxy mode — captures every provider opencode talks to (default)
claude-tap --tap-client opencode

# Live viewer is enabled by default
claude-tap --tap-client opencode

# Reverse mode — only works when using Anthropic provider (single ANTHROPIC_BASE_URL)
claude-tap --tap-client opencode --tap-proxy-mode reverse

MiMo Code examples

MiMo Code is an OpenCode fork with persistent memory, subagent orchestration, and Xiaomi MiMo platform integration. claude-tap defaults to forward proxy mode for mimocode: it injects HTTPS_PROXY plus the local CA into the child process so traffic to any provider is captured.

# Forward proxy mode — captures every provider MiMo Code talks to (default)
claude-tap --tap-client mimo

# Live viewer is enabled by default
claude-tap --tap-client mimo

# Reverse mode — single Anthropic provider with mimo-only disabled
claude-tap --tap-client mimo --tap-proxy-mode reverse

Pi examples

Pi is a multi-provider coding agent. claude-tap defaults to forward proxy mode for Pi because Pi can use subscription OAuth providers such as openai-codex and custom API-key providers from its model registry.

# OpenAI Codex OAuth via Pi's openai-codex provider
claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark -p "hello"

# Live viewer is enabled by default
claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark -p "hello"

# Read-only tool capture
claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark --tools bash -p "Run pwd"

Pi stores OAuth credentials in ~/.pi/agent/auth.json after /login. If you keep Pi credentials in another directory, set PI_CODING_AGENT_DIR before launching claude-tap.

Hermes Agent examples

Hermes Agent is a multi-provider Python AI agent (Nous Portal, OpenRouter, NVIDIA NIM, Xiaomi MiMo, GLM, Kimi, MiniMax, Hugging Face, OpenAI, Anthropic, custom). Because it can talk to any of these providers — and httpx / requests both honor HTTPS_PROXY natively — claude-tap defaults to forward proxy mode for hermes: it injects HTTPS_PROXY plus the local CA into the child process so any provider is captured.

# Interactive TUI — the recommended way for local trace capture.
claude-tap --tap-client hermes

# Gateway mode — captures LLM calls triggered by incoming platform messages (Slack, Telegram, etc.).
# Requires a messaging platform configured in ~/.hermes/.env.
# claude-tap auto-rewrites `gateway start` → `gateway run` so the gateway runs in the
# foreground and inherits HTTPS_PROXY; without this, the daemon spawned by systemd/launchd
# would not go through the proxy and no traces would be recorded.
claude-tap --tap-client hermes -- gateway start

# Reverse mode is opt-in and only useful when ~/.hermes is configured with an
# OpenAI-compatible provider that reads OPENAI_BASE_URL.
claude-tap --tap-client hermes --tap-proxy-mode reverse

Note: Gateway mode only produces traces when a configured messaging platform (Slack, Telegram, etc.) delivers a message to the bot. Without an active platform integration, the gateway makes no LLM calls and no traces are recorded.

Cursor CLI examples

Cursor CLI uses forward proxy mode by default. Use --model auto on free plans, and omit --mode ask when you want tool calls.

claude-tap --tap-client cursor -- -p --trust --model auto "hello"
claude-tap --tap-client cursor -- -p --trust --model auto --continue "continue"

Guides and Integrations

• OpenClaw setup guide for integrating claude-tap with OpenClaw. Simplified Chinese version: OpenClaw 设置指南.
• Claude Code with DeepSeek API for routing Claude Code through DeepSeek's Anthropic-compatible API. Simplified Chinese version: Claude Code 搭配 DeepSeek API.
• Client support matrix for exact environment variables, proxy modes, and URL rewrite rules.

Qoder CLI examples

Qoder CLI talks to multiple Qoder endpoints, so claude-tap defaults to forward proxy mode for --tap-client qoder.

# Browser login, PAT, or job token must be configured before launch.
qodercli login

claude-tap --tap-client qoder -- -p "hello" --permission-mode dont_ask

Antigravity CLI examples

Antigravity CLI talks to multiple Google/Antigravity endpoints, so claude-tap defaults to forward proxy mode for --tap-client agy. Its Code Assist model API also honors CLOUD_CODE_URL; claude-tap injects that automatically so model requests such as /v1internal:streamGenerateContent are captured by the same local proxy.

On macOS, Antigravity may not honor per-process CA environment variables. claude-tap automatically trusts the local CA in your current user's login keychain on first agy launch. This does not use sudo or the System keychain, though macOS may prompt to unlock the login keychain.

claude-tap --tap-client agy --tap-live

# Optional: trust the CA separately before launching a forward-proxy client.
claude-tap trust-ca

CodeBuddy CLI examples

CodeBuddy uses reverse proxy mode by default. claude-tap auto-detects the upstream from CodeBuddy's own login cache (~/.codebuddy/local_storage/), so iOA / WeChat / Google-Github / Enterprise-Domain login modes all work without any extra flag. When the cache is missing (e.g. before first login), it falls back to https://copilot.tencent.com/v2.

# Auto-detected endpoint (works for all four login modes once logged in)
claude-tap --tap-client codebuddy

# Explicit override (e.g. external SaaS or staging)
claude-tap --tap-client codebuddy --tap-target https://www.codebuddy.ai/v2

# Or via environment variable
CODEBUDDY_BASE_URL=https://www.codebuddy.ai/v2 claude-tap --tap-client codebuddy -- -p "Reply OK"

Viewer, export, and advanced options

# Live viewer runs by default while a client runs
claude-tap

# Disable live viewer for scripts, CI, remote shells, or old behavior
claude-tap --tap-no-live

# Browse saved traces without launching a client
claude-tap dashboard

# Stop the shared dashboard service
claude-tap dashboard stop

# Regenerate a self-contained HTML viewer from JSONL
claude-tap export .traces/2026-02-28/trace_141557.jsonl -o trace.html

# Export a portable compact trace bundle, then render it later
claude-tap export <session-id> --format compact -o trace.ctap.json
claude-tap export trace.ctap.json -o trace.html

# Embed the exported viewer in an iframe with reduced chrome
# trace.html?embed=1&hideHeader=1&hidePath=1&hideHistory=1&hideControls=1&density=compact&theme=light

# Store traces in another directory, or keep fewer sessions
claude-tap --tap-output-dir ./my-traces
claude-tap --tap-max-traces 10

# Start only the proxy for custom setups
claude-tap --tap-no-launch --tap-port 8080

# Disable browser auto-open for live and generated viewers
claude-tap --tap-no-open

In proxy-only mode, start your client in another terminal and point its base URL or proxy settings at the local proxy. Use the client support matrix for exact wiring.

When used as VSCode Claude Code's claudeProcessWrapper, claude-tap honors the Claude binary path passed by the extension.

CLI Options

All flags are forwarded to the selected client, except these --tap-* ones:

--tap-client CLIENT      Client to launch/listen to: claude (default), agy, codex, codexapp, gemini, kimi, kimi-code, mimo, opencode, openclaw, pi, hermes, cursor, qoder, or codebuddy
--tap-target URL         Upstream API URL (default: auto per client)
--tap-live               Start real-time viewer while the client runs (default: on)
--tap-no-live            Disable the real-time viewer server (pre-v0.1.75 behavior)
--tap-live-port PORT     Port for live viewer server (default: auto)
--tap-no-open            Don't auto-open live or generated HTML viewers in a browser
--tap-output-dir DIR     Trace output directory (default: ./.traces)
--tap-port PORT          Proxy port (default: auto)
--tap-host HOST          Bind address (default: 127.0.0.1, or 0.0.0.0 in --tap-no-launch mode)
--tap-no-launch          Only start the proxy, don't launch client
--tap-max-traces N       Max trace sessions to keep (default: 50, 0 = unlimited)
--tap-store-stream-events Persist raw SSE/WebSocket event arrays during capture so viewer/export output can show them (default: off)
--tap-no-update-check    Disable PyPI update check on startup
--tap-no-auto-update     Check for updates but don't auto-download
--tap-proxy-mode MODE    Proxy mode: reverse or forward (default: reverse for claude/codex/kimi/kimi-code/openclaw/codebuddy, forward for agy/gemini/mimo/opencode/pi/hermes/cursor/qoder; codexapp is transcript-only)
--tap-trust-ca           On macOS, explicitly trust the local CA in the user login keychain before launch (agy does this automatically)

Viewer Features

Trace viewer capabilities

The viewer is a single self-contained HTML file (zero external dependencies):

• Structural diff — compare consecutive requests to see exactly what changed: new/removed messages, system prompt diffs, character-level inline highlighting
• Path filtering — filter by API endpoint (e.g., /v1/messages only)
• Model grouping — sidebar groups requests by model, with Claude-family priority ordering
• Token usage breakdown — input / output / cache read / cache creation
• Tool inspector — expandable cards with tool name, description, and parameter schema
• Search — full-text search across messages, tools, prompts, and responses
• Dark mode — toggle light/dark themes (respects system preference)
• Iframe embed mode — add query parameters such as embed=1, hideHeader=1, hidePath=1, hideHistory=1, hideControls=1, density=compact, and theme=light|dark
• Keyboard navigation — j/k or arrow keys
• Copy helpers — one-click copy of request JSON or cURL command
• i18n — English, 简体中文, 日本語, 한국어, Français, العربية, Deutsch, Русский

Architecture

How it works

How it works:

1. claude-tap starts a reverse or forward proxy and spawns the selected client
2. Base URL clients are pointed at the reverse proxy; clients without base URL support use proxy/CA environment variables
3. SSE and WebSocket streams are forwarded as chunks/messages arrive with low proxy overhead
4. Each request-response pair or WebSocket session is recorded to local trace storage; raw SSE/WebSocket event arrays are omitted by default and must be captured with --tap-store-stream-events if you need them later in viewer/export output
5. On exit, a self-contained HTML viewer is generated
6. Live mode is enabled by default and broadcasts updates to the browser via SSE

Key features: 🔒 Common auth headers auto-redacted · ⚡ Low-overhead streaming · 📦 Self-contained viewer · 🔄 Real-time live mode

Community

Ecosystem

• 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.

Star History

Contributors

Thanks goes to these contributors:

liaohch3 💻 📖 🚧 ⚠️	BKK 💻	YoungCan-Wang 💻	0xkrypton 💻	CYJiang 💻	陈展鹏 📖	devtalker 💻
Yaguang Ding 💻	Sephy 💻

Contributing

Contributions are welcome. Start with CONTRIBUTING.md.

License

MIT