About this project

cost-xray is a local capture and cost-attribution tool for AI coding agents. Instead of reading local transcripts after the fact, it intercepts the actual API requests that Claude Code and Codex send, then breaks each request into its component sources and prices them. Why it exists: log-based usage tools show the total cost of a call or session, but the request-time context — system prompts, injected tool schemas, MCP blocks, tool results, cache reads/writes, prior thinking blocks — is assembled at request time and never written to the transcript. That invisible prefix can be a large share of the context. cost-xray reads the raw wire request so it can attribute tokens and dollars to schemas, MCP servers, tools, and message buckets, down to individual tool calls. How it works: mitmproxy runs as a local capture hop. Claude Code is captured via reverse-proxy mode with a base-URL override (no certificate); Codex uses a forward proxy plus a scoped local CA trusted only by the codex command. The proxy binds to 127.0.0.1, sends no telemetry, and redacts Authorization headers, API keys, cookies, and secret-looking body fields before writing to disk under ~/.cost-xray/. Analysis runs off the request path in a separate materializer, so tokenizing and pricing do not add latency to live relay. Captured traffic is deduplicated by unique block with per-turn deltas, keeping disk usage small even for million-token sessions. Features described in the README: per-source cost attribution split into fresh, cache-read, cache-write, and output tokens, priced down to the individual call; context-window occupancy broken into source-level rows; detection of configured MCP servers and tools that are injected into every request but never called; a tokenization approach for Claude that uses tiktoken estimation plus proportional calibration against the provider's own usage totals (totals exact, per-source split approximate); self-healing wrappers that restart the proxy or fall back to direct agent execution; and a live TUI. Installation is a curl-piped install script that prompts for which agents to capture, or accepts COST_XRAY_AGENTS=claude|codex|all. Capture is forward-only and requires a new terminal. The cx CLI opens the TUI and manages services (status, stop, start, restart, install, uninstall). Requirements are macOS or Linux, a supported agent, and no API keys or account. Licensed MIT.