claude-tap

claude-tap is an open-source local proxy and trace viewer for AI coding agents, built in Python and published on PyPI under the MIT license. It sits between your AI coding agent CLI and its upstream API, recording every request and response so you can inspect the real traffic in a self-contained browser-based viewer. The project was created by liaohch3 and has attracted community contributions from nine contributors.

What It Is

claude-tap is a developer observability tool for AI coding agents. It acts as either a reverse proxy (intercepting traffic by rewriting the client's base URL) or a forward proxy (injecting HTTPS_PROXY and a local CA certificate) depending on the client. Once traffic flows through it, claude-tap records system prompts, conversation history, tool schemas, tool calls, streaming responses, token usage, and request diffs — then renders everything in a zero-dependency self-contained HTML viewer. The core use case is debugging agent behavior with evidence: you can compare adjacent requests to see exactly which prompt, message, tool, or parameter changed between turns.

Supported Clients

claude-tap supports a wide range of AI coding agent CLIs and apps through a unified --tap-client flag:

• Claude Code — Anthropic API, AWS Bedrock, Google Vertex AI, and compatible gateways (DeepSeek, GLM, CC Switch)
• Codex CLI / Codex App — OpenAI API key mode and ChatGPT subscription OAuth; Codex App sessions imported from local JSONL files
• Gemini CLI — Google OAuth and Code Assist traffic via forward proxy
• Kimi CLI / Kimi Code CLI — Moonshot AI endpoints
• MiMo Code — OpenCode fork with multi-provider support from Xiaomi
• OpenCode — multi-provider terminal AI assistant
• OpenClaw — multi-provider sessions
• Pi — multi-provider coding agent including OpenAI Codex OAuth
• Hermes Agent — multi-provider Python agent (Nous Portal, OpenRouter, NVIDIA NIM, and others)
• Cursor CLI — Cursor Agent sessions via forward proxy
• Qoder CLI, Antigravity CLI, CodeBuddy CLI — additional forward-proxy clients

Viewer and Architecture

The trace viewer is a single self-contained HTML file with zero external dependencies. Key viewer capabilities include:

• Structural diff — character-level inline highlighting of what changed between consecutive requests
• 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, and cache creation
• Tool inspector — expandable cards with tool name, description, and parameter schema
• Full-text search — across messages, tools, prompts, and responses
• Dark mode — respects system preference
• Iframe embed mode — query parameters for embed, hideHeader, hidePath, hideHistory, hideControls, density, and theme
• Keyboard navigation — j/k or arrow keys
• i18n — English, Simplified Chinese, Japanese, Korean, French, Arabic, German, Russian

Architecturally, claude-tap starts a proxy, spawns the selected client, forwards SSE and WebSocket streams with low overhead, records each request-response pair to local JSONL trace storage, and generates the HTML viewer on exit. Live mode (enabled by default since v0.1.75) broadcasts updates to the browser via SSE while the agent runs.

Privacy and Portability

All traces are stored locally — no hosted dashboard is required. Common auth headers are automatically redacted before recording. Each run produces a portable trace session that can be exported to a self-contained HTML file for sharing or archiving, or to a compact .ctap.json bundle for later rendering. The --tap-output-dir and --tap-max-traces flags control where traces are stored and how many sessions are retained.

Update: v0.1.124

The latest release is v0.1.124, published on 2026-06-28. The project has been actively developed since its creation in February 2026, with the repository showing 2,237 stars and 211 forks. Recent development has expanded client support to include Antigravity CLI, CodeBuddy CLI, MiMo Code, Pi, Hermes Agent, and Cursor CLI, and introduced the live viewer server (enabled by default as of v0.1.75) that streams trace updates to the browser in real time during an agent run. The ecosystem has also grown to include Phistory, a community project that uses claude-tap's capture-only prompt export to archive versioned system prompt snapshots.