claude-tap

PyPI distribution: claw-tap · source: passionke/claude-tap

中文文档

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

OpenClaw: If you are Openclaw and integrating claude-tap with OpenClaw, also read the dedicated setup guide.

Install

Requires Python 3.11+ and the CLI you want to trace: Claude Code, Codex CLI, OpenCode, or Cursor CLI.

# Recommended
uv tool install claw-tap

# Or with pip
pip install claw-tap

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

Docker / server runtime (Rust)

Container images and the long-running proxy+live server are built from the Rust binary (crates/claude-tap). See docs/rust-backend.md and docs/deploy-compose.md. Live history is loaded on demand via Load from disk (no server-side SSE RAM buffer).

cargo build --release -p claude-tap
# or: docker compose up --build

Usage

Claude Code

# Basic — launch Claude Code with tracing
claude-tap

# Live mode — watch API calls in real-time in browser
claude-tap --tap-live

# Pass any 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

# Full-power combo: live viewer + skip permissions + specific model
claude-tap --tap-live -- --dangerously-skip-permissions --model claude-sonnet-4-6

Codex CLI

Codex CLI supports two authentication modes with different upstream targets:

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

Cursor CLI

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

# 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/sessions/*/trace.html

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

claude-tap export .traces/sessions/<storage-slug>/trace.jsonl -o trace.html
# or:
claude-tap export .traces/sessions/<storage-slug>/trace.jsonl --format html

Traces are only recorded when requests include a claw-session-id header. Session metadata and listing use claude_tap_sessions.sqlite3 next to the trace files.

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

Claw gateway mode (PostgreSQL)

For claw-code stack integration, set CLAW_CLUSTER_ID and CLAW_GATEWAY_DATABASE_URL so tap reads the active LLM URL and API key from the same PostgreSQL as http-gateway-rs. Workers point OPENAI_BASE_URL at tap; tap injects the DB-managed key when calling the real LLM (client auth headers are not forwarded).

export CLAW_CLUSTER_ID=local-dev
export CLAW_GATEWAY_DATABASE_URL=postgres://claw_gateway:secret@postgres:5432/claw_gateway

claude-tap --tap-no-launch --tap-host 0.0.0.0 --tap-port 8080 --tap-client codex

See docs/claw-tap-gateway-mode.md and docs/deploy-compose.md.

Run claude-tap --help for all options. Flags that are not --tap-* are forwarded to the selected client.

Viewer Features

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:

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 (with claw-session-id) is appended to sessions/{slug}/trace.jsonl, indexed in SQLite
5. On exit, a self-contained HTML viewer is generated per session trace file
6. Live mode (optional) broadcasts updates to the browser via SSE; pick a session with ?session= matching the header value

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

Community

Star History

Contributing

Issues and pull requests: passionke/claude-tap. See CONTRIBUTING.md.

License

MIT — see LICENSE.

This repository is a fork of liaohch3/claude-tap. The MIT license requires retaining the upstream copyright notice in LICENSE; fork-specific changes are maintained under passionke/claude-tap and published on PyPI as claw-tap.