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 800 — Google AI Ultra x20 $200/mo plan since 2026-07-09; was 40 on Google AI Pro). NOTE: LoadOrCreate never rewrites an existing config.json — on already-installed boxes bump geminiBudget5h by hand (done fleet-wide 2026-07-09 except the great-room PC). 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 x20 $300/mo plan since 2026-07-09) is a third offload lane and a first-class agent spawner: grok -p runs headless single turns and Grok fans out its own native subagents (--agents, --best-of-n) entirely off the Claude budget. Grok usage is not yet metered by the governor — the Heavy x20 plan's headroom is treated as effectively unconstrained for routing purposes; add a ledger like Gemini's if that changes.

state.json includes provider tiers:

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

Offload rule: codex RED+ routes bulk offloads to Gemini via agy-wrap or Grok (grok -p); gemini RED routes to Codex or Grok; both RED routes to Grok (untracked), 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.