cost-xray
See what Claude Code and Codex actually send to the API — and what each part of the request costs.
- Source repo
- tigerless-labs/cost-xray
- Stars
- ★ 6.1k
- Last updated
- 5d ago
- License
- MIT
- Primary language
- Python
- FA score
- 65/100 · Some gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code · OpenAI API · Claude API
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- An agent bill jumped and you need to know whether MCP schema prefixes, thinking tokens or tool output are responsible
- Not a fit if
- Teams that need native Windows support
- Users wanting to analyze past sessions — captures are forward-only
- Anyone needing exact per-source token splits today (currently estimated)
- Source review
- 65/100 · Some gaps
What does this agent do, and when should you use it?
cost-xray is a local wire-capture and cost-attribution tool for two coding agents: Claude Code and Codex. Instead of reading local transcripts, it runs mitmproxy as a transparent local hop — reverse proxy with a base-URL override for Claude Code, forward proxy plus a scoped local CA for Codex — and records the real API requests and responses. Traffic is redacted (Authorization, API keys, cookies, secret-looking body fields) before anything lands in ~/.cost-xray/sessions/, and a separate materializer tokenizes and prices it off the request path. The output attributes fresh, cache-read, cache-write and output costs back to the sources inside a request: system prompts, tool schemas, MCP servers, individual tool calls and message buckets. Everything is browsed through a terminal TUI launched with the cx command from any directory.
The installer deploys background capture services (auto-start on boot, self-healing, port-adaptive) and asks which agents to capture. At runtime mitmproxy binds to 127.0.0.1, relays the request, and writes only redacted raw request/response bytes to ~/.cost-xray/sessions/. A materializer later rebuilds each turn's full context from those raw bytes, splits tokens by source, and prices them with LiteLLM data. Because Claude's tokenizer is private, cost-xray estimates with tiktoken, applies targeted corrections to parts it mis-sizes (thinking, tool schemas), and scales the remainder so the calibrated total matches the provider's usage figure — the total is exact, the split between sources is approximate. Storage deduplicates repeated blocks (each unique message, schema or tool result stored once) with a tiny per-turn delta, rebuilding full bytes on demand. The TUI drills from agent → project → session → category → MCP server → tool → per-turn call → real output, and shows context-window occupancy plus unused MCP overhead.
- An agent bill jumped and you need to know whether MCP schema prefixes, thinking tokens or tool output are responsible
- You run several MCP servers and want to find ones injected into every prefix but never actually called
- You are deciding whether a Read or Bash tool's large output should be capped at the source
- You want to explain cache-read versus cache-write behavior in a session and check whether the prefix keeps being rewritten
- You want to observe what Claude Code or Codex actually sends, without editing your agent configuration
How do you install or deploy this agent?
Requires macOS or Linux and a supported agent (Claude Code or Codex). No API keys, account or agent config changes are needed. Run the installer:
curl -fsSL https://raw.githubusercontent.com/tigerless-labs/cost-xray/master/install.sh | bashThe installer asks which agent(s) to capture and prompts even under curl piping. To skip the prompt (for example in CI):
COST_XRAY_AGENTS=claude bash install.shIf you already cloned the repo, run it locally instead:
./install.shAfterwards open a new terminal: capture is forward-only and applies to runs started in that new shell.
How do you use this agent?
In the new terminal, run claude or codex exactly as before — no flags, no base-URL change. Then open the TUI from any directory:
cxCLI commands:
cx status # service state, live ports, sessions captured
cx stop # stop monitoring; proxies down, agents run direct (uncaptured)
cx start # resume monitoring
cx restart # restart the proxies after a config change
cx install # (re)install the chosen agents and remove the rest
cx uninstall # remove services and shell wrappers (keeps captured data)To change the port or upstream, edit ~/.cost-xray/env and run cx restart. Delete ~/.cost-xray/ to clear all captured data.
What are this agent's strengths and limitations?
- Reads actual API requests, so system prompts, injected tool schemas and MCP prefixes that never appear in transcripts become visible
- Attributes cost down to a single tool call and its output, with fresh/cache-read/cache-write/output splits instead of a session sum
- Non-invasive capture: no certificate for Claude Code, agent-scoped CA for Codex that never enters the system trust store, and a wrapper that falls back to direct runs if the proxy fails
- Redaction happens before anything hits disk, data stays under ~/.cost-xray/ with no telemetry, and deleting the directory clears it
- Deduplicated storage with per-turn deltas keeps disk use small even across million-token sessions
- Analysis runs off the request path, so tokenizing and pricing never add latency to live relay
- macOS and Linux only; no Windows path is documented
- Forward-only capture: sessions that predate installation are not recorded
- Claude token splits between sources are calibrated estimates, since no official tokenizer exists; the opt-in exact mode is not yet shipped
- Depends on mitmproxy plus systemd-based services for auto-start and self-healing; non-systemd environments need manual mode
- Supports only Claude Code and Codex today; each new agent needs its own adapter module
- No versioned releases documented; you install from install.sh or the repository directly
How does this agent compare with similar options?
The README explicitly contrasts itself with log-based usage tools, naming ccusage and codeburn. Those tools read local transcripts and price sessions by model, day or task, answering "how much did I spend." They cannot see the system prompt, injected tool schemas, MCP schemas, reminders and provider-added blocks, which are assembled at request time and never written to the transcript — the README states that invisible prefix can be roughly half the context or more in real coding-agent requests. cost-xray reads the raw API request instead, so it can produce per-source token counts and dollars for schemas, MCP servers, tools and message buckets, along with cache read/write/fresh splits per span.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| cost-xray This agent | 65 · Some gaps | CLIFree | ★ 6.1k | 5d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| AgentOps | 50 · Major gaps | Library / SDKFreemium | ★ 5.9k | 3mo ago | Python | OpenAI API · Claude API |
| AgentAcct | 61 · Some gaps | CLIFree | ★ 767 | 17d ago | Python | Codex · Claude Code |
| ClawMetry | 81 · Good | CLIFreemium | ★ 436 | 3d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Trust: the proxy binds to 127.0.0.1, sends no telemetry, and recursively redacts Authorization/x-api-key/Cookie and secret-looking body fields before disk, with tests/test_addon.py asserting redaction through the real hooks — data_flow_transparency and sensitive_data_handling earn 3. However install runs via curl|bash and writes shell rc, systemd/launchd services and linger, a broad system-level side effect where user confirmation rests only on an install prompt, so user_confirmation and least_privilege are 2; Codex also generates a local CA (scoped, not in OS trust store) which is sensitive. Dependencies are declared only with lower bounds (mitmproxy>=10, tiktoken>=0.7, rich>=13), no lock or hashes, so dependency_security is 1. Rollback exists via cx stop/uninstall keeping data, but uninstall only cleans the bashrc block, so rollback is 2. Source attribution credits mitmproxy/llm-interceptor/LiteLLM in README Credits but not per-file, so 2.
Reliability: README, docs/install.md, SECURITY.md and code/tests agree on capture paths, ports, redaction and self-healing, so self_consistency is 2. Dependency availability is weak — only lower-bound pins, no lockfile, no vendored deps, and install.sh is not in the evidence so its venv/uv provisioning cannot be checked — 1. Failure messages: tests cover raw-write failure logging, SSE garbage tolerance, unknown-type surfacing, and troubleshooting lists common errors, but there is no unified error/exit-code documentation, so 2.
Adaptability: clearly targets Claude Code and Codex users with GUI/Cursor and manual-mode scenarios, audience_and_scenarios 2. Capability boundaries are stated (local-only capture, forward-only, does not change agent behavior or cost, tokenizer is estimator+calibration), 2. Trigger precision: _matched precisely matches /v1/messages, /responses etc. and excludes count_tokens, covered by tests, 2. Environment fit limited to macOS/Linux with manual fallback for WSL/containers and no Windows, 2.
Convention: README is well structured with layered docs, information_architecture 2. install_notes are thorough (systemd/launchd, linger, ports, CA, manual mode, uninstall, troubleshooting), 3. Naming stability is weak — tests reference both context-xray and cost-xray, and pre-1.0 with no stable interface promise — 1. Examples and FAQ: screenshots, command examples and troubleshooting Q&A but no dedicated FAQ, 2. Known limitations are stated (approximate tokenizer, forward-only, pre-1.0), 2. LICENSE is full MIT, 3. Versioning is only pyproject 0.1.0 with no CHANGELOG, 1. Maintenance responsibility points only to master and a security email with no SLA or maintainer roles, and the publisher is unverified, 1.
Effectiveness: output is a TUI drilling to MCP/tool/per-call cost attribution, output_usability 2. It adds genuine marginal value over log-based tools (request-time prefix, schemas, MCP waste) but requires mitmproxy interception and deployment effort, marginal_value 2. Cost-benefit: local, no telemetry, deduplicated storage limits disk, but needs a resident service and CA, 2.
Verifiability: most README claims (redaction, binding, dedup, tokenizer calibration) map to code and tests, but comparative claims like 'nothing else prices below the tool' have no external evidence, so claim_traceability is 1. Cross-source corroboration is good — README, SECURITY.md, docs/install.md and tests reinforce each other, 2. Fact/inference separation: README explicitly labels the tokenizer as an estimator, calibration residuals as approximate, and exact mode as coming soon, so 2.
- Install runs via curl|bash and writes shell rc, systemd/launchd services and linger — a system-level change; review install.sh before running and prefer ./install.sh from a clone.
- Codex capture generates a local mitm CA; it is claimed scoped to the codex command and not in the OS trust store, but verify its scope and uninstall cleanup.
- Dependencies are declared only with lower bounds, no lockfile or hashes, so supply-chain reproducibility is weak; pin versions before production use.
- For Claude the tokenizer is an estimator plus proportional calibration, so per-source token splits within a request are approximate and should not be treated as exact billing.
- Publisher is unverified by FollowAgents; maintenance responsibility and update path point only to master and a security email, with no SLA or versioned release notes.
- Project is pre-1.0 and naming is inconsistent (context-xray vs cost-xray appear in docs/tests), so interfaces and names may change.