governer
Your agent spent $37,901 while you slept. The budget alert told you afterwards.
governer prices every request the way the provider actually bills it — cache
reads and writes included — then refuses the request that would cross your
line. Not a warning. Not a dashboard. A kill switch.
$ governer box
wallet $10.00 · gpt-6-astra · 200,000 tok/turn · CACHE MISSING
turn 1 $ 2.02 / $10.00
turn 2 $ 4.05 / $10.00
turn 3 $ 6.07 / $10.00
turn 4 $ 8.10 / $10.00
turn 5 BLOCKED (would have cost $2.0250)
🛑 BREAKER TRIPPED at $8.10 of $10.00 — agent stopped
paid $ 8.10 (5 turns)
same run, cached $ 0.90
you paid 9x the cached price — this is the $38k bug
No API key, no network, ninety seconds.
Install
pipx install governer # or: pip install governer
governer box
No dependencies either way. Prefer a file? Two curls and you're done:
curl -O https://raw.githubusercontent.com/Kaiser0733/governer/main/governer.py
curl -O https://raw.githubusercontent.com/Kaiser0733/governer/main/prices.json
python3 governer.py box
Python 3.9+.
Commands
| command | what it does |
|---|---|
governer proxy --limit 5 |
OpenAI-compatible shim: point your agent at it, it refuses anything past $5 |
governer box |
simulated agent in a virtual wallet — watch the breaker trip, no key needed |
governer check usage.json --limit 20 |
true cost of a real log, plus where a $20 cap would have stopped it |
governer prices |
what every model costs right now, with its verified date |
governer prices --refresh |
pull live prices from the gateway — 459 models, cache pricing included |
governer prices --live |
every known model, cheapest first |
governer prices --upcoming |
announced price changes — Gemini 3.8 Flash doubles 2027-01-01 |
governer free |
which models are free right now, fetched live |
governer status spend.jsonl --limit 20 |
the meter: spent, burn rate, projection, per-agent split |
governer verify ledger.jsonl |
checks a spend ledger for tampering |
Put it in front of your agent
$ governer proxy --limit 5 --ledger spend.jsonl
governer http://127.0.0.1:8787 → https://openrouter.ai/api/v1
wallet $5.00 · unknown models billed $0.0/$0.0 per M
export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
export OPENAI_API_KEY=<your key> # governer never stores it
Your agent keeps working unchanged. Every request is priced at its worst case
before it leaves the machine, forwarded with your own key, then billed at its
real usage. Cross the limit and the request comes back 402 with
type: governer_breaker_tripped — and your provider never sees it.
Streaming passes straight through — governer adds stream_options.include_usage
so the final usage block still arrives and the stream can be billed. Unpriced models
fall back to --default-in/--default-out, which is also how you shadow-price a
free model to see what it would have cost:
✓ 200 nvidia/nemotron-3.5-lightning:free $0.001230 $0.0012/$5.00
When the provider reports its own cost field, governer compares it against
its own number and warns when prices.json has gone stale.
Budgets per agent, per day
One proxy, several caps. Copy governer.example.json and pass it:
{
"limit": 20.0,
"ledger": "spend.jsonl",
"notify": "https://ntfy.sh/your-topic",
"agents": {
"claude-code": { "limit": 5.0, "per": "day" },
"ci": { "limit": 2.0, "per": "run" }
}
}
governer proxy --config governer.example.json
The agent names itself with a header — X-Governer-Agent: claude-code — and the
cap applies to it alone. day resets at UTC midnight, run lasts the process.
Both are rebuilt from the ledger on restart, so bouncing the proxy cannot reset a
budget. notify receives a POST when the breaker trips.
Watch for a week before you enforce
governer proxy --limit 20 --dry-run --ledger spend.jsonl
Dry run books the true spend and refuses nothing, so you learn what a normal week
costs before a cap starts costing you work. Anything it would have refused is
marked ◌ in the console.
Audit a log you already have
$ governer check usage.json --limit 20
requests 100
true cost $52.00
cache miss 100 request(s) billed uncached while sending ≥10k tokens
$43.20 of that was avoidable — ~83% of the bill
at $20.00 cap: stopped at request 39, $32.24 never spent (62% saved)
Reads Anthropic (input_tokens), OpenAI (prompt_tokens) and OpenRouter
(cached_tokens) field names, as a JSON array or JSONL.
It prices models nobody told it about
$ governer prices --refresh
459 models refreshed from https://openrouter.ai/api/v1
free right now: 20
vendor-confirmed cache pricing: 313
Curated entries are hand-verified, each with a date and a source. Everything else is pulled live, so an agent that switches to a model released last week still gets priced — instead of silently costing nothing in your ledger because nobody typed it into a table.
Gate a pull request on cost
- uses: Kaiser0733/governer@main
with:
usage-file: ci/agent-usage.json
budget: "2.50"
governer check --fail-over 2.50 exits 1 when the run costs more. Tests
should not be the only thing a PR can fail.
The meter, not just the wall
A hard cap alone does not fix behaviour — it just moves the spending to the last week of the month. The number has to be in front of you while you decide whether to kick off another run.
$ governer status spend.jsonl --limit 20
spent $2.40 of $20.00 (12% used)
burn rate $0.40/h over 6.0h
projected $9.60/day at this rate
runs out in 44.0h at this rate
agent claude-code $2.10
agent ci $0.30
chain OK — 3 records · $2.4000 · chain intact
It refuses to project from a window shorter than 30 minutes, because extrapolating three records in the same minute produces confident nonsense.
Why this instead of the other options
| option | what it covers | what it misses |
|---|---|---|
| provider credit / key limits | a hard stop per account | not per agent, not cross-vendor, and it is exactly the layer that failed the $38k case |
an in-process library (budget-guard, npm) |
a cap inside one Node app | one language, needs a code change, no help for a CLI agent you did not write |
an agent runtime with budgets (cx, Claude Extender) |
caps for agents inside that runtime | requires adopting the whole runtime |
| gateway budgets (litellm, OmniRoute) | budget fields in the gateway | enforcement is soft, and litellm's was silently bypassed (#26672) |
| governer | any client in any language, no code change, cross-vendor, cache-aware pricing, tamper-evident ledger, CI gate, audit of logs you already have | one process per ledger — do not point two proxies at the same file |
Why the bill explodes at night
- 1M-token contexts are table stakes, so the cached prefix is replayed on every call. Cache reads dominate agent bills — and they are billed even when that content is truncated before the model attends to it.
- "Prompt caching is supported" is not "your stack is caching." The expensive failure is silent: status 200, normal-looking output, invoice 100×.
- Alerts are not limits. Email after the money is gone is not a safety mechanism, and neither are credits or a dashboard you check on Mondays.
Receipts
The spend ledger is append-only and hash-chained: every record carries the hash
of the one before it, so editing a number breaks the chain and verify says so.
Tamper-evident bookkeeping, because a budget you can quietly rewrite is not a
budget.
Prices are data, not truth
Every model in prices.json carries a verified date and a source. Cache
prices marked ~ are derived from the vendor convention (0.1× read, 1.25×
write) rather than confirmed. Re-verify before betting a number that matters,
and open a PR when a vendor moves.
Roadmap
v0.2proxy, livefreecheck, CI gate — shippedv0.5price table refreshed from the gateway instead of hand-maintained — shipped- v0.3 per-agent and per-workflow budgets on one proxy
- v0.4 phone push the second a breaker trips
License
Docs and demo: https://kaiser0733.github.io/governer/
MIT. Built by Kaiser0733 at Vastraa Labs.
Metadata
Release files for governer 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| governer-1.0.2.tar.gz | 19.2 kB | With provenance | Details for governer-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| governer-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for governer-1.0.2-py3-none-any.whl |
Total release size: 38.7 kB
Release files / governer-1.0.2.tar.gz
| Download URL | governer-1.0.2.tar.gz |
|---|---|
| Size | 19.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
76d835f8f62bb2090e68bf1bec308f183f1c73a08772b85c95530f71c7f71241
|
|
BLAKE2b-256 checksum How to use checksums |
12360f701c719bba968f0bdc7ec94ff1453cdde9d2850b7507734901b0dea355
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logRelease files / governer-1.0.2-py3-none-any.whl
| Download URL | governer-1.0.2-py3-none-any.whl |
|---|---|
| Size | 19.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55b4e0066c1c8798be55b100576dd64cbd28fd9577f5e330520a0724c6dd668f
|
|
BLAKE2b-256 checksum How to use checksums |
707cf98040c2ff207799439d62e7a1d46f5af240563dd80992fb80d11f1df365
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logSecurity for governer 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for governer-1.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.