What it is

claude-tap is a local proxy and trace viewer for AI coding agents. It allows you to run your CLI through it or listen to local 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.

How it works

The project acts as a local proxy that captures traffic between various coding agents (e.g., Claude Code, Codex CLI, Gemini CLI, Cursor CLI, OpenCode, Kimi/Kimi Code, Pi, Hermes) and their upstream services. It records HTTP/SSE traffic and provides a trace viewer to compare prompts, messages, tool calls, and parameter changes across requests. It supports forward and reverse proxy modes and can decode specialized traffic formats (e.g., Vertex rawPredict, AWS Bedrock responses).

Getting started

Install

# 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

# 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 backend request capture
claude-tap --tap-client codexapp

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

# Grok Build CLI
claude-tap --tap-client grok -- -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

<details> <summary>Claude Code examples</summary> ```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 environment variables 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 upstream, claude-tap detects that value from Claude settings and records traffic before forwarding it upstream. Use `claude-tap` in place of `claude`; no separate `--tap-client` value is needed.

For the Claude Code VS Code extension, set `Claude Code: Claude Process Wrapper` to `claude-tap`.

</details> <details> <summary>Claude Code with DeepSeek API</summary>

Full English guide: Claude Code with 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.

</details>

<details>
<summary>Claude Code with AWS Bedrock</summary>

`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="<your gateway token in Bedrock>"
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.

</details>

<details>
<summary>Codex CLI auth modes and examples</summary>

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

```bash
# 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

</details>

<details>
<summary>Codex App backend capture examples</summary>

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` (bundle id `com.openai.codex`); older standalone `Codex.app` installs are still recognized. Non-model product traffic is relayed but not persisted as trace rows. On macOS, claude-tap trusts its local CA in the current user's login keychain when needed so the bundled app-server can connect through the proxy.

```bash
# Launch Codex App (ChatGPT.app or Codex.app) and inspect captured backend requests
claude-tap --tap-client codexapp

# Keep raw WebSocket/SSE event arrays in the trace
claude-tap --tap-client codexapp --tap-store-stream-events

# Override the executable when the app is installed outside the default locations
CODEX_APP_EXECUTABLE=/path/to/ChatGPT.app/Contents/MacOS/ChatGPT claude-tap --tap-client codexapp

If Codex/ChatGPT App is already running, claude-tap launches an isolated second instance with a dedicated --user-data-dir under ~/.claude-tap/codex-app-profiles/tap so your current window keeps working. You may need to sign in again in the tapped window. Override the profile with CODEX_APP_USER_DATA_DIR. This mode records live backend traffic instead of importing local session JSONL transcripts.

</details>

<details>
<summary>Kimi CLI examples</summary>

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.

```bash
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 -- --model <model-name>