Skip to content

Developer tools

Budget Guard puts a hard daily cap on Claude API spend

7 min read

Written by an AI model from the linked sources and checked against them by a second model. How we work

All about: Claude prices and limits →
Image: github.com

budget-guard is an MIT-licensed npm package that went public on August 19. It wraps an existing OpenAI, Anthropic or Gemini SDK client and refuses calls once a project’s spend for the day passes a dollar figure you set. How hard that cap holds depends on two settings: where the spend ledger lives, and whether the check runs before a call or after it.

The README on GitHub pitches it as a circuit breaker for indie developers who have seen “a $40 bill from a $5 task.” It is not a proxy. Requests still go straight to the provider, and the wrapper only counts tokens, prices them and decides whether the next request may go out. With Claude you write guard(anthropic.messages, { project: 'my-app', dailyCapUSD: 50 }) and then call ai.create(...) exactly as before. An optional second argument such as { feature: 'summarize' } adds a feature tag. Once the project is past $50 for the day, the next call throws BudgetExceededError before anything is billed, and spendReport('my-app') returns today’s spend per feature tag in dollars. The package has zero runtime dependencies. Adapters for the Vercel AI SDK (v5 and v7), LangChain.js, LlamaIndex.TS and Mastra rely on structural typing or optional peer dependencies. A hosted dashboard with cross-project spend and alerts is planned, and the README says the SDK stays free.

When does the check run?

By default the cap is checked against spend that has already been settled. That means a single call can overshoot: the call that crosses $50 goes through, and only the one after it is blocked. Calls still in flight aren’t counted either, so a fan-out of parallel requests can all pass the check at once. The README’s fix for both is an estimator, which prices a call before it is sent and blocks it if it would cross the cap.

The built-in estimator() estimates input at four characters per token from prompt, system and messages. It takes the output estimate from the declared max_tokens (or maxOutputTokens) and adds overhead for tool schemas when tools are passed. The author calls the chars/4 heuristic “fine for a circuit breaker.” For exact counts you can inject a tokenizer, and the README’s example uses gpt-tokenizer. Claude counts differ by tokenizer family, which is why an unofficial offline counter like ctok makes you pick the family with a version string.

For the newer Claude tokenizer generation, the estimator assumes about 30% more tokens on Opus 4.7 and later, Sonnet 5 and later, Fable and Mythos, and applies the correction automatically. That is still only one flat figure. Developers Digest quotes Anthropic’s migration guide as giving a range of roughly 1x to 1.35x depending on content, and quotes the June 2026 pricing docs as saying the new tokenizer “may use up to 35% more tokens for the same fixed text.” The same piece notes that Opus 4.8 is priced the same per million tokens as Opus 4.6 but can still produce a higher bill, because a million tokens no longer covers the same amount of text. Anthropic’s token-counting guidance tells developers to measure their own ratio on representative prompts.

The estimator matters even more when calls run in parallel. When the store supports it (the built-in memory, file and Redis stores all do), the estimated cost is reserved atomically before the call and corrected to the actual cost afterwards, so 100 parallel workers can’t all slip past the cap together. If a call fails, its reservation is rolled back. One of the bundled examples, precall-block.mjs, runs the reservation under 20 concurrent calls and needs no API key.

Memory, file or Redis

By default the ledger is held in memory for each process, which covers a single script, worker or agent. Cron jobs and short-lived scripts are where that quietly fails, the README says, because every run starts from $0. fileStore (imported from budget-guard/file) keeps the ledger in a single JSON file, so 100 runs a day share one cap. Writes are atomic: the store writes a temp file and then renames it. A corrupted file throws an error and doesn’t quietly reset the budget. The file store is meant for runs that happen one after another. Processes running at the same time should use Redis.

redisStore takes a node-redis v4 client and lets a fleet of instances enforce one cap that survives restarts. Its atomic reservation, the optional addIfUnder method, runs as a server-side Lua script. CI tests it against a real Redis for atomicity, TTL and the NOSCRIPT fallback. The underlying problem is a familiar one. Redis’s own rate-limiter docs point out that counters kept separately in each process break behind a load balancer. They add that a Lua script keeps the read, decide and update steps atomic, so concurrent requests can’t double-spend. The README sums up the tiers this way: memory is one process, file is one machine, Redis is a fleet. Any store that implements the small SpendStore interface (add, get, entries) can replace them.

Monthly caps have one trap. Setting period: 'monthly' with an IANA timezone resets the cap on your billing calendar instead of UTC, and an invalid zone throws when the guard is created. But Redis keys expire after about two days by default. A monthly cap therefore needs ttlSeconds set to cover the month (the README’s example is 40 days), or the counter disappears mid-month. The cap option is still called dailyCapUSD, even in monthly mode.

Streaming and Claude

For OpenAI streams, the wrapper adds stream_options: { include_usage: true } itself, because OpenAI only sends usage in the final chunk when that flag is set. Anthropic streams need provider: 'anthropic', so the wrapper reads usage from the message_start and message_delta events and skips the OpenAI-only flag. The typed helpers guardAnthropic, guardOpenAI and guardGemini set the provider for you. In either case the cap is checked before the stream opens, and the cost is recorded once, when the stream ends.

The Vercel AI SDK middleware meters both generateText and streamText. An over-cap streamText is blocked before the model call, but the error arrives on the SDK’s standard error channel (onError or await result.text). Because textStream swallows stream errors by default, a loop that reads only the text stream won’t see the block. Mastra agents run on AI SDK models, so the same middleware covers them. LangChain.js gets a callback handler, BudgetGuardHandler, that reads usage_metadata. In LlamaIndex.TS, a stream that carries no usage produces a warning and is not silently recorded as zero.

Usage formats are recognised automatically for OpenAI and the OpenAI-shaped APIs (Azure, Mistral, DeepSeek, xAI), Anthropic, Gemini, AWS Bedrock Converse and Cohere. Cached and reasoning tokens are charged at their own rates. xAI and Gemini report reasoning tokens outside the output count, and the wrapper adds them back. Prices come from a PRICES table shipped in the package, in USD per 1K tokens, and the README asks for pull requests to keep it current. A response whose usage the wrapper can’t read throws by default. You can opt out per guard with onMissingUsage: 'zero', or supply your own usageOf extractor.

Retry storms

The README argues that the most expensive bug class is not a big prompt but “a retry loop quietly re-burning money all night.” With retryStormThreshold set, the guard counts consecutive provider failures per feature and model pair and calls onRetryStorm once when the streak hits the threshold. A success resets the count and stamps retryCount on that call’s spend event, so the logs can show “this $0.40 call took 7 attempts.” Calls blocked by the cap don’t count; only those that reached the provider do. onSpend fires on every successful call with the project, feature, model, cost and day total. It runs synchronously just before the response is returned, so the README says to push heavy work onto a queue. onCap: 'warn' logs a warning and lets the call go through, which the README suggests for easing in.

Upgrading from 0.1 takes one change: spendReport() is now async, so every call to it needs an await. Everything else is backward compatible, and a guard with no store keeps the same in-process behaviour.

No comments yet. Be the first.

Join the conversation

Sign in to leave a comment. It appears after moderation.