claude-tap

Exploring Claude-tap: A Local Proxy and Trace Viewer for AI Coding Agents

Claude-tap is more than a tool; it’s a bridge between AI coding agents and transparent, private, and auditable interactions. Built as a local proxy and a rich trace viewer, claude-tap lets developers run their CLI-based AI assistants through a single, auditable conduit. It captures system prompts, conversation history, tool schemas, tool calls, streaming responses, token usage, and request diffs. Best of all, it does this locally, without pushing your data to a hosted dashboard, and it presents the results in a portable HTML viewer you can export and share. This article dives into what claude-tap does, how it works, and how you can start using it with a wide range of AI coding agents.

A Window into AI Conversations: What claude-tap Does

At its core, claude-tap acts as a local intermediary that you run in front of AI agents. You launch your chosen client (for example Claude Code, Codex CLI, Gemini CLI, or Qoder CLI) and direct its traffic through claude-tap. The proxy then records every request and response, including the prompts, messages, tool calls, results, and even the streaming responses where available. The output is a self-contained HTML viewer—an artifact you can save, archive, or reopen later to inspect the entire session without needing a live dashboard.

Key features you’ll encounter include:

• Exact context visibility: See prompts, messages, tool definitions, tool calls, and the results returned by the AI. You can reconstruct the streaming response step by step and inspect how tokens and flows evolve as the conversation progresses.
• Evidence-based debugging: Compare adjacent requests to identify precisely what changed—whether it’s a prompt variation, a different tool call, or a modified parameter. This makes debugging behavior deterministic and reproducible.
• Portable session artifacts: Each run produces a self-contained HTML viewer you can export. It’s easy to share a complete trace with teammates or store it for compliance and audit purposes.
• Local-first privacy: All traces live on your machine. No hosted dashboard is required, and sensitive headers can be redacted to protect your credentials.
• One workflow across clients: Claude-tap supports a broad ecosystem of AI agents and CLIs, letting you use a unified workflow across Claude Code, Codex CLI, Gemini CLI, Kimi CLI, OpenCode, Pi, Hermes Agent, Cursor CLI, Qoder CLI, Antigravity, and CodeBuddy.

A Glimpse of the Interface: Visuals You’ll See

To illustrate the experience, claude-tap ships with live visuals that help you study traces as they unfold:

• A demo GIF showing a real Codex trace in action. It captures the live proxy in operation and how requests appear in the viewer as they’re recorded.
• Light and dark mode viewer screenshots to support long review sessions:
• Light mode trace viewer
• Dark mode trace viewer
• A structured diff modal that highlights what changed between adjacent requests, making it easier to spot the exact differences in prompts, messages, or tool usage.

Claude-tap demo showing a real Codex trace

Light mode trace viewer Light viewer overview

Dark mode trace viewer Dark mode for long review sessions

Structured diff modal Structured diff across adjacent requests

Why Use claude-tap? The Value Proposition

• See the exact context: You deserve full visibility into what the AI sees and how it responds. With claude-tap, you can inspect every layer of the interaction—system prompts, messages, tool schemas, tool calls, and the real-time streaming outputs that follow.
• Debug with evidence: When an answer behaves unexpectedly, you can compare neighboring turns and pinpoint which prompt, message, tool, or parameter drifted. This is invaluable for diagnosing flaky behavior or tuning your setup.
• Portable and shareable: A completed trace becomes a self-contained HTML document you can distribute or archive without depending on a live system.
• Localized security posture: Since traces never need to leave your machine for viewing, your sensitive data stays under your control. Traces can be redacted at rest to minimize exposure.
• Consistent workflow across AI agents: Whether you’re using Claude Code, Codex CLI, Gemini, Kimi, OpenCode, Pi, Hermes, Cursor, Qoder, Antigravity, or CodeBuddy, claude-tap harmonizes the way you inspect traffic and tool interactions.

Supported Clients: A Unified Front Across AI Agents

Claude-tap is designed to work with a broad spectrum of AI coding agents. Rather than presenting a static table, here is a concise, developer-friendly summary of the major clients you can trace with claude-tap, along with typical use cases and notes:

• Claude Code: The Claude family’s coding-focused interface. Use claude-tap with Claude Code to inspect live API traffic and to view the end-to-end context of code-oriented prompts. Claude Code can be driven through Anthropic gateways like DeepSeek, and claude-tap can adapt upstream targets automatically.
• Codex CLI: The OpenAI Codex CLI experience. Depending on your authentication mode (OAuth for ChatGPT subscriptions or an API key), claude-tap auto-detects the appropriate upstream. You can also override the upstream explicitly if needed.
• Gemini CLI: Google’s Gemini Code Assist traffic. claude-tap supports forward proxy capture by default, and you can tailor the proxy settings for specialized workflows.
• Kimi CLI: Moonshot/Open Platform-based code assistance. claude-tap supports forward proxy mode and can be directed to Moonshot’s Code API if you want a different upstream target.
• OpenCode: A multi-provider terminal AI assistant. claude-tap defaults to forward proxy mode so traffic to any provider is captured, with live viewing enabled by default.
• Pi: A multi-provider coding agent. claude-tap defaults to forward proxy mode, capturing OAuth providers like OpenAI Codex and other model registries. You can adjust the model and other flags as needed.
• Hermes Agent: A multi-provider AI agent. claude-tap leverages forward proxy mode to capture calls from Hermes, which can route through multiple backends (Nous Portal, OpenRouter, NVIDIA NIM, etc.).
• Cursor CLI: A user-friendly CLI that captures Cursor Agent sessions with readable local transcripts. Forward proxy mode by default, with options to adjust trust and model behavior.
• Qoder CLI: Interacts with multiple Qoder endpoints. claude-tap defaults to forward proxy mode for comprehensive traffic capture, with credentials configured for login or tokens.
• Antigravity CLI: Google/Antigravity endpoints and Code Assist models. claude-tap supports the forward proxy approach and can accommodate model API variations and per-provider payload changes.
• CodeBuddy CLI: Tencent’s CodeBuddy service. claude-tap defaults to a forward proxy mode and can auto-detect CodeBuddy’s upstream from its login caches, with options to override when needed.

Install and Get Running: Prerequisites and Quick Setup

Before you begin, you’ll want to make sure you have the right environment. claude-tap requires Python 3.11 or newer and the client you intend to trace. The installation is straightforward and designed to be as frictionless as possible.

• Prerequisites

• Python 3.11+ installed on your system

• The target client you want to inspect (Claude Code, Codex CLI, Gemini CLI, etc.)

• Installation (recommended flow)

• Install claude-tap via the Python package manager:

  • curl alternatives exist, but a typical setup is:
  • pip install claude-tap

• If you’re upgrading later, you can use:

  • claude-tap update
  • uv tool upgrade claude-tap
  • pip install --upgrade claude-tap

• Quick-start commands

• Run Claude Code with the live browser viewer enabled by default:

  • claude-tap

• If you want to restore pre-v0.1.75 behavior (no live viewer server), use:

  • claude-tap --tap-no-live

• Environment variable tips

• Claude Code upstreams can be auto-detected from ANTHROPICBASEURL in your environment or Claude settings. You can override targets with:

  • claude-tap --tap-target

A glance at sample setups for popular clients

• Claude Code

• Default: claude-tap runs Claude Code with live viewer

• For explicit Claude Code upstreams (e.g., DeepSeek), you can set an ANTHROPICBASEURL and a targeted model

• Codex CLI

• OAuth users (ChatGPT subscription): automatic detection after codex login

• API Key users: use the standard OpenAI API target

• Optional flags to force specific models or auto approvals

• Kimi, Gemini, OpenCode, Pi, Hermes, Cursor, Qoder, Antigravity, CodeBuddy

• Each client has its own default proxy mode (forward or reverse) and typical usage patterns

• claude-tap provides straightforward commands to switch between modes, specify targets, and tailor prompts or tool usage

Live Viewing: How the Viewer Helps You Understand

The viewer is a powerful companion to the raw trace data. Here are some highlights of what you can do with it:

