What Is Claude Tap? A Simple Guide to AI Agent Trace Debugging

What Is Claude Tap? A Simple Guide to liaohch3/claude-tap for AI Agent Trace Debugging

Image extracted from the official liaohch3/claude-tap repository, file docs/viewer-light.png. This is a PNG image, not SVG.¹

Quick summary

claude-tap is a local proxy and trace viewer for AI coding agents. The official README describes it as a tool that lets you run an AI CLI through a proxy and inspect real API traffic: system prompts, conversation history, tool schemas, tool calls, streaming responses, token usage and request diffs.²

In plain terms: when you use Claude Code, Codex CLI, Gemini CLI, Cursor CLI, OpenCode, Kimi, Pi or Hermes, you normally see the agent’s final response but not the exact API requests behind it. Claude Tap lets you inspect what the agent actually sent to the model, what tools were exposed, what tool calls happened, how tokens were used and how one request changed from the previous one.

The README emphasizes that traces stay on your machine, no hosted dashboard is required, and common authentication headers are redacted before recording.³ However, traces can still contain prompts, file paths, tool schemas, response bodies and private context, so they must be handled carefully.⁴

What is Claude Tap used for?

Claude Tap is useful when you want to understand why an AI coding agent behaved a certain way.

It helps answer questions such as:

• What system prompt did the agent send?
• How large is the conversation context?
• Which tool schemas were included?
• Which tool call did the model choose?
• Which tool result changed the model’s behavior?
• How many tokens did each request use?
• Was cache read/cache creation used?
• What changed between consecutive requests?
• Did the agent call the expected provider or gateway?
• Why did the agent forget an instruction?

It belongs to the agent observability and agent debugging category. It does not replace the agent; it shows you what the agent is doing.

What Claude Tap is not

Claude Tap does not make the model smarter. It helps you see what the model and agent exchange.

What stands out in the liaohch3/claude-tap repo?

The GitHub repository describes claude-tap as a tool for intercepting and inspecting coding-agent API traffic from Claude Code, Codex CLI, Gemini CLI, Cursor CLI, OpenCode, Kimi, Pi and Hermes in a local trace viewer.⁵ The package is MIT-licensed, requires Python 3.11+, and exposes the claude-tap command-line script.⁶

README highlights:

• live browser viewer enabled by default;
• export to self-contained HTML viewer;
• support for many clients;
• structured diffs across requests;
• token usage breakdown;
• tool inspector;
• full-text search across messages/tools/prompts/responses;
• reverse proxy and forward proxy modes;
• forward proxy plus local CA for clients without base URL overrides;
• local .traces storage by default.⁷

Supported clients

The README lists these main clients:⁸

The support matrix documents default proxy modes: Claude, Codex, Kimi and CodeBuddy use reverse mode by default, while Gemini, OpenCode, Pi, Hermes, Cursor, Qoder and Antigravity use forward mode by default.⁹

Reverse proxy vs forward proxy

Claude Tap captures traffic in two main ways:

Simple mental model:

Reverse proxy:
Client → localhost proxy → API provider

Forward proxy:
Client → HTTPS_PROXY local → one or many API providers

The support matrix explains that each client’s default mode is chosen based on whether it can use a base URL override and whether it may talk to multiple upstreams.⁹

Installation

Requirements:

• Python 3.11+
• The client you want to trace, such as Claude Code, Codex CLI, Gemini CLI, Cursor CLI or Hermes Agent

Recommended installation:

uv tool install claude-tap

Alternative:

pip install claude-tap

Upgrade:

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

The README lists uv tool install claude-tap as the recommended path.¹⁰

Verify:

claude-tap --help

Quickstart with Claude Code

Default run:

claude-tap

This launches Claude Code through Claude Tap, with the live browser viewer enabled by default.¹¹

Pass Claude Code flags after --:

claude-tap -- --model claude-opus-4-6

Continue the last conversation:

claude-tap -c

Skip Claude Code permission prompts:

claude-tap -- --dangerously-skip-permissions

Note: --dangerously-skip-permissions belongs to Claude Code, not Claude Tap. Use it only when you accept the risk of auto-approved tool calls.

Codex CLI

Run Codex through Claude Tap:

claude-tap --tap-client codex

For OAuth after codex login, the README says claude-tap can auto-detect the target https://chatgpt.com/backend-api/codex when it can read the auth state.¹²

Explicit target:

claude-tap --tap-client codex --tap-target https://chatgpt.com/backend-api/codex

API key mode:

export OPENAI_API_KEY="..."
claude-tap --tap-client codex

Pass Codex flags:

claude-tap --tap-client codex -- --model codex-mini-latest

Full auto:

claude-tap --tap-client codex -- --full-auto

Gemini CLI

Gemini CLI uses forward proxy mode by default because Google OAuth / Code Assist traffic goes to multiple Google endpoints.¹³

claude-tap --tap-client gemini -- -p "hello"

For compatible API-key or Vertex-style flows, reverse mode is available:

claude-tap --tap-client gemini --tap-proxy-mode reverse -- -p "hello"

Cursor CLI

