Skip to content

usage-governor

Always-on Claude Max usage governor. Council-approved design (2026-07-08, second sitting — report: llm-council/reports/2026-07-08_135825_usage-crisis-claude-max-5-hour-usage.md).

Prevents 5h-limit blowouts by measuring weighted token burn from transcript JSONL and enforcing tier policy via Claude Code hooks.

Components

Piece Path Role
Scanner UsageGovernor.exe scan Every 5 min (Scheduled Task UsageGovernorScan): incremental byte-offset scan of ~/.claude/projects/**/*.jsonl, fixed-5h-window weighted burn (events sorted chronologically across files), atomic state.json
Advisory hook UsageGovernor.exe hook-prompt UserPromptSubmit: one byte-stable directive line per tier
Hard gate UsageGovernor.exe hook-pretool PreToolUse on Agent\|Workflow: denies expensive spawns in YELLOW, all spawns in RED/BLACKOUT — catches autonomous loops that never fire UserPromptSubmit

C# solution: UsageGovernor.sln (Core lib + Cli exe + xunit tests, net10.0). Build/publish/install on any PC with install.ps1 (publishes self-contained exe, registers the task, merges hooks into ~/.claude/settings.json). Superseded PowerShell originals live under archive/ per archive-not-delete policy. Gates run 2026-07-08: 74/74 unit tests, 93.9% line coverage on Core, Stryker mutation 68.4% (ratchet ticket open), secret-grep clean, council code review (Codex chair) — all findings implemented.

State dir: ~/.claude/usage-governor/ — state.json, config.json, cursors.json, burn-history.jsonl, override.json.

Multi-provider limits

Codex provider tracking uses native Codex session telemetry. UsageGovernor.exe scan reads up to the 3 newest non-empty *.jsonl files under %USERPROFILE%\.codex\sessions (or UG_CODEX_SESSIONS_DIR in the CLI) and uses the latest line with payload.rate_limits, e.g.:

{"timestamp":"2026-07-08T18:00:00Z","type":"event_msg","payload":{"type":"token_count","info":{},"rate_limits":{"primary":{"used_percent":1.0,"window_minutes":300,"resets_at":"2026-07-08T23:00:00Z"},"secondary":{"used_percent":16.0,"window_minutes":10080,"resets_at":"2026-07-15T18:00:00Z"},"plan_type":"pro"}}}

Codex provider tier is the worst of primary/secondary: YELLOW >=60%, RED >=80%, BLACKOUT >=92%. Missing or >6h-old telemetry is UNKNOWN and never blocks.

Gemini provider tracking uses an invocation ledger because agy has no local usage telemetry. UsageGovernor.exe log-offload gemini appends ~/.claude/usage-governor/gemini-ledger.jsonl and reports the 5h count against geminiBudget5h (default 200 — Google AI Ultra 5x $99.99/mo since 2026-09-24, a quarter of the old x20 default of 800; was 40 on Google AI Pro). The weighted agy pool defaults were quartered the same day (Gemini 750k/5h, 15M/week; GPT-OSS 75k/5h, 750k/week). NOTE: LoadOrCreate never rewrites an existing config.json — on already-installed boxes bump budgets by hand. The 2026-09-24 x5 downgrade was hand-synced on all four PCs (greatroom, gaming, streaming, bedroom; backups config.json.bak-flt253): geminiBudget5h, grokBudget5h, grokPoolTokens (greatroom only), and agy.geminiBudget5hWeighted / geminiBudgetWeeklyWeighted / gptOssBudget5hWeighted / gptOssBudgetWeeklyWeighted. GPT-OSS runs through agy, so it draws on the Google AI subscription. Use agy-wrap.ps1 instead of calling agy.exe directly so every offload is logged before forwarding all args to %LOCALAPPDATA%\agy\bin\agy.exe with stdin closed.

Grok (Grok Build CLI; SuperGrok Heavy from 2026-07-09, downgraded 2026-09-24) is a third offload lane and a first-class agent spawner: headless single turns and Grok fans out its own native subagents (--agents, --best-of-n) entirely off the Claude budget. Grok usage is metered by the grokPoolTokens spend ledger — the only input to the Grok tier. The default is still null (tier reads UNKNOWN): FLT-260 added the metered paths below, but llm-council and fleet-dispatch still call bare grok -p, and a capacity over a ledger that misses whole callers would read GREEN on incomplete evidence. Once every caller books, set 2.5M tokens / 24h — a quarter of the old 10M figure for the 2026-09-24 x5 downgrade (Andrew's call; xAI publishes no tier ratio and meters a weekly compute pool shown as % used — calibrate against /usage in Grok Build).

The ledger is fed from the producer, never estimated: Grok Build's --output-format json result document carries usage.total_tokens, and two paths book it:

  • council-seat run --seat Gronktayvius runs grok with --output-format json, validates the unwrapped review text, keeps the raw document as seat-gronktayvius.raw.out, and books the spend. Output without a usage receipt FAILS the seat (fails closed); a ledger write failure only warns, since the raw receipt can be booked later with grok-spend.
  • ~/source/repos/usage-governor/publish/UsageGovernor.exe grok-exec [--source S] [--timeout-sec N] -- <grok args> is the metered replacement for a bare grok -p / grok --prompt-file: it forces json output, prints only the response text, then books the spend. Exit 3 = the response printed but its spend could not be booked (reason on stderr). grok-spend --output-file F books a json result a caller captured itself; both dedupe on the producer's requestId.

A bare grok -p books nothing — route offloads through grok-exec (the hook's routing text names the exact command). grokBudget5h (default 200) is display-only and gates nothing. Codex tiers come from the CLI's own primary/secondary % telemetry, so the ChatGPT Pro 20x -> 5x downgrade (published limits exactly 1:4) needs no budget change.

state.json includes provider tiers:

"providers": {
  "codex": { "tier": "GREEN", "primaryPct": 1.0, "secondaryPct": 16.0, "stale": false },
  "gemini": { "tier": "GREEN", "count5h": 3, "budget": 200 }
}

Offload rule: codex RED+ routes bulk offloads to Gemini via agy-wrap or Grok (grok-exec); gemini RED routes to Codex or Grok; both RED routes to Grok, batch-tolerant work to the local-model tier (gaming/streaming PC councils — see docs/local-offload-routing.md), and queues whatever remains until a window resets.

Weighting

weighted = modelWeight × (input×1 + cacheWrite×1.25 + cacheRead×0.1 + output×5) modelWeight: opus/fable/mythos = 5, sonnet = 1, haiku = 0.25 (sonnet-input-equivalent units).

Tiers

Tier Trigger Enforcement
GREEN below all thresholds standard escalation ladder
YELLOW actual ≥45% or projected ≥60% or >4 sessions active in 15 min delegation Haiku-first (haiku/sonnet/cavecrew only), workflows blocked, bulk → Codex/Gemini/Grok, loops detached
RED actual ≥70% or projected ≥85% no new Claude subagents/workflows; Codex/Gemini/Grok implement, batch work → local models; Claude routes/decides
BLACKOUT actual ≥85% orchestration + critical decisions only

Budget calibration (downward-only ratchet)

Seed budget 1.0B weighted/5h (provisional). On every observed limit hit run:

.\publish\UsageGovernor.exe scan --record-limit-hit

Budget ratchets to 80% of the window burn at the hit; never calibrates up.

Escape hatch

Write ~/.claude/usage-governor/override.json: {"tier":"GREEN","expires":"2026-07-08T20:00:00","reason":"prod incident"} Logged intent, auto-expires.