Skip to content
Back to search

Cost-guard

SkillWorks with Claude CodeGitHub

Stop Claude Code burning your credits — cost estimates before big runs, daily and per-task spending caps, error-loop brake. Free Claude Code skill with hooks.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kml11kml--cost-guard/badge.svg)](/listings/kml11kml--cost-guard)

HTML

<a href="/listings/kml11kml--cost-guard"><img src="/api/listings/kml11kml--cost-guard/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Install with the skills CLI
npx skills add kml11kml/cost-guard

# Or copy it manually
mkdir -p ~/.claude/skills
cp -r cost-guard ~/.claude/skills/cost-guard

Then ask Claude Code to estimate before any big run — the skill does the rest.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 41 lines
  1. # Cost Guard — Spending Caps and Loop Brakes for Claude Code
  2. Use this skill whenever a task could get expensive: long runs, many files, subagents, scheduled or recurring jobs, or anything left running unattended. Never start an expensive run without an estimate and a cap.
  3. Why this exists: users are publicly reporting Claude Code burning their credits with no cap and no estimate. In anthropics/claude-code#110395 a weekly allowance of 361.6M tokens ran out in 3.83 days plus $45.61 overage, because simple condition checks were built as full AI runs every 5 to 10 minutes with no cost estimate, no cap, and a failure loop that repeated 39 times. In a separate November 2026 incident a Stop hook that refused to let Claude stop burned about $335 in 3 hours across 2,736 model calls. Both were preventable with the rules below.
  4. ## Estimate before a big run
  5. - Estimate the cost before any big run and show the user the number.
  6. - For a one-off run use `scripts/cost_guard.py estimate --model sonnet --input N --output N`.
  7. - For a recurring or scheduled job use `scripts/estimate_recurring.py --interval-min M --tokens-per-run N --weekly-allowance W`.
  8. - Treat the recurring estimate as a floor, not a ceiling: retries, failure loops and overlapping jobs only push real spend above it.
  9. - Wait for the user's yes when the estimate is above $2 or above their cap.
  10. - Never build a recurring job without stating runs per day, tokens per day, and days until the allowance runs out.
  11. ## Set caps first, then record
  12. - Set a daily cap and a per-task cap before the work starts. Defaults are $10 a day and $5 a task; change them in `~/.cost-guard/config.json` or with `COST_GUARD_DAILY_CAP` and `COST_GUARD_TASK_CAP`.
  13. - Record every finished run with `scripts/cost_guard.py record --model M --input N --output N --task LABEL`.
  14. - Check the cap before an expensive step with `scripts/cost_guard.py check --task LABEL --est-cost X`. A blocked check means stop and ask the user, not find a way around it.
  15. - Show `scripts/cost_guard.py status` at the start and the end of a session.
  16. ## Brake error loops
  17. - Give every repeated failure a stable signature and record it with `scripts/cost_guard.py fail --signature "area:what-failed"`.
  18. - After 3 identical failures in one day, stop. Report what failed, what changed between tries, and ask the user what to do next.
  19. - Never retry the same failing command without changing something first.
  20. - Never write a Stop hook that blocks Claude from stopping unconditionally. A Stop hook that sends Claude back into the loop is how the $335 burn happened: each re-entry re-read the whole context, and the built-in 8-block limit resets whenever a tool call happens in between. If a hook must check completion, read `stop_hook_active` from the hook input and exit 0 when it is true.
  21. ## Ask before expensive operations
  22. - Ask before anything that spends a lot at once: full-repo refactors, multi-agent workflows, long headless runs, and any job that runs while the user is away.
  23. - Prefer the cheaper model when the job allows it. Say which model you picked and why.
  24. - Keep the user informed while a long job runs: cost so far, cap remaining, and what happens next.
  25. ## Honest limits
  26. - The guard works off a local ledger of token counts you record. It cannot see real billing, plan quotas, or usage limits.
  27. - Claude Code hooks cannot cap a model API call. They can only gate tool calls and report at session start and end.
  28. - All prices in the scripts are API list prices from November 2026. Verify current pricing before relying on them and update `config.json` when they change.
  29. - This skill reduces surprise bills. It does not guarantee any saving and it never executes a payment.
