Files

T

BKK 7b979fc179 Capture Codex App traffic via forward proxy (#351 )

* Capture Codex App traffic via forward proxy

* feat: resolve Codex App executable via CODEX_APP_EXECUTABLE and default install paths

Port the executable-resolution approach from the duplicate PR #350 into
this PR's forward-proxy Codex App capture:

- Add _codex_app_executable_candidates() and _resolve_client_executable()
  so codexapp launch checks CODEX_APP_EXECUTABLE first, then the default
  /Applications and ~/Applications install locations, instead of a single
  hardcoded path.
- Print an actionable error (mentioning CODEX_APP_EXECUTABLE) when no
  Codex.app executable is found.
- Update README/README_zh with a CODEX_APP_EXECUTABLE usage example.
- Refresh docs/support-matrix.md and .zh.md Codex App rows, which still
  described the removed transcript/CDP capture mode.
- Add unit tests for executable candidate resolution and env override
  precedence; update existing codexapp launch tests to mock the new
  resolver instead of shutil.which.

* test: remove obsolete Codex App transcript lock case

* fix: address Codex App capture review feedback

---------

Co-authored-by: liangweifeng <liangweifeng@bytedance.com>
Co-authored-by: youngcan <wangyongkai03@meituan.com>
Co-authored-by: Wyckoff <yongkai_wang@foxmail.com>

2026-07-21 23:29:45 +08:00

4.4 KiB

Raw Permalink Blame History

Local AI Agent Trace Viewer

claude-tap is a local trace viewer and HTML exporter for AI coding agents. It helps you inspect Claude Code traces, Codex traces, OpenAI Responses API traces, Anthropic Messages traces, Gemini traces, and other agent runs without uploading private data to a hosted dashboard.

English guide | Simplified Chinese guide

What is an AI agent trace?

An AI agent trace is the recorded request and response flow behind an agent run. For coding agents, a useful trace usually includes:

System prompts and conversation history
Tool schemas, tool calls, tool inputs, and tool results
Streaming response chunks reconstructed into readable output
Token usage, cache usage, and latency
Request diffs between adjacent turns

These details are hard to recover from terminal output alone. The terminal shows what the agent says; a trace shows what the agent sent.

Why view traces locally?

Many observability products are useful for production systems, but local debugging has a different job. When a coding agent touches private code, private prompts, repository metadata, or internal tools, the safest default is to inspect the trace on your own machine.

claude-tap keeps trace sessions local by default. Common auth headers are redacted before recording, and exported HTML files are static artifacts that you control.

Supported traces and clients

claude-tap can trace and inspect sessions from:

Claude Code
Codex CLI
Codex App
Gemini CLI
Cursor CLI
OpenCode
Kimi CLI
Pi
Hermes Agent
Qoder CLI
Antigravity CLI
CodeBuddy CLI

It also supports trace shapes from Anthropic Messages, OpenAI Responses, OpenAI Chat Completions, Gemini, and Claude-compatible gateways.

How to view a trace

Install claude-tap:

uv tool install claude-tap

Run the client through claude-tap:

# Claude Code
claude-tap

# Codex CLI
claude-tap --tap-client codex

# Codex App backend capture through the forward proxy
claude-tap --tap-client codexapp

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

Open the local dashboard or export a standalone HTML file with embedded compact trace data:

claude-tap export trace.jsonl --format html

What to inspect first

Start with these questions:

Did the agent receive the prompt and context you expected?
Did tool schemas change between turns?
Did the agent call the right tool with the right parameters?
Did token usage grow because of history, tool results, or repeated context?
Did latency come from the model call, tool call, or a long streaming response?

The trace viewer is designed around these debugging questions.

Claude trace viewer

For Claude Code and Anthropic-compatible traffic, claude-tap shows Anthropic Messages requests, tool calls, streaming responses, token usage, and Claude-compatible gateway metadata. It can be used as a local Claude trace viewer when you want to inspect Claude Code runs without uploading session data.

Codex trace viewer

For Codex CLI, claude-tap supports OpenAI API key mode and ChatGPT subscription OAuth mode. For Codex App, it launches the desktop app through a local forward proxy and records completed HTTP/WebSocket model calls to /backend-api/codex/responses; other product traffic is relayed without being stored. Quit an already-running Codex App first so the launched process inherits the proxy and CA configuration. The viewer can inspect request context, tool calls, reasoning/output sections, token usage, and request diffs.

Export traces to HTML

The HTML export is useful when you need a portable review artifact:

Share a debugging run with another maintainer
Attach evidence to a pull request
Archive a model behavior regression
Compare adjacent requests during prompt or tool changes

The exported file is self-contained and can be opened without a hosted dashboard.

Local trace viewer vs hosted observability

Use a local trace viewer when you want fast inspection of private agent runs. Use hosted observability when you need production monitoring, team-wide dashboards, alerts, or long-term telemetry.

claude-tap is focused on the local debugging and review loop: capture a real run, inspect the request flow, and export a static artifact when needed.

4.4 KiB Raw Permalink Blame History