Skip to main content

spend-explainer

Tells you why your Claude bill went up, and refuses to show an AI-written explanation unless its numbers check out.

It's built on the Usage and Cost Analytics API, which launched in beta on October 29, 2026. It ships as a Claude Code plugin, and all bundled data is synthetic.

Try it in one minute

You need Python 3.9 or newer, and you don't need an API key. It has no dependencies.

pip install spend-explainer
spend-explainer demo

Or run it from a clone, with nothing installed:

git clone https://github.com/thejaredchapman/spend-explainer.git
cd spend-explainer
python3 explain_spend.py demo

The examples below use python3 explain_spend.py. If you installed with pip, use spend-explainer instead. The evals/ scripts and tests are only in the clone.

The demo walks through one spike, a broken prompt cache, one stage at a time. It runs a correct answer and then an answer with an invented number. The second ends like this:

  [FAIL] numbers    not found in the data: $9999.99

STEP 5  Decide what to show (spend_explainer/pipeline.py)
  shown from : deterministic fallback
  status     : spike (cache_regression)
  driver     : wrkspc_01SYNTHSUPPORT
  headline   : Daily spend went from $270.62 to $431.51 (1.59x).

The answers in the demo are hand-made stand-ins, not real model output, so no key is needed.

To see all 6 scenarios and 5 answer types, and to run the tests:

python3 explain_spend.py demo --all
python3 -m unittest discover -s tests

demo --all should end with Unexpected outcomes: 0, and the tests should end with OK.

How it works

Models are good at explaining, and code is good at being right about numbers. So each does one job:

 API data --> rules compute facts + a conclusion
                   |                    |
                 facts           (hidden from model)
                   v                    |
                 model                  |
                   v                    v
                 answer ---> reliability check
                                  |
                       pass ------+------ fail
                        v                  v
                 model's answer      plain rule-based report
  1. Parse. Convert the API's amounts from cents, and drop days that are still incomplete.
  2. Analyze. Compare the last 3 days with the earlier baseline, using rules and no model.
  3. Explain. The model gets the facts, but not the conclusion.
  4. Verify. Six checks compare the answer with the facts. These cover its format, conclusion, driver, IDs and every number.
  5. Decide. One failed check means the user sees the plain report instead.

docs/ARCHITECTURE.md explains every stage, the decisions behind them, and what the check can't catch. The code is meant to be read in that same order, starting at spend_explainer/analytics.py.

Commands

Command What it does Needs
demo Walks through the pipeline. Add --all for every scenario Nothing
prompt --scenario NAME Prints the exact model prompt Nothing
analyze --scenario NAME Prints the facts and the rules' conclusion Nothing
verify --scenario NAME --answer FILE Checks an answer. Exit 0 if shown, 1 if it fell back. Add --summary to hide rejected values Nothing
project --scenario NAME --days 30 Multiplies the daily increase over a period, with code rather than by hand Nothing
run --scenario NAME Asks a real model, then verifies ANTHROPIC_API_KEY
fetch --start T --end T --out DIR Downloads your real data ANTHROPIC_ADMIN_API_KEY

Scenarios are quiet, one_day_outlier, model_mix_shift, cache_regression, volume_increase and broad_growth. Commands that take --scenario also accept --data DIR for a folder with usage.json and cost.json.

Use it with a real model

export ANTHROPIC_API_KEY="your key"
python3 explain_spend.py run --scenario cache_regression

If the call fails, or the answer fails a check, you still get the plain report. The default model is claude-haiku-5-5, and --model changes it.

Use it on your real spend

This needs an Admin API key. Enterprise organizations use a key with the read:analytics scope.

export ANTHROPIC_ADMIN_API_KEY="your admin key"
python3 explain_spend.py fetch --start 2026-10-01T00:00:00Z --end 2026-10-18T00:00:00Z --out my-data
python3 explain_spend.py run --data my-data

A request can cover at most 31 days, and you need at least 6 complete days. Data typically refreshes within 4 hours, but can take up to 24.

run sends your spend figures, workspace IDs, API key IDs and model names to the Claude API.

Use it as a Claude Code skill

claude plugin marketplace add thejaredchapman/spend-explainer
claude plugin install spend-explainer@spend-tools

Start a new session and ask "why did my Claude spend go up?". Claude itself writes the answer, so no API key is needed for the synthetic scenarios. The same check still decides what you see.

On default permissions, Claude Code asks once whether to use the skill. After that, the skill's commands run without further prompts.

What it runs and sends

