Claude Code Spend Guard: Hard Daily Cost Cap Hook

Claude Code Spend Guard is a one-file Node.js hook that turns a dollar figure into a hard stop. Set a daily cap, a per-session cap or a rolling 5-hour window, and when the number is reached the next prompt is rejected before it reaches the model and the next tool call is blocked mid-task, each with a one-line reason. It is built for developers and small teams running Claude Code on an API key or a Max plan who want a ceiling they do not have to watch.

It reads the transcripts Claude Code already writes under ~/.claude/projects, counts each response once (Claude Code writes a response once per content block, so a plain sum overcounts by about 2x), and prices it from a table checked against Anthropic's pricing page on 13 October 2026: Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5 with its over-100K-token tier, cache writes, cache reads and fast mode. No dependencies, no network calls, nothing leaves your machine.

What You Get

• hooks/spend-guard.mjs — the guard itself: reads today's transcripts, prices them, warns at 80% of the cap and blocks at 100% using the exit-code mechanism documented in the Claude Code hooks reference. Handles missing folders, malformed lines, unknown models and 100 MB transcripts by streaming.
• config/caps.json and config/prices.json — the cap (daily USD, session USD, warn percentage, optional 5-hour window) and the October 2026 price table. Edit the numbers, nothing else.
• install/settings.snippet.json and INSTALL.md — the exact hooks block to paste into ~/.claude/settings.json and the three-step install, including how to confirm the hook fires.
• scripts/cost-per-pr.mjs — groups spend by repository and git branch and writes a CSV, so you can see what each pull request cost. A sample CSV is included.
• --report mode — a per-model table for today, the cap status and your most expensive sessions, printed in the terminal.
• tests/run.sh with fixtures — 53 checks you can run yourself in under a second: under the cap, over the cap, malformed lines, large files, pricing cases to the cent.
• README, VERIFY.md, CHANGELOG and a single-buyer commercial licence — VERIFY.md records the real test output and a live blocking run inside Claude Code 2.1.296.

How to Install

1. Unzip anywhere, for example ~/.claude/spend-guard. Node.js 20 or newer is the only requirement.
2. Open config/caps.json and set dailyUsd. Twenty dollars is a sensible first value for a solo developer.
3. Paste the block from install/settings.snippet.json into ~/.claude/settings.json under hooks, adjusting the path.
4. Run node hooks/spend-guard.mjs --report to see today's spend, then bash tests/run.sh to confirm the install.

From the next prompt on, Claude Code calls the guard before every prompt and every tool call. Once over the cap, Claude cannot raise it for you: editing the cap needs a tool call, and tool calls are blocked.

Who This Is For

• Developers paying for Claude Code through an API key who want a hard stop, not an email alert that arrives after the bill.
• Max 5x and Max 20x subscribers who want to know what their usage would cost at list price, and to keep agent runs inside a budget.
• Team leads who need cost per branch or per pull request for a weekly review.
• Anyone who has watched an agent loop burn through a day of budget in an afternoon.

Read the limits before you rely on the number: the guard estimates from local transcripts at list prices, it does not read Anthropic's billing, and it only sees usage on the machine it runs on. It pairs with the free Agent Run Cost Simulator for planning a budget, and sits alongside the other packs in best Claude Code configs. Browse the rest of the catalog at /browse.