• Structural diff: Compare consecutive requests side by side and see exactly what changed in prompts, messages, or tool calls. Inline highlighting surfaces even tiny edits.
• Path filtering: Narrow the view to a particular API endpoint (for example, focusing on /v1/messages) to reduce noise.
• Model grouping: A sidebar clusters requests by model, ensuring you can trace how Claude-family models are performing relative to others.
• Token usage breakdown: Separate input tokens, output tokens, cache reads, and cache writes to understand cost and efficiency.
• Tool inspector: Expand tool cards to reveal tool names, descriptions, and parameter schemas. It’s a quick way to verify what tools are being invoked.
• Search: Full-text search across all messages, tools, prompts, and responses, making it easy to locate a specific request or tool usage.
• Dark mode: Toggle between light and dark themes, with attention to accessibility and comfort during long review sessions.
• Iframe embed options: When embedding the viewer in other contexts, you can pass query parameters like embed=1, hideHeader=1, hidePath=1, hideHistory=1, hideControls=1, density=compact, and theme=light|dark.
• Keyboard navigation: Move through traces with j/k or the arrow keys for quick scanning.
• Copy helpers: One-click copies of request JSON or cURL commands make it easy to recreate interactions or share slices of a trace.
• Internationalization: Out-of-the-box i18n support includes English, 简体中文, 日本語, 한국어, Français, العربية, Deutsch, Русский.

Architecting the Flow: How claude-tap Works Under the Hood

Architecture is the backbone of claude-tap’s reliability and low overhead. Here’s how the pieces fit together:

• The proxy and client launch: claude-tap starts a reverse or forward proxy and spawns the selected client. The client’s base URL is pointed at the proxy, or, when the client has no simple base URL, env vars and CA settings route traffic through the proxy.
• Streaming and capture: SSE and WebSocket streams are forwarded to the trace in real time, with minimal overhead. The proxy captures each request and response pair, including WebSocket sessions, while providing optional storage of raw stream events for advanced viewers.
• Self-contained viewer generation: On exit, claude-tap produces a self-contained HTML viewer that can be opened offline or shared with teammates.
• Live mode: Live updates are broadcast to the browser using SSE, enabling a real-time inspection experience during an agent run.
• Security posture: Common authentication headers are redacted to prevent accidental exposure of secrets in traces.

A central architectural image helps visualize these ideas:

Architecture How it works — How claude-tap starts, proxies, and renders the viewer

Community, Contributors, and the Path Forward

Claude-tap isn’t just a tool; it’s a community endeavor. The project maintains an active set of contributors and a growing star history that demonstrates community interest over time.

• Star history: A live view of the project’s popularity provides a snapshot of how the project is received by users and contributors over time. Star History Chart

• Contributors: A diverse group of developers has contributed to claude-tap, including core maintainers and independent contributors. The contributor list is displayed in the project’s repository and highlights a wide range of involvement, from code to documentation and maintenance.

• Licensing: claude-tap is released under the MIT license, inviting contribution and adoption across a broad community of developers who want transparent AI tooling.

Contributing and Getting Involved

The project welcomes contributions. If you’d like to contribute, start by reviewing the contribution guidelines and the contributing document. Whether you want to improve the viewer, enhance proxy modes, expand client support, or refine the documentation, your input helps the project evolve.

A Closer Look at Guides and Integrations

Claude-tap extends beyond a single workflow by offering guides and integrations that connect it to broader ecosystems:

• OpenClaw setup guide: Integrate claude-tap with OpenClaw. There’s a Simplified Chinese version available for Chinese-speaking users.

• OpenClaw 设置指南: docs/guides/OPENCLAW_README.md

• Simplified Chinese: OpenClaw 设置指南 (docs/guides/OPENCLAW_README.zh.md)

• Claude Code with DeepSeek API: For routing Claude Code through DeepSeek’s Anthropic-compatible API. A Simplified Chinese version is also provided for ease of use across language contexts.

• Claude Code with DeepSeek API: docs/guides/deepseek-claude-code.md

• Simplified Chinese: Claude Code 搭配 DeepSeek API (docs/guides/deepseek-claude-code.zh.md)

• Client support matrix: A detailed reference for exact environment variables, proxy modes, and URL rewrite rules. This is your go-to guide for the nitty-gritty of each client integration.

• Qoder, Antigravity, and CodeBuddy: Each of these clients has special considerations due to the multi-endpoint nature of their ecosystems. claude-tap’s documented examples guide you through:

• Qoder CLI: Forward proxy defaults and login/token requirements.

