# claude-tap

> A local proxy and trace viewer for AI coding agents that intercepts and inspects API traffic from Claude Code, Codex CLI, Gemini CLI, Cursor CLI, and more.

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.

## Features
- Local reverse and forward proxy for AI coding agent CLIs
- Real-time live viewer via SSE while agent runs
- Structural diff between consecutive requests with character-level highlighting
- Inspect system prompts, conversation history, tool schemas, tool calls, and streaming responses
- Token usage breakdown (input, output, cache read, cache creation)
- Self-contained zero-dependency HTML trace viewer export
- Compact .ctap.json portable trace bundle export
- Full-text search across messages, tools, prompts, and responses
- Dark mode and light mode with system preference detection
- Iframe embed mode with query parameter controls
- Keyboard navigation (j/k or arrow keys)
- i18n support: English, Chinese, Japanese, Korean, French, Arabic, German, Russian
- Auth headers auto-redacted before recording
- Path filtering by API endpoint
- Model grouping in sidebar with Claude-family priority ordering
- Support for AWS Bedrock (SigV4 and gateway modes)
- Support for Google Vertex AI pass-through gateways
- Forward proxy mode with local CA injection for multi-provider clients
- Codex App local JSONL session listener with CDP WebSocket enrichment
- CLI flag --tap-client to select among 14+ supported clients

## Integrations
Claude Code, Codex CLI, Codex App, Gemini CLI, Kimi CLI, Kimi Code CLI, MiMo Code, OpenCode, OpenClaw, Pi, Hermes Agent, Cursor CLI, Qoder CLI, Antigravity CLI, CodeBuddy CLI, AWS Bedrock, Google Vertex AI, DeepSeek API, OpenAI API, Anthropic API, Moonshot AI, Phistory

## Platforms
WINDOWS, MACOS, WEB, API, VSC_EXTENSION, CLI

## Pricing
Open Source

## Version
v0.1.124

## Links
- Website: https://liaohch3.com/claude-tap/
- Documentation: https://liaohch3.com/claude-tap/guides/agent-trace-viewer.html
- Repository: https://github.com/liaohch3/claude-tap
- EveryDev.ai: https://www.everydev.ai/tools/claude-tap