Governor for Claude Code

Keep long Claude Code sessions sharp under quota pressure.

Reduce noisy tool output, recurring context bloat, and drift without throwing away the clue.

Quick Start · Why Governor · Benchmarks · Commands · Install

Governor is a Claude Code plugin for context hygiene, tool-output filtering, memory compression, telemetry, and drift guardrails.

It is built for the harder problem than "make the model talk less":

keep long Claude Code sessions efficient without making the model dumber.

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 Governor

Long Claude Code sessions usually do not fail because Claude writes one extra paragraph.

They fail because context gets polluted:

• verbose test, build, and MCP output floods the transcript
• bloated recurring files like CLAUDE.md, notes, and rules tax every session
• broad prompts trigger repo-wide scans and retries
• scope drift compounds over time

Governor is designed for that failure mode.

What It Does

Why It Feels Different

Most token-saving tools optimize one layer:

• shorter replies
• shorter command output

Governor is built for the broader session problem:

• tool spam
• recurring context tax
• MCP-heavy workflows
• long-task drift
• wasted retries

That is why Governor's benchmark story starts with valid-context loss and decision preservation, not only token counts.

Benchmarks

V2 Sonnet Fixture Run

Recent measured Sonnet run with Claude decision grading:

What this means:

• Caveman still wins on raw compression.
• Governor preserved more valid context in this run.
• Governor won on decision quality in the latest Sonnet pass.

Artifacts:

• benchmarks/v2-fixture-results.md
• benchmarks/v2-fixture-results.json
• benchmarks/sonnet-v2-report.md

Early Multi-Turn Pilot

Same machine, fresh Claude CLI Sonnet sessions, same multi-turn task, same starting repo snapshot.

This was a narrow pilot, not a universal claim. It matters because Governor kept the implementation contract intact while shaving cost on a real multi-turn coding task.

Tool Filter Signal Checks

Structured/local cases focused on the criticism that compaction can miss the real clue.

Compared To

RTK

RTK is excellent at shrinking shell output.

Governor is aimed at the wider Claude Code session:

• tool-output filtering
• recurring prompt-file hygiene
• MCP and structured payload handling
• drift-sensitive long sessions
• measured savings and waste heat inside Claude Code

Caveman

Caveman is excellent when the main goal is making Claude talk in fewer tokens.

Governor is built for the broader session problem:

• less tool spam
• less recurring context tax
• less drift
• more decision preservation under pressure

Short version:

RTK compresses commands. Caveman compresses style. Governor protects the session.

Best Fit

Governor is best for:

• Claude Code Max users who hit long-session limits
• MCP-heavy workflows
• Burp / Playwright / structured tool output
• prompt-heavy repos with large rules or command docs
• teams who care about drift, reproducibility, and auditability

Governor is less useful for:

• tiny chats
• already-clean prompt files
• users who only want meme-simple answer shortening

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.
• Content-aware tool filtering: large outputs are only compacted when content is repetitive noise (>40% duplicate lines). Unique data — API responses, Burp proxy history, curl output, structured JSON — passes through unfiltered. Noisy test failures, repetitive logs, and build spam still get compacted.
• Inline full-output bypass: set GOVERNOR_FULL=1 as an env var in the same Bash call to skip compaction without a separate command. Immune to parallel-call cancellation.
• 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. The status command automatically discovers and merges ledger files from all known locations, including the plugin data directory set by Claude Code (CLAUDE_PLUGIN_DATA) and the manual fallback path. Deduplication uses resolved paths so symlinks and non-canonical paths do not cause double-counting.

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 and 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

Primary metrics:

• valid-context loss rate
• decision preservation
• wrong-decision rate
• five-hour usage delta
• assistant output tokens
• tool-output tokens blocked
• wall time
• task success

Run:

python3 scripts/run_benchmark.py \
  --write-json benchmarks/v2-fixture-results.json \
  --write-md benchmarks/v2-fixture-results.md

Refresh Caveman captures first when Claude CLI auth is available:

python3 scripts/capture_fixture_conditions.py \
  --condition caveman \
  --model sonnet \
  --write-summary benchmarks/captured/caveman/latest-summary.json

Refresh reference-style Governor captures too:

python3 scripts/capture_fixture_conditions.py \
  --condition governor \
  --model sonnet \
  --write-summary benchmarks/captured/governor/latest-summary.json

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, or prefix with GOVERNOR_FULL=1 to bypass inline.
• 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.