governor 0.5.0

A PreToolUse hook that watches what a Claude Code session is spending and stops it running away. Zero always-on cost for the gate itself — hooks run outside the model's context.

Gates

gate	default	effect
burn rate	25k output tokens in 5 min	warn
soft	60% of budget	warn
hard	100% of budget (200k)	deny every tool call

The model keeps its voice when denied, so it reports what is done and what is left rather than going silent.

The budget, and the ceiling

A denied session may still edit the project config — otherwise the gate strands it with no way to ask for more. That doubles as the self-extension: it can raise budget up to ceiling. Past the ceiling nothing it can reach moves the line; enabled, ceiling and both ratios live in ~/.claude/governor.json.

New in 0.5.0 — weighted

Off by default. The gate counted output tokens because they drive cost — true for a session that writes, false for one that reads. Measured on a real agent turn: 168 output tokens against 322,512 cache reads, costing $0.3562, of which output was $0.0042 — 1.2%. Across four tool-heavy runs, output was 5% of the bill.

"weighted": true counts each class at its price relative to output (input ×0.2, cache write ×0.25, cache read ×0.02), so the budget tracks dollars while keeping its unit. Weighted totals run far higher on the same work — raise budget in the same edit.

0.4.0 — security

Three ways out of the gate, closed. The escape hatch let a denied session write the project config, and the project config could set any field — so {"enabled": false} or {"hardRatio": 100} turned the gate off from inside and the ceiling was decoration. The project file may now set budget, burnTokens, burnMinutes and rewarnMinutes only.

Also: the state file was trusted on the way in and a non-array window threw on every tool call for the rest of the session; state moved out of world-writable /tmp to ~/.claude/governor-state; and find-plugin now allowlists repo slugs before printing them inside a paste-able command and strips control characters that \s did not cover.

Measured

See BENCHMARK.md — the gate replayed over 395 real session transcripts: 6.1% would have been hard-stopped, $40.34 of spend sat past the line, and the published median/p90/p99 reproduce from raw data.

Install

claude plugin marketplace add tanvoid0/claude-code-plugins
claude plugin install governor@tanvoid0