cost-xray: attributing every token a coding agent spends to the exact request part that caused it

Pricing the request, not just the session

cost-xray answers a question most usage tools cannot: not how much a session cost, but why. The README's argument is that tools reading local logs see the total of a call but miss the request-time context assembled before the model runs, the system prompts, tool schemas, MCP blocks, tool results, cache reads and writes, and previous thinking blocks. cost-xray captures the actual local API traffic for Claude Code and Codex and attributes tokens and dollars back to the sources inside each request.

The user is a developer or team running these agents who wants to know where their token budget goes. When a turn is expensive, the useful answer is which MCP server, which tool result or which cached block drove the cost, and that is exactly what cost-xray claims to surface. It is MIT licensed and, by design, local-only with no telemetry.

What makes it more than another dashboard is the level of attribution. The README states it traces every token's cost, split into fresh, cache-read, cache-write and output, down to the individual call: the cost of a specific `Read` invocation and its output, not a session sum. It claims nothing else prices below the tool, call by call, and whether or not that is strictly unique, per-call attribution is a genuinely different resolution from the usual per-session total.

A transparent local hop, decoded by per-agent adapters

The mechanism is a proxy that sits in the path between the agent and the API. The README's supported-agents table describes two capture methods: Claude Code is captured with a reverse proxy via a base-URL override and no certificate, while Codex is captured with a forward proxy and a scoped local CA behind a self-healing wrapper. Both are local hops that, the README stresses, do not change what the agent does, its results or its cost.

The wire is decoded by a thin per-agent adapter, which the README calls the only place the code forks by agent. That design has a payoff: adding an agent is one small module, and anything speaking the Anthropic or OpenAI-Responses wire shape is close to drop-in. So the architecture is a shared analysis core with a small adapter per agent, rather than two separate tools.

Because capture is transparent, there is no API key, no account and no config change to the agent itself. mitmproxy does the interception locally, and the captured traffic never leaves the machine. For anyone nervous about routing their coding agent's traffic through a tool, the local-only, no-telemetry stance is the load-bearing promise, and the README leads with it.

Installing and opening the live view

Installation is a single script that asks which agents to capture:

curl -fsSL https://raw.githubusercontent.com/tigerless-labs/cost-xray/master/install.sh | bash

The README says the installer prompts for Claude Code, Codex or both even under `curl | bash`, and that you can skip the prompt in CI by setting `COST_XRAY_AGENTS=claude|codex|all`. If you have already cloned the repository, `./install.sh` does the same. Capture is forward-only: you open a new terminal, run `claude` or `codex` exactly as before, and runs started in that shell are captured while past history is not.

The entire CLI is the `cx` command, and it works from any directory:

cx
cx status
cx stop

`cx` opens the live TUI, `cx status` shows the services' state, live ports and sessions captured, and `cx stop` takes the proxies down so agents run direct and uncaptured. The README notes capture runs as a background service that auto-starts on boot, self-heals and adapts ports. Inside the TUI you drill from the top down, agent to project to session to category to MCP server to tool to per-turn call to the real output, with every cell carrying its cache split of read, write, fresh and output dollars.

Forward-only capture and the proxy trust question

Two limitations follow directly from the design. First, capture is forward-only, which the README is explicit about: only runs started after installation in a new shell are recorded, not past history. So cost-xray is a tool you install before the sessions you want to analyze, not a forensic tool for reconstructing spending you already incurred. If you want data on a run, you have to be capturing when it happens.

Second, the capture works by interposing a proxy. For Codex that means a scoped local certificate authority, which is a self-healing wrapper the README documents but is still a local CA you are trusting for the interception to work. That is a reasonable trade for the visibility, and the README bounds it, local-only, no telemetry, scoped, but it is a real part of the setup that a security-conscious team should understand rather than run blind. The Claude Code path avoids the certificate by using a base-URL override instead, so the two agents carry slightly different trust footprints.

There is also a platform limit: the README lists macOS or Linux, with GUI agents such as Cursor needing a base-URL setup documented separately. Windows is not in the requirements.

Against reading local logs or the provider dashboard

The alternative is what most people already use: a usage tool that reads the agent's local logs, or the provider's own billing dashboard. Those are simpler, need no proxy and no certificate, and give you accurate totals per call or per session.

The difference is resolution and reason. A log-based tool sees the recorded cost of a call but not the composition of the request that produced it, so it can tell you a turn cost a lot but not that the cost came from a particular MCP server's tool schemas or a large cached block. cost-xray captures the wire itself, so it can split each token into fresh, cache-read, cache-write and output and attribute it to the source inside the request, down to the call. The cost of that depth is the proxy and its trust footprint, and the forward-only capture. Choose the log reader or the dashboard when you want totals with zero setup. Choose cost-xray when a turn is expensive and you need to know which part of the assembled context, which tool, which MCP server, actually spent the tokens, and you are willing to run a local capture hop to see it.

MIT, local-only, and where to start

cost-xray is MIT licensed with a `THIRD_PARTY_NOTICES.md`, so it can be forked and adapted, and its adapter-per-agent structure means extending it to another agent that speaks the Anthropic or OpenAI-Responses wire is a bounded job rather than a rewrite. The presence of a `SECURITY.md`, an `experiments/` directory and a test suite in the tree suggests the project takes the sensitive nature of proxying agent traffic seriously.

Operationally the upkeep is light because the service is self-healing and port-adaptive, and configuration lives in `~/.cost-xray/env`, edited then reloaded with `cx restart`. Uninstalling with `cx uninstall` removes the services and shell wrappers while keeping captured data, so trying it is low-commitment.

The concrete first step is to confirm the transparent-capture claim on your own setup before trusting the numbers: install, open a new terminal, run one `claude` or `codex` turn, and check `cx status` shows it captured, then open `cx` and verify a call's cache split looks right. Because capture is forward-only and local-only, that first captured turn is also the moment you confirm the proxy is not changing your agent's behaviour, which is the property the whole tool rests on.

Editorial conclusion

Use cost-xray if you run Claude Code or Codex and need to know which part of a request, an MCP server, a tool result, a cached block, actually spent your tokens, at per-call resolution that log-based tools cannot reach: the transparent local proxy and the fresh/cache-read/cache-write/output split are the reasons to run it. It is the wrong tool for reconstructing past spending, since capture is forward-only, or on Windows, which is not in the requirements, or if you cannot accept a scoped local CA for Codex capture. Start by installing, capturing a single turn in a new terminal, and confirming with cx status that it recorded and that your agent behaves identically, since local-only, no-change capture is the promise everything else depends on.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. tigerless-labs/cost-xray on GitHub