Model or dataset
tigerless-labs/cost-xray avatar
tigerless-labs/cost-xray

cost-xray: totals are exact, per-source splits are not, and pricing comes from a bundled snapshot

See what Claude Code and Codex actually send to the API — and what each part costs.

5,807 stars377 forksPythonMIT

At a glance

What is it?
cost-xray sits in the path between a coding agent and its API, decodes the traffic for two supported agents, and prices each source inside a request rather than each session. Its documentation is unusually candid about the weak point: for Claude there is no open tokenizer, so the per-source split within a request is approximate even though the total it prints is not. It also states that dollars come from a price snapshot bundled in the package and refreshed by a script, not fetched live.
Who is it for?
This tool fits someone whose bill surprised them and who suspects the context window rather than the model, since that is the question it is built to answer. Three things to check before you trust a number from it.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • tigerless-labs/cost-xray5,807 ★ · +3,678
Star history
Repository2026-09-222026-11-15
tigerless-labs/cost-xray2.1k5.8k

3,678 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

It reads the wire rather than your transcripts

The pitch is a distinction from log-based tools, and the page is specific about it. Most usage tools read local logs, which shows what a call or a session cost in total but misses the context assembled before the model is invoked: the system prompt, the tool schemas, the MCP blocks, tool results, cache reads and writes, and previous thinking blocks. cost-xray captures the local API traffic instead and attributes tokens and dollars back to the sources inside the request. Log tools such as the two it names are described as excellent at local-first session analytics, reading local transcripts and pricing a session by model, day or task, which answers how much was spent. The lower question this tool asks is which bytes the model actually received and which source owns those tokens.

One supported agent needs no certificate and the other installs one

The supported agent table is two rows and the capture column is where they differ. Claude Code is captured with a reverse proxy using a base-URL override, and the table notes no certificate is involved. Codex is captured with a forward proxy and a scoped local certificate authority, installed by a self-healing wrapper. So the cost of the setup is not uniform across the two agents, and a user of the second one is agreeing to trust a local certificate authority on their machine in exchange for the capture. The page is also candid about the code shape: the wire is decoded by a thin per-agent adapter, which is the only place the code branches by agent, and anything speaking either of the two supported wire shapes is described as close to drop-in.

The totals are exact and the per-source split is an estimate

This is the caveat worth reading before quoting any figure from the tool. Claude's tokenizer is private, with no official or open-source tokenizer available, and calling the provider's own token counting endpoint for everything would add load and hit its limits. So for Claude the tool estimates and then calibrates proportionally: a general tokenizer sizes each part, the parts it mis-sizes most, named as thinking blocks and tool schemas, get targeted corrections that are pinned against the counting endpoint when you are logged in and fall back to a fixed ratio otherwise, and the remainder is scaled so the calibrated total matches the provider's own reported usage. The stated consequence is that the total, and therefore the bill, is exact, while only the split between sources in the same request is approximate. The residuals are benchmarked continuously, and an opt-in exact mode using full endpoint differencing is announced as coming.

Dollars come from a bundled price snapshot with a refresh script

The pricing source is visible in the repository rather than in the prose, and it matters. The package includes a data directory of JSON files as package data, and the build configuration declares a target that refreshes the bundled price snapshot, with a make target named for the job that runs a script to do it. So the dollar figures are computed from a table vendored into the installed package, not from a live price feed. That is a reasonable design for a tool that must work offline and be reproducible, and it has an obvious failure mode: a model released after the snapshot was taken may have no entry until the snapshot is refreshed. The repository also carries a third party notices file and a security file, which is the expected shape for something that terminates TLS locally and ships another project's data.

The live TUI is an optional extra, the proxy is not

The runtime dependencies are three, and one of them is a proxy toolkit rather than a library: a proxy framework at version 10 or newer, a tokenizer library, and a terminal formatting library. The terminal user interface the documentation spends most of its words on is not among them. The project configuration puts it in an optional extra alongside the development group, so opening the live view from the command line depends on an extra that the base install does not pull in. The drill-down the page describes is impressive in scope, going from agent to project to session to category to server to tool to the individual turn call and its output, with every cell carrying its own split between cache read, cache write, fresh and output cost, and the README's install flow says to open it with `cx` right after running the installer.

The installer asks a question even when it is piped into a shell

