Skip to content

Usage Governor (C#) — Plain English

This is a rewrite of the original PowerShell "usage governor" scripts as a proper C# program. It does the exact same job, just built to be more testable and maintainable.

What problem does this solve?

Claude Max has a rolling 5-hour usage window. If you burn through it too fast — especially by spawning lots of expensive subagents — you can hit the limit and get locked out mid-task. The usage governor watches your usage in the background and, as you get closer to the limit, starts nudging (and eventually blocking) expensive behavior so you naturally slow down before you hit a wall instead of hitting it by surprise.

How it watches usage

Every 5 minutes, a small program reads through the transcript files Claude Code already writes to disk (~/.claude/projects/**/*.jsonl) and adds up how much "cost" you've burned in the current 5-hour window. Not all tokens cost the same — a cheap model like Haiku barely moves the needle, while a big model like Opus counts for a lot more. It only reads the new lines each time (like a bookmark), so it stays fast even as transcripts grow.

The four traffic-light tiers

  • GREEN — you're fine, work normally.
  • YELLOW — you're using a lot. New subagents should be cheap ones (Haiku/Sonnet, or the special lightweight "cavecrew" helpers) — no more expensive models spun up as subagents.
  • RED — you're very close to the limit. No new Claude subagents at all; hand implementation work off to other tools (Codex/Gemini/Grok) and use Claude just for decisions and review.
  • BLACKOUT — you're basically at the limit. Claude should only make critical decisions and wrap things up, nothing else.

There's also a "projected" percentage — a short-term trend line — so it can warn you before you actually cross a line, not just after.

How it actually stops things

Two hook points into Claude Code:

  1. Every time you send a message (UserPromptSubmit), if the tier is YELLOW or worse, Claude sees a short reminder message telling it how to behave.
  2. Every time Claude tries to spawn a subagent or workflow (PreToolUse), the governor can flat-out block it if the tier and the request don't match up — this matters because a fully autonomous loop might never send a new "message" the first hook could catch, but it will still try to spawn subagents, so this second check is the real safety net.

What if the estimate is wrong?

If you ever actually hit Claude's real usage limit, you can tell the governor "that just happened" and it will recalibrate its internal budget downward to match reality — it never guesses the budget is bigger than what you've already proven it to be.

There's also a manual override file you can drop in if you need to force a tier for a while (e.g. "treat this as GREEN for the next 2 hours, I know what I'm doing") — it's logged and expires on its own so it can't be silently left on by accident.

Why rewrite it in C#?

The original was a couple of PowerShell scripts. That's fine for something small, but it's hard to unit test, hard to keep behaviorally consistent as it grows, and every change to the reason-text strings has to be manually kept in sync with anything reading them. The C# version is the same behavior, just structured into small, independently testable pieces (weighting, windowing, tiering, scanning, hooks) with a real test suite instead of "run it and eyeball the output."