cost-xray Reads the Raw API Request, Because Your Agent's Transcript Never Contained the Tokens You Paid For

Why every token-accounting tool built on session logs is measuring an artifact the harness assembled after the fact

There is one sentence in the cost-xray README that invalidates most of the agent cost tooling built in the last year.

"Log readers see the transcript after the agent has run," it says, and then the part that does the damage: "the system prompt, injected tool schemas, MCP schemas, reminders, and provider-added blocks are assembled at request time and never written to the transcript."

Sit with that list. System prompt, tool schemas, MCP schemas, reminders, provider-added blocks. On a real Claude Code or Codex session with a handful of MCP servers connected, that material is not a rounding error on the bill. It is frequently the majority of the input tokens on every single request, repeated on every turn. And it is not in the file you have been parsing.

Which means the honest version of what most people know about their agent spend is: they have a receipt total from the provider dashboard, and a transcript that cannot explain it.

The gap between what you can read and what you were charged

The failure is structural rather than anyone's bug. A transcript is a record of the conversation. The request is a record of the conversation plus everything the harness wrapped around it, and the harness builds that wrapper fresh on every call.

So when your bill jumps 40% after you connect two new MCP servers, the transcript looks identical. Same messages, same tool calls, same length. The 40% lives in tool schema definitions that got serialized into every request and never touched a log file. Anthropic's own advanced tool-use work put numbers on this class of problem last year: tool definitions alone can run to six figures of tokens before optimization, and a modest multi-server MCP setup can carry tens of thousands of tokens of schema on every turn. You cannot see any of it from the outside.

tigerless-labs/cost-xray resolves this by refusing to read the transcript at all. It captures the HTTP request on its way out and computes token attribution from the bytes the provider actually received. The README's own framing: cost-xray "reads the raw API request, so it can compute source-level tokens." Source-level is the operative phrase. Not "this session cost $4.10" but "this session cost $4.10, and $2.60 of it was tool schemas."

How it actually gets in the path

The mechanism is a local mitmproxy sitting between your agent and the model API. The README diagrams it as agent ──HTTP──▶ mitmproxy ──HTTPS──▶ model API, and the two supported agents get there by different routes.

Claude Code gets a "reverse proxy (base-URL override)" with "no certificate." That is the easy case: Claude Code lets you point it at a different base URL, so cost-xray takes the traffic without touching your trust store. Nothing in your system certificate configuration changes.

Codex gets a "forward proxy + scoped local CA (self-healing wrapper)." That is a heavier ask. A forward proxy intercepting TLS needs a certificate authority your agent will trust, and cost-xray installs a scoped one. If you have a policy about local CAs, this is the line in the README where you stop and think, and it is to the project's credit that it says so rather than burying it in an install script.

The self-healing part is a good design decision that I wish more local proxies copied: "if the proxy is down, the wrapper restarts it and routes through; if it can't, the agent runs direct," and the README's two-word verdict on that fallback is "never broken." An observability tool that can take your coding agent offline gets uninstalled in week two. This one degrades to not-observing instead of to not-working.

Install is one line, curl -fsSL https://raw.githubusercontent.com/tigerless-labs/cost-xray/master/install.sh | bash, and the installer "asks which agent(s) to capture" from Claude Code, Codex, or both, and the README notes it "prompts even under curl … | bash", with COST_XRAY_AGENTS available if you want that unattended. Note the master in that URL. The default branch is master, not main, which will bite anyone scripting against the raw content.

The runtime surface is a small CLI: cx opens the TUI, plus cx status, cx start, cx stop, cx restart, cx install and cx uninstall.

The privacy story is the part that decides adoption

A tool that reads every request your coding agent sends is reading your source code, your prompts, and whatever secrets you have been careless with. So the README's claims here are the ones that matter most, and they are unusually specific.

"The proxy binds to 127.0.0.1 and sends no telemetry." No account, no API key, no signup. "Authorization, API keys, cookies, and secret-looking body fields are redacted before anything hits disk." Captures land in ~/.cost-xray/sessions/, and the README's cleanup instruction is to delete the directory.

Redaction before write is the correct ordering and it is not the common one. Plenty of tools redact on display and keep the raw bytes on disk, which means a laptop backup carries your keys. This one claims to redact at the boundary. I have not audited the redaction rules, and "secret-looking body fields" is a heuristic rather than a guarantee, so treat it as a better default than most rather than as a promise.

The limitation the project states about itself

Here is the sentence I respect most in the README, because it undercuts the tool's own headline: "The total, and therefore the bill, is exact; only the split between sources in the same request is approximate."