The install command is a script fetched over the network and executed by the shell:

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

The page is straightforward that this still prompts, asking which agents to capture among Claude Code, Codex, or both, and it gives the non-interactive route as an environment variable with three accepted values for one agent, the other, or all. If you already have a clone, the same script runs from the repository. What follows the install is the part that changes your habits: you open a new terminal, and from then on the agent you already use is captured without flags and without a base-URL change. The requirement list is otherwise short, naming a supported agent, macOS or Linux, and no API keys, no account and no configuration change to the agent, with capture described as a transparent local hop.

Capture is forward-only, self-healing, and falls back to running direct

Three properties of the capture are worth knowing before you rely on them. It is forward-only: only runs started after installation are captured, and past history is not, which follows from where the data comes from. It is self-healing, because the wrappers are per-command and will restart the proxy and route through it if it is down, and if they cannot, the agent runs direct rather than breaking. And it is a background service, described as auto-starting on boot, self-healing and port-adaptive, with port and upstream settings living in an environment file in a dot-directory in your home folder and a restart command to apply them. The same command set stops monitoring, which takes the proxies down and leaves the agents running direct and uncaptured, resumes it, restarts the proxies after a configuration change, reinstalls the chosen agents while removing the others, and uninstalls the services while keeping the captured data.

Unused MCP servers are billed on every turn

One feature exists because of how the agents assemble a request. Configured servers and their tools are injected into the prefix of every request whether or not they are ever called, so they pay a tool-schema overhead on each turn. The tool flags that dead weight rather than reporting it, and the same reasoning appears in the window occupancy view, which decomposes what is occupying the context window right now, from system prompt through every tool schema, MCP servers, messages and generated output, into rows by source. The page's point about caching is the useful one: a stable schema block of around forty thousand tokens is cheap once it is cached, but it still displaces the code and the conversation that matter. So the tool measures occupancy rather than only the bill.

Editorial conclusion

This tool fits someone whose bill surprised them and who suspects the context window rather than the model, since that is the question it is built to answer. Three things to check before you trust a number from it. Whether you are reading the total or a split, because the page is explicit that the total matches the provider's own usage while the breakdown between sources in the same request is an estimate calibrated against that total. When the prices come from, since the package bundles a price snapshot and a script refreshes it, so a stale snapshot can misprice a new model. And what the capture does to your setup, since one supported agent needs a local certificate authority installed and capture only covers runs started after installation, with no history.

Frequently asked questions

How do I install cost-xray?

Fetch the installer and pipe it to the shell with curl and bash. It asks which agents to capture, Claude Code, Codex or both, and the prompt can be skipped by setting COST_XRAY_AGENTS to claude, codex or all. If you already cloned the repository you can run the script from it instead. After installing you open a new terminal, and agents started from there are captured with no flags and no base-URL change.

Does cost-xray need API keys or a Claude Code account?

The requirements say no API keys, no account and no configuration changes to your agent, describing capture as a transparent local hop, and the supported platforms are macOS and Linux. Claude Code is captured with a reverse proxy and a base-URL override with no certificate, while Codex is captured with a forward proxy and a scoped local certificate authority installed by a self-healing wrapper.

Is the per-source token cost in cost-xray exact?

The total is, and the split is not. Because Claude's tokenizer is private, the tool estimates with a general tokenizer, applies targeted corrections to the parts it mis-sizes most such as thinking blocks and tool schemas, and scales the rest so the calibrated total matches the provider's own usage. The page states the total and therefore the bill is exact while only the split between sources in one request is approximate, with an opt-in exact mode announced as coming soon.

How much data does cost-xray store?

It keeps the complete raw traffic but deduplicates it, storing each unique block such as a message, schema or tool result once with a small per-turn delta, and rebuilding full per-turn bytes on demand. The page says disk stays small even across sessions measured in millions of tokens, because deduplication removes the repetition created when a long session re-sends its whole history on every turn. Uninstalling the services keeps the captured data.

Official sources

  1. Issues
  2. License: MIT
  3. README
  4. tigerless-labs/cost-xray on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tigerless-labs-cost-xray.svg)](https://hysenlabs.com/projects/tigerless-labs-cost-xray)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tigerless-labs-cost-xray.svg)](https://hysenlabs.com/projects/tigerless-labs-cost-xray)

Was this useful?