claude-spend-guard 如何阻止 Claude Code 工作階段支出失控，以及仍可能失效之處
How claude-spend-guard stops runaway Claude Code sessions — and where it can still fail
claude-spend-guard 會讀取 Claude Code 在 --output-format stream-json 模式輸出的 total_cost_usd，與用戶設定的上限比較；累計成本超限時，先向程序羣組發送 SIGTERM，寬限期後再向仍運行的程序發送 SIGKILL。
Claude Code reports its own running cost. When run with --output-format stream-json, it emits a total_cost_usd value that claude-spend-guard can monitor. The tool reads Claude Code's stdout, parses that field, and compares it with a cap you set.
npx claude-spend-guard --cap 5 -- claude -p "refactor the auth module"
When reported cumulative cost crosses the cap, the wrapper 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.
That scope is why the confirmed dollar-cap enforcement claim is for Claude Code. Other CLIs do not expose the same confirmed cost signal in their output, so their support uses weaker fallback modes instead of pretending the same guarantee applies.
What happens when parsing breaks
A tool meant to stop runaway spend has to be clear when it cannot do that job. It has three visible states:
- ENFORCING — the cost output is being parsed and compared with the cap.
- 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 enforcing the cap but still claims it is protecting the run.
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
- It cannot undo the request that first crosses the cap. It can stop a subsequent request, but the crossing request has already incurred its cost.
- 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 · dev.to