llm-spendguard

Actively minimize and govern LLM spend before work runs — then prove the result against the provider's bill.

uvx --from llm-spendguard spendguard scan        # 10 seconds. No key, no config, nothing leaves your machine.

That reads the coding-agent transcripts already on your disk and tells you what that work costs at API rates. Nothing is installed into your interpreter and nothing is uploaded — see what leaves your machine.

Then, when you want the guard rails, set up once:

pip install 'llm-spendguard[all]' && spendguard init --all   # ONE command: caps + identity, auto-detect your $0 subscription lanes, and wire the gate, MCP tools, in-chat receipt & slash-commands
spendguard run -- python your_job.py   # gate ONE command: cost estimate before submit + hard caps
spendguard reconcile all               # your ledger vs the provider's actual bill, with the gap NAMED
spendguard submit-jobs jobs.jsonl      # hand it a WHOLE job set + a goal; it plans the cheapest route and runs it

spendguard init is safe to re-run and works fully standalone (no account). init alone writes config and auto-detects your $0 lanes; init --all also wires the gate, MCP tools, receipt, assistant rule and slash-commands (add --quick for zero prompts). It ends on a status card + the one command that proves the path end-to-end.

Six things it does that the observability and gateway tools don't:

1. Estimates a batch before you submit it — not after the tokens are billed.
2. Refuses to price a model it doesn't know, loudly, instead of logging $0. (Elsewhere a $0 price can also silently exempt the call from your budget cap — an unknown model becomes an uncapped model.)
3. Reconciles to the actual invoice and names the residual as ungoverned spend, with a published error rate — see ACCURACY.md.
4. Learns the cheaper config and proves it's safe before adopting it (measure → test for output equivalence → adopt only if quality holds → apply → remember what failed).
5. Plans a whole job set for you — the simplest contract there is: hand it the jobs and a goal (a budget, how urgent), and it picks the cheapest route per call — the Batch API, a subscription lane you already pay for, or the metered API — capability-matched to each call's structured-output needs, runs it, and returns. It estimates the whole set first and refuses before spending a cent over your budget. You never hand-tune which path each call takes; that's spendguard's job. See the whole-job contract.
6. Manages constrained plans actively — sheds eligible work from a capped/overage lane to another ready $0 lane, chooses the cheapest measured-good (model, effort), substitutes an actually served model inside a bounded economic envelope, and delegates self-contained agentic work to codex/gemini/zai/kimi CLIs when the current plan is capped.

Zero required dependencies. Fail-open by design: a cost tool must never be the reason your job doesn't run. Learn more at https://llmspendguard.com · Docs & quickstart →

The global model reference is available without login at llmspendguard.com/catalog. Its row as_of is the authored date the row's price/capability payload last changed; “snapshot ingested” is the server's separate observation time. Local standalone operation remains complete; SaaS sync and dashboards are optional.

📘 New here? Read the Solution Specification — the whole story end to end: why it exists, the value, the journey of a dollar (call → gate → ledger → reconcile → push), the design, and how it's tested, secured, and operated.

What leaves your machine

Three modes. The default is local-only — you have to opt in to each of the other two.

Two things worth stating plainly, because they are the questions a careful reviewer asks first:

• Your API keys never leave the machine and are never sent to our server. Provider billing is read locally with your key; only the resulting numbers are pushed, and only if you connect a team dashboard.
• Coding-agent transcripts can contain secrets (a .env echoed into a session, a pasted credential). That is exactly why LLM attribution is opt-in and de-identified rather than on by default — and why scan, the command we ask you to run first, never sends them anywhere.

spendguard run --show prints the exact bootstrap that will execute in your process. Nothing is downloaded at runtime, ever.

Why llm-spendguard?

Cost overruns don't announce themselves — they slip in silently: a hardcoded price that drifted from the real rate, a forgotten model swap, under-batching that re-bills a shared prompt every request, a job cancelled "to save money" that still bills for completed work, an ungated script in some other venv quietly leaking spend. spendguard stops those before the spend (the gate hard-stops over a cap, prices from a verified table, finds the leaks) and learns what was actually worth it — so "cheaper" never quietly costs you quality.