README.md · README · 144 lines
  1. # Claude Code Cost Guard — Stop Claude Code Burning Your Credits
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Claude Code Skill](https://img.shields.io/badge/Claude_Code-Skill-blueviolet)](https://github.com/kml11kml/cost-guard)
  4. [![Version](https://img.shields.io/badge/version-0.1.0-blue)](https://github.com/kml11kml/cost-guard)
  5. **Claude Code has no spending cap and shows no cost estimate before a run.** Users are publicly reporting burned weekly allowances and surprise bills. Cost Guard is a free Claude Code skill that estimates cost *before* big runs, enforces daily and per-task spending caps from a local ledger, and brakes error loops after 3 identical failures — so a runaway job stops itself instead of emptying your quota.
  6. ## The problem — real reports, November 2026
  7. - In [anthropics/claude-code#110395](https://github.com/anthropics/claude-code/issues/110395), simple condition checks were built as full AI runs every 5 to 10 minutes, about **40,000 tokens each**. No cost estimate, no check of the weekly limit, no spending cap, no brake on repeated failures (one failure loop ran **39 times**). The weekly allowance of **361.6M tokens ran out in 3.83 days**, followed by **$45.61 of paid overage**.
  8. - In a separate November 2026 incident, a developer's Stop hook refused to let Claude stop until tests passed and CI was green. The hook blocked **1,314 stops**, the session made **2,736 model calls in about 3 hours**, and the burn was priced at about **$335** at API list rates.
  9. Both were preventable: estimate first, cap the spend, brake the loop.
  10. ## Quick start
  11. ```bash
  12. # Install with the skills CLI
  13. npx skills add kml11kml/cost-guard
  14. # Or copy it manually
  15. mkdir -p ~/.claude/skills
  16. cp -r cost-guard ~/.claude/skills/cost-guard
  17. ```
  18. Then ask Claude Code to estimate before any big run — the skill does the rest.
  19. ## How it works
  20. | Step | What happens |
  21. | --- | --- |
  22. | **Estimate** | `cost_guard.py estimate` prices a run from token counts before it starts. `estimate_recurring.py` prices a recurring job: runs per day, tokens per day, days until the weekly allowance runs out. |
  23. | **Cap** | A local ledger tracks spend per day and per task. Defaults: **$10/day, $5/task**. `cost_guard.py check` blocks (exit code 2) when a cap would be exceeded. |
  24. | **Brake** | `cost_guard.py fail` counts identical failures by signature. The **3rd identical failure in a day** stops the loop and asks the user what to do next. |
  25. | **Report** | Example hooks show spend at session start and end, and gate Bash calls when the cap is hit. |
  26. ## Worked example — the #110395 case, priced before building
  27. ```bash
  28. python3 scripts/estimate_recurring.py \
  29. --interval-min 10 --tokens-per-run 40000 --weekly-allowance 361600000
  30. ```
  31. Output: 144 runs a day, 5.76M tokens a day, allowance gone in ~63 days on
  32. paper — but the real incident burned it in 3.83 days, because retries,
  33. failure loops and overlapping jobs piled on top of the floor estimate. That
  34. gap is the whole point: the estimate is a floor, not a ceiling, and that is
  35. exactly why the skill says **never build a recurring job without stating runs
  36. per day, tokens per day, and days until the allowance runs out**.
  37. ## Install (full)
  38. ```bash
  39. # 1. Copy the skill into Claude Code's skills directory
  40. mkdir -p ~/.claude/skills
  41. cp -r cost-guard ~/.claude/skills/cost-guard
  42. # 2. Optional: set your caps (defaults: $10/day, $5/task, loop limit 3)
  43. mkdir -p ~/.cost-guard
  44. cp ~/.claude/skills/cost-guard/config.example.json ~/.cost-guard/config.json
  45. # then edit ~/.cost-guard/config.json
  46. # 3. Optional: install the example hooks
  47. # Merge hooks/hooks.json into ~/.claude/settings.json under the "hooks" key.
  48. # Do NOT overwrite your existing settings.json -- merge the "hooks" object.
  49. # Check what is active with:
  50. python3 ~/.claude/skills/cost-guard/scripts/cost_guard.py config
  51. ```
  52. ## Usage
  53. ```bash
  54. G=~/.claude/skills/cost-guard/scripts/cost_guard.py
  55. # Estimate a run before starting it
  56. python3 $G estimate --model sonnet --input 1000000 --output 500000
  57. # Estimate a recurring job before building it
  58. python3 ~/.claude/skills/cost-guard/scripts/estimate_recurring.py \
  59. --interval-min 10 --tokens-per-run 40000 --weekly-allowance 361600000
  60. # Record a finished run (do this after every task)
  61. python3 $G record --model sonnet --input 800000 --output 120000 --task "refactor-auth"
  62. # See today's spend
  63. python3 $G status
  64. python3 $G status --task "refactor-auth"
  65. # Gate an expensive step (exit 2 = blocked)
  66. python3 $G check --task "refactor-auth" --est-cost 2.50
  67. # Record a failure; the 3rd identical failure in a day brakes the loop
  68. python3 $G fail --signature "tests-fail:auth" --task "refactor-auth"
  69. ```
  70. ## Why this skill
  71. - **It answers a real, public complaint** — not a hypothetical. The incidents above are linked GitHub issues and reports from November 2026.
  72. - **Stdlib only, no dependencies** — two Python scripts, one hooks file, plain JSON config. Nothing to install, nothing phoning home.
  73. - **It says what it cannot do** — see the limits below. No fake savings figure, no invented users, no testimonials.
  74. ## FAQ
  75. **Does it read my real Anthropic bill?**
  76. No. It works off a local ledger of token counts you record. If you never record a run, the ledger stays at $0 while the real bill grows. See the limits below.
  77. **Can a hook stop a model API call?**
  78. No. Claude Code hooks gate tool calls and report at session start/end. They cannot intercept a model call or read token usage from the API. The guard blocks the *next tool step* and the *next run* — it does not reach inside an in-flight call.
  79. **Can it guarantee I save money?**
  80. No. It reduces surprise bills by forcing an estimate, a cap, and a loop brake before the expensive work. It never executes a payment and guarantees no saving.
  81. **Is it financial advice?**
  82. No. It is a cost-control tool, not financial advice.
  83. ## Honest limits — read before relying on it
  84. - **Estimates, not billing.** The guard works off a local ledger of token counts you record. It cannot see your real Anthropic bill, plan quota, or usage limits.
  85. - **Hooks cannot cap a model call.** Claude Code hooks gate tool calls and report at session start/end. They cannot intercept or stop a model API call, and they cannot read token usage from the API.
  86. - **Prices change.** The scripts use API list prices from November 2026. Verify current pricing and update `~/.cost-guard/config.json` when they change. Cache reads are priced at 10% of the input price, which is an approximation.
  87. - **A Stop hook must never block stopping unconditionally.** The $335 burn happened because a Stop hook kept sending Claude back. If a hook checks completion, read `stop_hook_active` from the hook input and exit 0 when it is true. The example Stop hook in this skill only prints a status report and never blocks.
  88. - **No guarantee.** This skill reduces surprise bills. It does not guarantee any saving, and it never executes a payment.
  89. ## Files
  90. | File | What it is |
  91. | --- | --- |
  92. | `SKILL.md` | The skill rules |
  93. | `skill.yaml` | Skill metadata (name, version, description) |
  94. | `README.md` | This file |
  95. | `LICENSE` | MIT |
  96. | `scripts/cost_guard.py` | Ledger + caps + loop brake (stdlib only) |
  97. | `scripts/estimate_recurring.py` | Recurring-job estimator (stdlib only) |
  98. | `hooks/hooks.json` | Example Claude Code hooks |
  99. | `config.example.json` | Example caps and pricing |
  100. ## Custom work
  101. Need this fitted to your setup — custom caps, team ledger, CI guardrails, or a full Claude Code workflow with cost controls? Custom skill, plugin, and MCP builds are available as a service. Open an issue in this repo with what you need and the budget range; quotes are $150–500 per project, 50% upfront in USDT, rest on delivery.
  102. ## Version
  103. v0.1.0 — first version, 2026-11-21. Not financial advice. No verified savings figure; the incidents above are public bug reports, not this skill's results. No fake testimonials, no invented users.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.