• Antigravity CLI: Forward proxy defaults; special handling for CLOUDCODEURL and per-provider endpoints.

• CodeBuddy CLI: Reverse proxy defaults and automatic upstream detection from CodeBuddy caches.

A Note on Live Viewing and Exporting

Claude-tap’s live viewer is designed to be both convenient and robust. While the live session is active, you can examine each piece of traffic in real time. When the session completes, you’ll have a compact HTML artifact you can store and share. Additionally, you can export traces and re-import them into the viewer for later analysis.

• Export options: You can export trace data to a self-contained HTML viewer and view it offline.
• Embedding: The viewer supports iframe embedding with optional chrome suppression, allowing you to integrate traces into dashboards or internal wikis.

Practical Examples: Quick Start Scenarios

• Getting started with Claude Code:
• claude-tap
• Expect to see a live browser viewer by default.
• Quick override for no live viewer:
• claude-tap --tap-no-live
• Using Codex CLI with a specific target:
• claude-tap --tap-client codex --tap-target https://chatgpt.com/backend-api/codex
• Using Pi with a particular model:
• claude-tap --tap-client pi -- --model openai-codex/gpt-5.3-codex-spark -p "hello"

A Visual Tour of a Few Key Elements

• The live demo GIF demonstrates the end-to-end flow, from proxy to viewer, including how a real Codex trace appears in the browser.
• The light and dark viewer images show how the interface adapts to different viewing environments and how users can toggle themes for readability.
• The structured diff modal image illustrates how the viewer highlights changes between consecutive requests, providing a crisp way to track evolution in prompts and tool usage.

Imagery recap

• Claude-tap demo showing a real Codex trace
• Light mode trace viewer
• Dark mode trace viewer
• Structured diff modal
• Architecture
• Star History Chart

A Summary of What You’ll Gain

• Confidence in AI interactions: By inspecting the exact prompts, messages, and tool usage, you’ll understand how your AI agents arrived at their conclusions.
• Reproducibility: The ability to export a complete trace into a portable HTML file means you can recreate the exact session later or share it with colleagues for review.
• Privacy-aware workflows: Local traces with redaction help you keep sensitive information under your control while still enabling thorough debugging and auditing.
• Cross-client consistency: A single workflow across Claude Code, Codex CLI, Gemini CLI, Kimi CLI, OpenCode, Pi, Hermes Agent, Cursor CLI, Qoder CLI, Antigravity, and CodeBuddy simplifies tooling decisions and reduces cognitive overhead.

Conclusion: Embracing Transparent AI Debugging

Claude-tap is a thoughtful response to the need for transparent, auditable, and portable AI debugging tooling in code-oriented workflows. By acting as a local proxy and a rich, self-contained viewer, claude-tap empowers developers to observe, understand, and refine AI agent behavior across a diverse set of clients. The combination of live tracing, structural diffs, token usage analysis, and a portable HTML artifact makes claude-tap an indispensable companion for anyone who wants to understand how AI assistants interpret prompts, decide on actions, and interact with tools in real time.

If you’re exploring AI coding assistants, claude-tap offers a practical path to greater clarity and control. Start with a simple setup, try with Claude Code or Codex CLI, and then experiment with other clients as you broaden your tooling. The journey from raw API traffic to an elegant, readable trace viewer is empowering—and with claude-tap, that journey remains local, private, and repeatable.

License and Contribution

Claude-tap is released under the MIT license. Contributions are encouraged and welcomed. If you’re curious about contributing, check out the repository’s contributing guide for how to get started, file issues, or propose enhancements.

Images and visuals have been included from the input to illustrate the key concepts and user experiences described in this blog post:

• Demo gif and viewer screenshots provide a visual reference for real use.
• Architecture diagram clarifies the flow of proxying, recording, and viewer generation.
• Star history image highlights community engagement with the project.

In short, claude-tap is a powerful, user-friendly way to observe and audit AI coding agent interactions locally. It’s designed to be extensible, compatible with a broad range of clients, and accessible to developers who want to bring transparency to automated code assistance. Whether you’re debugging a tricky prompt, validating a tool invocation, or simply documenting an AI session for archival purposes, claude-tap gives you a clear, portable, and private view of what your AI agents are doing behind the scenes.