How Claude Spend Guard tracks reported costs — and where it can still fail

Oscar Lansh — Sun, 01 Nov 2026 18:20:17 +0000

Claude Code's --output-format stream-json output includes total_cost_usd in the final result event. Claude Spend Guard parses that field and compares it with the cap you set when that event arrives.

npx claude-spend-guard --cap 5 -- claude -p "refactor the auth module"

Important limitation: in a single claude -p run, the first dollar-cost value may arrive only after the work is finished. Spend Guard cannot use that final value to stop the same run early, so it is not a per-request or in-flight hard cap. The command below shows setup, not a guarantee that an over-budget run will be interrupted before it completes.

When Spend Guard receives a supported cost report at or above the cap, it sends SIGTERM to the process group, waits for a grace period, then sends SIGKILL to anything still running. There is no dashboard, account, or server: it is a local process wrapper.

Why a wrapper instead of a dashboard or an SDK hook

Usage dashboards such as claude-spend and claude-usage help you review spending after the fact. SDK middleware such as llm-spend-guard and budget-guard applies when your own code calls a provider API. I wanted a guard for the claude CLI process itself, including unattended terminal runs.

Claude Code is the only CLI for which this package currently parses a confirmed dollar-cost field. Other CLIs do not expose the same confirmed cost signal in their output, so their support uses weaker fallback modes instead of implying the same behavior.

What happens when parsing breaks

The tool has three visible states:

ENFORCING — a supported cost value has been parsed and is being compared with the cap. This does not mean a cost is available during an in-flight request; for a single claude -p run, the final cost can arrive after the run ends.
DEGRADED — the output format no longer matches what the parser expects; the tool warns instead of quietly implying the cap still works.
UNVERIFIED — an unconfirmed CLI or version is being used; the tool asks for confirmation before running without verified enforcement.

The failure mode I wanted to avoid was a tool that stops parsing cost but still claims the cap is being enforced. The final-event timing is a separate limitation: correct parsing cannot make a cost value available before Claude emits it.

Zero telemetry, enforced by CI

The package has no runtime dependencies. Its test suite stubs Node networking primitives and checks that the wrapper does not make network calls; a dependency blocklist also guards against adding common telemetry packages later.

What it cannot do

For a single claude -p run, it cannot stop the run based on a dollar value that only appears in the final result event. The run may already be over by then.
It cannot undo cost already incurred before a supported report reaches the cap.
A child process that deliberately detaches from the process group may escape the kill.
Windows does not provide a direct equivalent of Unix SIGTERM, so graceful shutdown is weaker there.

Those limitations are documented in the README.

npx claude-spend-guard --cap 5 -- claude -p "your prompt"

The tool is MIT licensed and runs locally. If you run Claude Code unattended, I’d like to hear which edge cases you would test first.

npm: https://www.npmjs.com/package/claude-spend-guard
GitHub: https://github.com/toxot-net/claude-spend-guard

DEV Community: Oscar Lansh

How Claude Spend Guard tracks reported costs — and where it can still fail

Why a wrapper instead of a dashboard or an SDK hook

What happens when parsing breaks

Zero telemetry, enforced by CI

What it cannot do