Born from a real incident: a "cost-conscious" day meant to cost ~$33 actually cost $149.76 — a price constant was hardcoded wrong (GPT-5.5 at the old GPT-5 rate) and jobs ran 1 item/request (the shared prompt re-billed every call). spendguard makes those mistakes impossible to ship silently — and goes further: it reconstructs what you should do cheaper, and won't let "cheaper" cost you quality.

What it does

Enforce → shed → route → delegate → save → prove → learn.

• gate — overlay on the OpenAI/Anthropic SDKs (armed by spendguard run --, by import spendguard, or venv-wide via the opt-in hook): estimates every batch/real-time call — chat, Responses API, Anthropic messages, and embeddings (realtime + batch input bodies) — hard-stops over a cap (per-batch + cross-process daily/monthly) — then asks if interactive.
• reliability (no 429 storms) — one admission chokepoint paces every fan under the vendor's real rpm/tpm (seeded from the catalog's published limits, refined by AIMD from live headers) and diverts an over-deadline burst to the Batch API — so a thousand-wide fan is paced or batched, never stormed. Durable, crash-resumable, exactly-once; the caller is always served with no 429 surfaced. See docs/PLAN_429_storm_to_batch.md.
• pricing — one canonical, verifiable table (layered from LiteLLM + curated + override), cross-checked vs OpenRouter; an audit fails CI if any code hardcodes a disagreeing price.
• reconcile — actual $ from real billed tokens; reconcile-ledger compares the local ledger to provider billing to find leaks (ungoverned spend from a non-gated venv/repo).
• report — daily/weekly/monthly email with spend totals + a leak alert + the advisor's top learnings.
• learning advisor — a per-call cost+quality corpus → confidence-scored, lifecycle-tracked insights; brief pre-fills a plan, optimize recommends the cheapest config that held quality, experiment proves it (cost↓ and same-output), promote runs it and keeps the output. Cost-per-good-result, not per-token.
• model-advisor (over MCP) — which model for this job? answered from your own measured usage: advise ranks the models you've used for a job-type by $/good, recommend picks the top-K on the cost×quality frontier at the precision the job needs (agentic quality-bar), and bakeoff measures untried models on a task sample so they enter the ranking. Exposed as a local MCP server — spendguard mcp (stdio, no SDK dep) — so any MCP client (Claude Code / Desktop, an IDE agent) can call it as tools. See Model-advisor.
• active routing — advisor.shed_lanes plus live cap/overage state moves eligible work to ready $0 lanes; best-value resolves the cheapest measured-good (model, effort); unserved requests get the best catalog-ranked served substitute within anchor rate ×1.25. Shed results distinguish avoided-overage $ from quota-preserved value.
• warm shared MCP + fleet — one long-lived daemon per tool is shared by sessions; spendguard fleet reports the deployed green version and stale consumers instead of leaving long-running processes silently behind.
• cost levers — prompt-caching audit/test, semantic cache + batch dedup, cost-aware cascade routing.
• observability — emits OpenTelemetry GenAI-convention metrics+spans → Langfuse / Helicone / Phoenix / any OTLP backend.

The advisor's own LLM use is itself caged (a separate caps.meta budget, tagged spendguard:*, excluded from the corpus it analyzes) so the governor can't overspend governing.

Cost reporting has three axes and never blends them: Total $X = $A API + $S Subscription (plan) + $R Remote (provider) :: Est sub value $V; guarded savings (measured + counterfactual) is a separate third axis, never added to real dollars or estimated subscription value.

Delegate work to another plan

When the current plan is capped or on paid overage, spendguard delegate can hand a self-contained subtask to a configured $0 or cheaper subscription plan. It is a two-hop flow: a plan-covered classifier decides whether the task is a one-shot, an agentic workspace task, or needs the current Claude context; then the selected provider CLI runs it. The default is a dry-run that returns the classification, route, separate real-$ and est-value estimate, and estimated dollars saved versus measured Claude overage:

spendguard delegate "summarize this design" --files docs/design.md
spendguard delegate "fix and test this module" --provider codex --files src/app.py --yes

MCP clients can use the same engine with spendguard_delegate (execute=false by default). The honest boundary: this offloads a SELF-CONTAINED subtask to another provider's plan; it does NOT reroute the calling agent's own turns. Use it for bounded work you can describe completely; keep live-context conversational work in the current agent. This implements the packaged assistant guidance in §8 of the installed spendguard:rule: batchable comprehension goes through lane routing, while agentic subwork can be handed to another provider CLI when the current plan is capped or on overage.

Docs: Architecture + diagrams · Diagrams · Durable queue + dedup · Plan shedding · Fleet / update propagation · Model-advisor (MCP) · Use with Claude/Cursor · Methodology · Roadmap (teams/orgs/SaaS) · Module map · Contributing · Changelog · Setup

Use with an AI assistant: spendguard install-rule --global writes a rule into CLAUDE.md so every Claude/Cursor conversation routes the LLM code it builds through spendguard — then spendguard install-skills adds the slash-commands: /spend (status), /spendguard-reconcile (trust the number), /spendguard-learn (advisor), /spendguard-prompts (the prompt lab), /spendguard-close (monthly close). See Use with Claude. Teams & orgs: each user keeps their own ledger and local caps; the connected server also serves effective advisory or enforced caps through GET /v1/policy, which the client pulls and enforces (an enforced org cap can only be tightened locally). Opt-in roll-ups carry decisions, shed effectiveness, savings, and fleet/client status to the dashboard. The client is production-ready and fully standalone. The team/org dashboard is live at llmspendguard.com — see ROADMAP.md.

Quickstart

A) Set up with Claude (recommended). Point Claude Code / the desktop app at this repo and say:

Install spendguard from this repo and run the guided setup in SETUP.md.

Or just run spendguard init — it reads the config registry (src/spendguard/config_schema.py — the single source of truth for every setting, its default, valid options, and whether it's secret) and walks you through caps, projects, and providers conversationally, one question at a time, then writes your config. Pointed at this repo, Claude does the same end-to-end: installs the package, runs the interview off that same registry, and wires up the gate. Details: SETUP.md.

B) pip + code.

pip install llm-spendguard
# or, from a clone of this repo:
pip install -e .

import spendguard                    # importing the guard now GATES every OpenAI/Anthropic call in this process
# spendguard.install(cap=75)         # optional — set a per-batch cap (import already installed the gate)

import spendguard auto-installs the gate (idempotent, fail-open), so pip install + import is enough — no more silently-ungated spend. Knobs: SPENDGUARD_NO_AUTOINSTALL=1 opts out; SPENDGUARD_REQUIRE=1 makes the import fail-closed (raises if an SDK is present but the gate can't enforce here — refuse loudly rather than spend ungated). For a hard guarantee in a script, keep spendguard.require() at the top.

To gate one command without touching your interpreter at all — the default, and the shape ddtrace-run and opentelemetry-instrument use:

spendguard run -- python your_job.py
spendguard run --show          # print the exact bootstrap that will execute, before you trust it

Nothing is written into site-packages and nothing persists once the process exits. To arm every process in a venv you own, that's an explicit opt-in: spendguard install-hook --venv .venv (remove with --uninstall). We don't default to writing startup hooks — see Architecture for why. Configure with spendguard init (interactive — or init --quick for non-interactive defaults) / spendguard config (show current); see the configuration reference.

Where to go next

Safety

Fail-open: any estimation or patch error logs a warning and lets the call proceed — the gate never breaks a job by accident. Only the deliberate over-cap stop blocks. Disable instantly with spendguard off (checked per-call, live) — and the kill switch is honored even if the gate itself errors.

Getting help

• Website: https://llmspendguard.com
• Bugs / feature requests: GitHub Issues
• Questions / ideas / show-and-tell: GitHub Discussions
• Contributing: see CONTRIBUTING.md.