claude-tap 0.1.63

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

claude-tap

中文文档

Intercept and inspect all API traffic from Claude Code, Codex CLI, Gemini CLI, Kimi CLI, OpenCode, Hermes Agent, or Cursor CLI. See exactly how they construct system prompts, manage conversation history, select tools, and use tokens — in a beautiful trace viewer.

Dark Mode / Diff View

OpenClaw: If you are integrating claude-tap with OpenClaw, read the OpenClaw setup guide. Simplified Chinese version: OpenClaw 设置指南.

Install

Requires Python 3.11+ and the client you want to trace: Claude Code (default), Codex CLI for --tap-client codex, Gemini CLI for --tap-client gemini, Kimi CLI for --tap-client kimi, OpenCode for --tap-client opencode, Hermes Agent for --tap-client hermes, or Cursor CLI for --tap-client cursor.

# Recommended
uv tool install claude-tap

# Or with pip
pip install claude-tap

Upgrade: uv tool upgrade claude-tap or pip install --upgrade claude-tap

Quick Start

Run the client you want to inspect through claude-tap:

# Claude Code
claude-tap

# Claude Code with live browser viewer
claude-tap --tap-live

# Codex CLI
claude-tap --tap-client codex

# Gemini CLI
claude-tap --tap-client gemini -- -p "hello"

# Kimi CLI
claude-tap --tap-client kimi

# Cursor CLI
claude-tap --tap-client cursor -- -p --trust --model auto "hello"

Flags that are not --tap-* are forwarded to the selected client after --.

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 + skip permissions + specific model
claude-tap --tap-live -- --dangerously-skip-permissions --model claude-sonnet-4-6

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

claude-tap \
  --tap-proxy-mode reverse \
  --tap-target https://api.deepseek.com/anthropic \
  -- --permission-mode bypassPermissions

Set ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic only for direct Claude Code usage. When capturing with claude-tap, use --tap-target for the DeepSeek upstream.

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
claude-tap --tap-client codex --tap-live -- --full-auto

Kimi CLI examples

Kimi CLI uses reverse proxy mode by default through KIMI_BASE_URL. Use your existing Kimi CLI auth/config; the default upstream target is the Kimi Code API.

claude-tap --tap-client kimi
claude-tap --tap-client kimi -- --thinking

# Use Moonshot Open Platform instead of Kimi Code
claude-tap --tap-client kimi --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
claude-tap --tap-client gemini --tap-live -- -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

# With live viewer
claude-tap --tap-client opencode --tap-live

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

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 --tap-live

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

Browser preview, export, and proxy-only mode

# Disable auto-open of HTML viewer after exit (on by default)
claude-tap --tap-no-open

# Live mode — real-time viewer opens in browser while client runs
claude-tap --tap-live
claude-tap --tap-live --tap-live-port 3000    # fixed port for live viewer

# Standalone dashboard — browse trace history without launching a client
claude-tap dashboard
claude-tap dashboard --tap-output-dir ./my-traces --tap-live-port 3000

When the client exits, you can also manually open the generated viewer:

open .traces/*/trace_*.html

You can also regenerate a self-contained HTML viewer from an existing JSONL trace:

claude-tap export .traces/2026-02-28/trace_141557.jsonl -o trace.html
# or:
claude-tap export .traces/2026-02-28/trace_141557.jsonl --format html

Proxy-only mode

Start the proxy without launching a client — useful for custom setups or connecting from a separate terminal:

# Claude Code
claude-tap --tap-no-launch --tap-port 8080
# In another terminal:
ANTHROPIC_BASE_URL=http://127.0.0.1:8080 claude

# Codex CLI (OAuth)
claude-tap --tap-client codex --tap-target https://chatgpt.com/backend-api/codex --tap-no-launch --tap-port 8080
# In another terminal:
OPENAI_BASE_URL=http://127.0.0.1:8080/v1 codex -c 'openai_base_url="http://127.0.0.1:8080/v1"'

# Codex CLI (API Key)
claude-tap --tap-client codex --tap-no-launch --tap-port 8080
# In another terminal:
OPENAI_BASE_URL=http://127.0.0.1:8080/v1 codex -c 'openai_base_url="http://127.0.0.1:8080/v1"'

# Kimi CLI
claude-tap --tap-client kimi --tap-no-launch --tap-port 8080
# In another terminal:
KIMI_BASE_URL=http://127.0.0.1:8080 kimi

# Gemini CLI (reverse mode only)
claude-tap --tap-client gemini --tap-proxy-mode reverse --tap-no-launch --tap-port 8080
# In another terminal:
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8080 GOOGLE_VERTEX_BASE_URL=http://127.0.0.1:8080 gemini

Common Combos

# Trace Claude Code with live viewer and auto-accept
claude-tap --tap-live -- --dangerously-skip-permissions

# Trace Codex (OAuth) with live viewer and full auto
claude-tap --tap-client codex --tap-target https://chatgpt.com/backend-api/codex --tap-live -- --full-auto

# Save traces to a custom directory
claude-tap --tap-output-dir ./my-traces

# Keep only the last 10 trace sessions
claude-tap --tap-max-traces 10

CLI Options

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

--tap-client CLIENT      Client to launch: claude (default), codex, gemini, kimi, opencode, hermes, or cursor
--tap-target URL         Upstream API URL (default: auto per client)
--tap-live               Start real-time viewer (auto-opens browser)
--tap-live-port PORT     Port for live viewer server (default: auto)
--tap-no-open            Don't auto-open HTML viewer after exit (on by default)
--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-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, forward for gemini/opencode/hermes/cursor)

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)
• 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 a dated trace_*.jsonl
5. On exit, a self-contained HTML viewer is generated
6. Live mode (optional) broadcasts updates to browser via SSE

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

Community

Star History

Contributors

Thanks goes to these contributors:

liaohch3 💻 📖 🚧 ⚠️

BKK 💻

YoungCan-Wang 💻

0xkrypton 💻

CYJiang 💻

陈展鹏 📖

Contributing

Contributions are welcome. Start with CONTRIBUTING.md.

License

MIT