That is exactly the right thing to disclose. The total is exact because it is counted from the request the provider received. The split is approximate because attributing a shared token budget back to "system prompt" versus "MCP schema" versus "your actual message" requires deciding where one section ends and another begins inside a single serialized payload, and there is no ground truth for that boundary.

So cost-xray tells you your bill exactly and your breakdown approximately. Which is still a large improvement over a transcript that tells you neither. But it means you should use the breakdown for ranking rather than for accounting. "Tool schemas are the biggest line item" is a conclusion you can act on. "Tool schemas are 63.2% of spend" is a number you should not put in a slide.

Put this into practice

Start with the cheapest possible experiment, and do it before you change anything about your setup. Install, run cx, and do one ordinary session you would have done anyway. Do not optimize. Just look at the split and find out whether your assumption about where the money goes survives contact with the request.

Then run the one experiment this tool exists for. Note your per-request input token count. Disconnect every MCP server you are not actively using. Run the same kind of session again. The difference is the standing cost of schemas you were carrying for tools the model never called, and until now you had no way to price that decision. Most people are carrying several servers they connected once for a specific task and never disconnected. This makes that visible in dollars instead of vibes.

Third, if you maintain a CLAUDE.md or an equivalent instruction file that has been growing for months, look at what fraction of every request it now occupies. Instruction files are the one part of the wrapper you fully control, and they are the part nobody measures because editing them feels free. It is free to write and it is not free to send.

Fourth, before you install on a machine that matters, decide about the CA. Claude Code needs no certificate, so if you only run Claude Code you can get the whole benefit with no trust-store change. Codex is the case that needs the scoped local CA, and that is a security-review question in most organizations rather than a preference.

And keep the release reality in mind while you do all this. Which brings me to the part that should shape how you adopt it.

Honest limitations

I have not installed cost-xray or run it against a session. Everything above is a reading of the README and the repository's own release metadata, verified this morning with cache-busted fetches. I am reporting what the project claims about itself, including its privacy claims, none of which I tested.

The release history is the real caution. The only tagged release is v0.1.0, dated June 9, 2026, which is three and a half months ago as of today, against a README describing a finished TUI, a dashboard, and multi-agent capture. Either the project ships from master without tagging, which is common and fine as long as you know you are doing it, or the tag you would pin in any reproducible setup is far behind the documentation you read. Both readings argue for installing from a commit you chose rather than from a moving branch.

I also did not verify the star count against a second source. The shields read this morning showed roughly 2.2k, and api.github.com is unreachable from where I was working, so that is one source and should be treated as approximate. Momentum board ranks are a moment, not a standing, and the #5 slot it held at 07:11 ET may not be the one it holds tonight.

The redaction claim deserves one more caveat than the README gives it. "Secret-looking body fields" means pattern matching, and pattern matching misses. If you have credentials in an unusual shape, or in a file your agent pasted into context, assume they are on disk under ~/.cost-xray/ until you have checked.

And the bigger unknown: I do not know how cost-xray computes the source-level split, only that the project calls it approximate. Without knowing the segmentation rule, I cannot tell you whether the approximation is off by a percent or by a lot on a request with heavily interleaved system and tool content. The project says the ordering of line items is what you should trust. I have no basis to say it is wrong about that, and no basis to say how much slack sits inside it.

The idea worth keeping even if you never install this

The transferable insight here is not a tool. It is a rule about where to instrument.

Any time a system assembles a payload at call time from parts you did not write, your logs are a description of your intent and the payload is a description of what happened. Coding agents are the most expensive current example, but the same shape shows up in anything that injects schemas, retrieves context, or wraps your message in a template built by somebody else's code. If your measurement sits above that assembly step, you are measuring the part you already knew.

So put the meter below the thing that builds the request. For coding agents today that means a local proxy, and cost-xray is the most direct version of it I have read. Install it in a repository you do not care about, run one normal session, and see whether the split matches the story you have been telling yourself about your bill.

If it does, you have lost twenty minutes. If it does not, you now know which of your MCP servers you are paying rent on.

Sources: tigerless-labs/cost-xray · cost-xray README, raw · mitmproxy · Anthropic advanced tool use

Medium metadata

Title: cost-xray Reads the Raw API Request, Because Your Agent's Transcript Never Contained the Tokens You Paid For Subtitle: Why every token-accounting tool built on session logs is measuring an artifact the harness assembled after the fact Tags: Claude Code, AI Agents, Developer Tools, MCP, Open Source Canonical: import from fervorai.dev