What Claude Code Actually Sends to the Model? Discover with claude‑tap

Why AI‑coding tools need observability

Many developers now embed Claude Code, Codex CLI, Cursor, Gemini CLI and similar tools into daily workflows to read repositories, modify code, run commands and even perform large‑scale refactoring. However, the actual request payloads—system prompts, tool definitions, context accumulation, token distribution, and possible gateway modifications—are usually hidden inside a black box.

claude‑tap: a local proxy and trace viewer

claude‑tap is an MIT‑licensed open‑source project that sits between an AI‑coding CLI and the model API. It records every request and response, writes them as JSONL traces, and presents them in a browser‑based viewer, showing per‑round dialogue, tool calls, diffs and token statistics. This gives prompt engineers, agent developers and tool evaluators a concrete way to see why an AI behaved a certain way.

How it works

All supported CLI traffic is routed through a local proxy.

The proxy logs the full JSON request/response pair, then streams a structured trace to the viewer.

The proxy operates in two modes: reverse‑proxy for clients that allow a custom base URL (e.g., Claude Code, Codex CLI) and forward‑proxy via the HTTPS_PROXY environment variable for clients that cannot change their endpoint (e.g., Gemini CLI, OpenCode). TLS decryption is handled with a self‑signed certificate.

Supported CLI ecosystem

claude‑tap covers 16 clients, including:

Claude series: Claude Code, AWS Bedrock, DeepSeek/GLM gateways

OpenAI series: Codex CLI, Codex App

Google series: Gemini CLI

xAI: Grok Build CLI

Moon‑side: Kimi CLI, Kimi Code

Other tools: Cursor, Qoder, Antigravity, OpenCode, Pi, Hermes Agent, Tencent CodeBuddy CLI

This breadth lets developers compare how different tools structure prompts, declare tools, and manage context without writing separate packet‑capture logic for each.

Structured diff for multi‑round context

AI CLI requests evolve over rounds: the first round may contain only a system prompt and user query, later rounds add model replies, tool results, file contents and further user instructions. claude‑tap’s structured diff highlights exactly what changed between consecutive requests—system prompt edits, tool list additions or schema changes, ordering of dialogue history, inclusion of tool results, hidden commands or gateway‑injected prefixes, and a detailed token breakdown (input, output, cache reads, cache writes).

Engineering details

Authentication headers are automatically redacted before being written to the trace.

The viewer is a single‑file HTML that can be shared or archived.

Real‑time mode is enabled by default, updating the view as the CLI runs.

Token usage is split into input, output, cache read and cache write.

Special adapters handle Anthropic gateways on AWS Bedrock, enterprise proxies and SigV4 signing.

Installation and usage

# Recommended
uv tool install claude-tap
# Or with pip
pip install claude-tap

Start the proxy with a simple command: claude-tap Specify a target client with --tap-client (e.g., claude-tap --tap-client codex for Codex CLI, claude-tap --tap-client gemini -- -p "hello" for Gemini CLI, etc.). Additional flags for the underlying CLI are passed after --.

# Pass flags through to Claude Code
claude-tap -- --model claude-opus-4-6
# Skip permission prompts
claude-tap -- --dangerously-skip-permissions

The tool itself is free; costs arise only from the underlying model APIs (Claude, OpenAI, Gemini, Kimi, etc.).

Three primary scenarios

Studying mature AI‑CLI system designs: inspect how system prompts, tool schemas, permission strategies, context trimming and error recovery are orchestrated.

Debugging custom agents: pinpoint where context balloons, tool results are dropped, or constraints are lost, turning “mysterious drift” into data‑driven fixes.

Evaluating different models and gateways: verify that request structures, tool definitions and model parameters remain consistent across back‑ends.

Best‑practice cautions

Having a request trace does not mean you should copy another tool’s system prompt verbatim; each product embeds extensive engineering trade‑offs (permission models, file indexing, error recovery, product boundaries). Instead, learn how they constrain tool calls, organize multi‑round context and manage token costs, then adapt those patterns to your own agents.

Conclusion

AI programming is shifting from “using tools” to “debugging tools”. Observability of the request layer—seeing the raw JSON, diffs and token accounting—is essential for moving from trial‑and‑error to systematic, engineering‑grade development.