Governor for Claude Code

Keep Claude Code concise, clean, and under control.

Compact professional output, context hygiene, tool-output filtering, and usage
telemetry for Claude Code Max users.

Governor is the serious alternative to style-only token savers. It keeps the
agent concise, shrinks recurring memory files, blocks noisy logs from flooding
context, and adds planning guardrails for broad tasks.

The installed Claude Code command namespace is still /governor:*.

Quick Start

bash install.sh --force

Restart Claude Code, then run:

/governor:status
/governor:audit
/governor:compress CLAUDE.md

Governor auto-starts in compact professional mode when the plugin is loaded.
Use /governor:off to disable response compression and /governor:on to
re-enable it.

Why It Exists

Heavy Claude Code users do not only burn quota on long answers. The bigger
session killers are often:

• bloated always-loaded context such as CLAUDE.md, notes, and rules
• huge Bash/test/build output copied into conversation context
• vague prompts that trigger broad scans and repeated failed attempts
• scope drift during long coding tasks
• compactions caused by preventable context growth

Governor attacks those system problems while keeping the interaction
professional and readable.

Early Results

These are directional pilot results, not universal claims.

Same machine, fresh Claude CLI Sonnet sessions, same multi-turn task, same
starting repo snapshot. This pilot measured an implementation contract, a real
implementation turn, a later conflicting stakeholder request, and a final drift
check.

What this means:

• Governor reduced output tokens and total cost in this pilot.
• Governor preserved the original implementation contract and rejected later
  scope drift.
• This was not a speed win; Governor took one extra turn.
• This is early evidence, not a broad claim across all Claude Code tasks.

Notes:

• n=1 pilot run
• Claude CLI Sonnet
• Multi-turn static dashboard task
• Browser-level smoke testing and larger multi-task comparisons are still in
  progress

Governor should not be judged by token savings alone. Throwing context away is
easy. The harder problem is reducing avoidable quota burn while preserving
correctness, intent, and useful model behavior over longer sessions.

Micro Benchmarks

Small local smoke benchmarks. Useful for understanding where savings come from,
but not substitutes for real task runs.

Output Tokens

Three technical explanation prompts, Sonnet, no tools.

Memory Compression

One project-notes.md sample from the Caveman compression fixtures.

Tool Output Filtering

Synthetic noisy pytest -vv output with preserved failure lines.

Interpretation: Caveman is excellent at pure style compression. Governor aims
for broader quota control: compact output, recurring-context compression,
noisy-tool filtering, telemetry, and retry reduction.

Features

• Always-on compact mode: SessionStart and UserPromptSubmit hooks keep
  responses concise in every Claude Code chat.
• Professional memory compression: /governor:compress CLAUDE.md rewrites
  verbose memory files into dense prose.
• Protected-span safety: code blocks, inline code, paths, URLs, commands,
  env vars, versions, headings, tables, and warnings are preserved.
• Quality guard: low-savings compression is rejected and the backup is
  restored instead of pretending success.
• Tool-output filtering: noisy Bash/test/build output is summarized while
  preserving failure signals.
• Telemetry ledger: /governor:status reports blocked tokens, failures,
  compactions, and statusline snapshots when available.
• Prompt guidance: vague broad prompts get soft, non-blocking suggestions.
• Plan and drift guard: explicit contracts for broad builds, then scope
  checks with /governor:guard.
• Portable rule snippets: compact-mode rules for Codex, Gemini, Cursor,
  Windsurf, and Cline.

Commands

Install

Local Development

claude --plugin-dir .

One-Line Local Install

bash install.sh --force

Install From This Repository

gh repo clone 0xhimanshu/governor
cd governor
bash install.sh --force

Install Rule Files For Other Agents

bash install.sh --project /path/to/project --agents all

Supported rule snippets:

Other agents get compact professional behavior only. Claude Code is the V1
target for hooks, telemetry, statusline, and Bash output filtering.

How Compression Works

/governor:compress is automatic from the user's point of view:

1. Create a timestamped backup.
2. Mark protected spans.
3. Rewrite the file with dense professional prose.
4. Strip markers.
5. Validate protected content.
6. Attempt protected-span recovery if needed.
7. Reject low-savings output and restore the backup if the quality guard fails.
8. Report exact before/after token estimates and backup location.

Compression levels:

Set GOVERNOR_ALLOW_LOW_SAVINGS=1 only if you intentionally want to keep a
low-savings compression result.

Telemetry

Governor stores a local JSONL ledger under:

~/.claude/plugins/governor/

It tracks:

• tool-output tokens blocked
• full-output overrides
• prompt-risk suggestions
• Bash failures
• compactions
• statusline snapshots
• memory compression savings

Prompt caching can reduce usage/cost but does not necessarily reduce context
window occupancy. Governor reports those separately when Claude Code exposes
the data.

Benchmarking

Use benchmarks/ for measured comparisons.

Recommended conditions:

• control: no token/style plugin
• caveman: Caveman enabled as normal
• governor-hooks: Governor hooks enabled, memory unchanged
• governor-compressed: Governor after /governor:compress CLAUDE.md
• governor-strict: optional strict-mode run for broad tasks

Fill benchmarks/run-sheet.csv, then run:

python3 scripts/compare_benchmarks.py benchmarks/run-sheet.csv

Primary metrics: five-hour usage delta, peak context %, assistant output
tokens, tool-output tokens blocked, failed tool calls, compactions, wall time,
and task success.

Design Principles

• Helpful by default, strict only when invoked.
• Professional dense prose, never novelty dialect.
• Measure exact savings where possible.
• Treat 1M context as a ceiling, not a target.
• Keep broad planning and drift checks opt-in.
• Restore backups instead of accepting unsafe or low-value compression.

Gotchas

• If hooks do not fire, /governor:status will show little or no telemetry.
• Existing custom statuslines are not overwritten by the installer.
• Compression sends file content through the active Claude Code/model workflow.
  Do not compress secrets or sensitive private files.
• Use /governor:full before a diagnostic command when you need unfiltered logs.
• For installed-but-inactive behavior, launch Claude Code with
  GOVERNOR_DEFAULT_MODE=off.

Contributing

Contributions are welcome when they make Governor more useful, safer, or easier
to trust. Please read CONTRIBUTING.md before opening a pull
request, especially for compression, hook, telemetry, or benchmark changes.

License

MIT. See LICENSE.