Action What happens
demo, analyze, prompt, verify, project Run locally, read local files, and send nothing
run Sends the prompt to api.anthropic.com with ANTHROPIC_API_KEY. The prompt holds spend figures, workspace IDs, API key IDs and model names
fetch Reads usage and cost data from api.anthropic.com with ANTHROPIC_ADMIN_API_KEY, and writes it to the folder you choose
The skill Runs python3 on the commands above, and writes your answer to a temporary file. Claude reads the prompt, so the data goes wherever your Claude session runs
evals/ scripts (clone only) Send the synthetic prompts to Claude Code or to your local EvalForge server

It stores no keys, collects no telemetry, and runs no code from the network. The skill needs to run python3 on your machine, and it has only been tested in Claude Code.

Evals

The evals run the real prompt against real models. You can test the eval itself for free:

python3 evals/dry_run.py

If you're logged in to Claude Code, this runs all 6 scenarios on 3 Claude models and shows how often each answer would be shown:

python3 evals/run_claude_cli.py
python3 evals/score_results.py

This cost about $0.13 to $0.39 per run in testing. For the judged rubric and non-Claude models, use EvalForge Lite, which needs an OpenRouter key. docs/EVALS.md covers both, and the latest results.

Verification status

Part Status
Parsing, analysis, verifier, fallback Covered by the unit tests
Fixture format Matches the API reference's documented fields, but hasn't been compared with a real response
Eval cases, result scoring Run through EvalForge's real /api/run with models mocked
fetch and run Tested with mocked HTTP only, never against the live APIs
Conclusions on synthetic data 36 of 36 real answers correct across Haiku 5.5, Sonnet 5.5 and Opus 5.5. See docs/EVALS.md
Verifier strictness Caught 35 of 35 wrong figures planted in real answers
EvalForge live run Ran through OpenRouter on 3 models. Opus passed 6 of 6. Sonnet 4.5 and Haiku 4.5 passed 0 of 6, because they wrapped their JSON in fences. See docs/EVALS.md
Reasoning and advice quality Rubric judge scored 16 of 18 answers 5 out of 5 and 2 answers 4 out of 5, but it has not judged the Claude 5.5 answers
Plugin manifest Passes claude plugin validate .
Skill Tried in headless and interactive Claude Code sessions on synthetic data. It triggered without being named, and showed the fallback for a planted bad number. On default permissions the only prompt was the skill consent

Troubleshooting

Message Fix
python3: command not found Install Python from python.org
Need at least 6 complete days Fetch a longer date range, or pass a smaller --window-days
ANTHROPIC_API_KEY is not set Export the key, or use demo, which doesn't need one
HTTP 401 or 403 from fetch Check that you're using an Admin API key, not a regular API key
Could not reach EvalForge Start EvalForge first. See docs/EVALS.md
Every answer shows json failed The model is wrapping its JSON in fences. Run prompt, then see docs/EVALS.md

Project layout

explain_spend.py        runs the command line without installing
spend_explainer/        the pipeline; start with __init__.py
  data/fixtures/        synthetic API responses, one folder per scenario
  data/recorded/        hand-made stand-in answers
skills/explain-spend/   the Claude Code skill
evals/                  EvalForge test cases and scoring
scripts/make_fixtures.py  regenerates the data folders
tests/                  unit tests, no network
docs/                   architecture and eval guides

License

MIT

Metadata

Release files for spend-explainer 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spend-explainer 0.1.0
File Size Uploaded Provenance Actions
spend_explainer-0.1.0.tar.gz 61.8 kB Without provenance Details for spend_explainer-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for spend-explainer 0.1.0
File Interpreter ABI Platform Actions
spend_explainer-0.1.0-py3-none-any.whl Python 3 none any Details for spend_explainer-0.1.0-py3-none-any.whl

Total release size: 134.7 kB

Release files / spend_explainer-0.1.0.tar.gz

Download URL spend_explainer-0.1.0.tar.gz
Size 61.8 kB
Tags Source
SHA-256 checksum
How to use checksums
e7961f9b783fe65cefc09117c3033cd80b27cfdb2c774f4ef5266675eafe3927
BLAKE2b-256 checksum
How to use checksums
53743e490772a326af9115bae8d79b55e7bee645a33f59e6b2b3ad32894fef1f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.8 {"installer":{"name":"uv","version":"0.11.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / spend_explainer-0.1.0-py3-none-any.whl

Download URL spend_explainer-0.1.0-py3-none-any.whl
Size 72.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1ee5accab96b257e087049a1c9e35670ccbf4a45f483d1b863ba23f0a5f20c24
BLAKE2b-256 checksum
How to use checksums
60f2a3652cc6be9b97055801f5fb88f559074f0aec89d48996b136ccc26e9867
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.8 {"installer":{"name":"uv","version":"0.11.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for spend-explainer 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page