Cursor CLI uses forward proxy mode by default. The README recommends --model auto on free plans and omitting --mode ask when tool calls are desired.¹⁴

claude-tap --tap-client cursor -- -p --trust --model auto "hello"

Continue:

claude-tap --tap-client cursor -- -p --trust --model auto --continue "continue"

OpenCode

OpenCode is a multi-provider terminal AI assistant, so Claude Tap defaults to forward proxy mode to capture whichever provider OpenCode calls.¹⁵

claude-tap --tap-client opencode

Reverse mode only works when OpenCode is using the Anthropic provider:

claude-tap --tap-client opencode --tap-proxy-mode reverse

Hermes Agent

Hermes Agent is a multi-provider Python AI agent. The README says httpx and requests honor HTTPS_PROXY, so claude-tap defaults to forward proxy mode for Hermes.¹⁶

Interactive TUI/local trace:

claude-tap --tap-client hermes

Gateway mode:

claude-tap --tap-client hermes -- gateway start

Claude Tap rewrites gateway start to gateway run so the gateway runs in the foreground and inherits proxy environment variables; otherwise a systemd/launchd daemon may not be captured.⁹

Gateway mode only creates traces when a configured messaging platform such as Slack or Telegram sends a real message to the bot.¹⁶

Live viewer, dashboard and export

Live viewer is on by default:

claude-tap

Disable it:

claude-tap --tap-no-live

Browse saved traces:

claude-tap dashboard

Export JSONL trace to HTML:

claude-tap export .traces/2026-02-28/trace_141557.jsonl -o trace.html

Export compact bundle:

claude-tap export <session-id> --format compact -o trace.ctap.json
claude-tap export trace.ctap.json -o trace.html

The README describes the viewer as a self-contained HTML file suitable for review or archiving.¹⁷

Viewer features

Image extracted from the official liaohch3/claude-tap repository, file docs/diff-modal.png. This is a PNG image, not SVG.¹⁸

The README lists these viewer capabilities:¹⁹

This is more readable than raw JSON logging.

Architecture

Image extracted from the official liaohch3/claude-tap repository, file docs/architecture.png. This is a PNG image, not SVG.²⁰

The README describes the flow as follows:²¹

1. claude-tap starts a reverse or forward proxy and spawns the selected client.
2. Base URL clients are pointed at the reverse proxy; other clients use proxy/CA environment variables.
3. SSE and WebSocket streams are forwarded as chunks/messages arrive.
4. Each request-response pair or WebSocket session is recorded in local trace storage.
5. On exit, a self-contained HTML viewer is generated.
6. Live mode broadcasts updates to the browser through SSE.

Simple view:

AI coding agent CLI
        ↓
claude-tap proxy
        ↓
LLM provider / gateway / OAuth backend
        ↓
local trace storage
        ↓
live viewer / dashboard / exported HTML

Trace storage and retention

Default trace directory:

./.traces/

Custom directory:

claude-tap --tap-output-dir ./my-traces

Keep fewer sessions:

claude-tap --tap-max-traces 10

Unlimited sessions:

claude-tap --tap-max-traces 0

Proxy-only mode:

claude-tap --tap-no-launch --tap-port 8080

In proxy-only mode, run your client separately and point its base URL or proxy settings at the local proxy.²²

Important CLI options

All non---tap-* flags are forwarded to the selected client.²³

When should you use Claude Tap?

Use it when:

• you are debugging an AI coding agent;
• the agent calls the wrong tool;
• the agent forgets instructions;
• you need request-by-request diffing;
• tool schemas are too large;
• token usage is unexpected;
• you are comparing coding agents;
• you need a portable trace for team review;
• you need to confirm provider/gateway routing.

Avoid or be careful when:

• you do not want prompts or context stored locally;
• the project contains very sensitive data;
• you run on a shared machine;
• you do not understand forward proxy/local CA behavior;
• enterprise policy forbids proxy/MITM capture;
• traces require strict compliance handling.

Personal workflow

Recommended flow:

# 1. Install
uv tool install claude-tap

# 2. Run with your main client
claude-tap
# or
claude-tap --tap-client codex
# or
claude-tap --tap-client cursor -- -p --trust --model auto "hello"

# 3. Inspect the live viewer

# 4. Browse saved traces later
claude-tap dashboard

# 5. Export only when needed
claude-tap export <session-id> --format compact -o trace.ctap.json
claude-tap export trace.ctap.json -o trace.html

Add .traces/ to .gitignore if you run it inside a Git repository.

Team rollout guide

Phase 1: individual use

• Each developer installs claude-tap.
• They run it with the agent they already use.
• They inspect context, tools and token usage locally.
• They do not share raw traces without redaction.

Phase 2: trace-sharing policy

Suggested policy:

- Do not share raw .traces/*.jsonl outside the team.
- Do not share HTML traces before reviewing them.
- Redact API keys, file paths, customer data and internal prompts.
- Prefer compact export when possible.
- Delete old traces regularly.

Phase 3: agent workflow review

Use traces to review:

• oversized prompts;
• oversized tool schemas;
• unnecessary context;
• unusual token/cost spikes;
• tool results that mislead the agent;
• prompt injection from tool output;
• incorrect provider/gateway routing.

Phase 4: internal observability

Do not automatically upload traces to a shared server without privacy review. If you need centralized traces:

• encrypt artifacts;
• restrict access;
• define retention;
• isolate customer-data traces;
• store metadata instead of full bodies when possible;
• conduct security review.

Security notes

The SECURITY.md explicitly warns not to attach raw .traces/*.jsonl, generated HTML viewers, screenshots or recordings unless they have been reviewed and redacted.⁴ Trace files can contain prompts, tool schemas, file paths, response bodies and private context even when API keys are redacted.⁴

Security checklist:

• Add .traces/ to .gitignore.
• Do not commit trace.html or .ctap.json.
• Do not post traces in public chats.
• Review system prompts before sharing.
• Check file paths and repository names.
• Check tool outputs for secrets or customer data.
• Avoid binding --tap-host 0.0.0.0 unless you understand the risk.
• Understand where the local CA is trusted when using forward proxy mode.
• Do not run on shared machines with sensitive traces.
• Delete old traces.
• Report security issues privately, not through public GitHub issues.⁴

Claude Tap vs Headroom and RTK

Claude Tap does not directly optimize tokens. It shows where tokens are being spent so you can make better optimization decisions.

FAQ

What is Claude Tap?

Claude Tap is a local proxy and trace viewer for AI coding agents. It records real API traffic such as system prompts, messages, tools, tool calls, streaming responses, token usage and request diffs.²

Is Claude Tap only for Claude Code?

No. The README lists support for Claude Code, Codex CLI, Gemini CLI, Kimi CLI, OpenCode, Pi, Hermes Agent, Cursor CLI, Qoder CLI, Antigravity CLI and CodeBuddy CLI.⁸

Are traces uploaded to a hosted dashboard?

The README says traces stay on your machine and no hosted dashboard is required.³ If you export or share a trace, redaction is your responsibility.

Does Claude Tap remove API keys?

The README says common authentication headers are redacted before recording.³ The security policy warns that traces can still contain prompts, file paths, response bodies and other private context.⁴

What is the difference between reverse and forward proxy?

Reverse proxy is best when a client supports a base URL override. Forward proxy is best for clients that talk to multiple upstreams or do not support a reliable base URL override.⁹

Should Claude Tap be used in CI?

It can be used for debugging, but avoid uploading trace artifacts without a privacy policy. Traces can contain sensitive context.

Conclusion

liaohch3/claude-tap is useful for anyone who uses AI coding agents seriously. It turns an otherwise opaque process into inspectable data: prompts, messages, tool schemas, tool calls, responses, token usage and request diffs. That makes it easier to understand why an agent failed, why token usage grew, or whether traffic went to the intended provider.

The easiest start is uv tool install claude-tap, then run claude-tap for Claude Code or claude-tap --tap-client codex/cursor/gemini for other clients. For teams, the main value is agent workflow review, but trace privacy needs strict handling because traces can include private context.

References

Footnotes

1. GitHub raw asset. liaohch3/claude-tap/docs/viewer-light.png. https://raw.githubusercontent.com/liaohch3/claude-tap/main/docs/viewer-light.png ↩

2. claude-tap README, project overview. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩ ↩²

3. claude-tap README, “Why use it”. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩ ↩² ↩³

4. claude-tap SECURITY.md. https://raw.githubusercontent.com/liaohch3/claude-tap/main/SECURITY.md ↩ ↩² ↩³ ↩⁴ ↩⁵

5. GitHub. liaohch3/claude-tap. https://github.com/liaohch3/claude-tap ↩

6. claude-tap pyproject.toml. https://raw.githubusercontent.com/liaohch3/claude-tap/main/pyproject.toml ↩

7. claude-tap README, viewer and trace overview. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

8. claude-tap README, supported clients. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩ ↩²

9. claude-tap support matrix. https://raw.githubusercontent.com/liaohch3/claude-tap/main/docs/support-matrix.md ↩ ↩² ↩³ ↩⁴

10. claude-tap README, install section. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

11. claude-tap README, quick start examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

12. claude-tap README, Codex CLI auth modes and examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

13. claude-tap README, Gemini CLI examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

14. claude-tap README, Cursor CLI examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

15. claude-tap README, OpenCode examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

16. claude-tap README, Hermes Agent examples. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩ ↩²

17. claude-tap README, export and advanced options. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

18. GitHub raw asset. liaohch3/claude-tap/docs/diff-modal.png. https://raw.githubusercontent.com/liaohch3/claude-tap/main/docs/diff-modal.png ↩

19. claude-tap README, viewer features. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

20. GitHub raw asset. liaohch3/claude-tap/docs/architecture.png. https://raw.githubusercontent.com/liaohch3/claude-tap/main/docs/architecture.png ↩

21. claude-tap README, architecture section. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

22. claude-tap README, viewer/export/advanced options. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩

23. claude-tap README, CLI options. https://raw.githubusercontent.com/liaohch3/claude-tap/main/README.md ↩