README.md

September 6, 2026 · View on GitHub

Governor for Claude Code

Keep long AI coding sessions sharp under quota pressure.

Now also works with Cursor · Windsurf · Cline · Codex CLI · Gemini CLI · Hermes · DeepSeek

Quick Start · Multi-Agent · Why Governor · Benchmarks · Commands · Install

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

As of v0.2.4, Governor's core behavior — content-aware tool-output filtering and context hygiene — works with any AI coding agent via prompt-based skills. No hooks or MCP required.

Keep long coding sessions efficient without making the model dumber.

The Claude Code command namespace is /governor:*.

Quick Start

Claude Code (full plugin)

bash install.sh --force

Restart Claude Code. Filtering, compact mode, and telemetry are already running — there is nothing to turn on. When you want to look under the hood:

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

Other Agents (prompt-based skill)

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

This copies a Governor rules file into your project for each agent. The rules teach the agent to self-filter noisy tool output, preserve unique data, and maintain context hygiene — automatically, every session.

Multi-Agent Support

Governor works at two levels:

Agent	Integration	What You Get
Claude Code	Plugin with hooks	Full: auto-filtering, telemetry, compression, drift guard, `/governor:*` commands
Cursor	`.cursor/rules/governor.mdc`	Self-filtering, compact mode, context hygiene
Windsurf	`.windsurf/rules/governor.md`	Self-filtering, compact mode, context hygiene
Cline	`.clinerules/governor.md`	Self-filtering, compact mode, context hygiene
Codex CLI	`AGENTS.md`	Self-filtering, compact mode, context hygiene
Gemini CLI	`GEMINI.md`	Self-filtering, compact mode, context hygiene
Hermes 🆕	`.hermes.md`	Self-filtering, compact mode, context hygiene
DeepSeek 🆕	`.dsh/rules/governor.md`	Self-filtering, compact mode, context hygiene

How it works for non-Claude agents: Governor's rules file teaches the agent to apply content-aware filtering itself. When tool output has >40% duplicate lines (test failures, log spam, build warnings), the agent compresses it — keeping the first error, file:line, and exit code. When output is unique (API responses, JSON, code), it passes through intact. No external dependencies.

Claude Code gets the deepest integration because it supports plugin hooks. Other agents get the core behavior via prompt engineering.

Why Governor

Long coding sessions usually do not fail because the AI 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 — in Claude Code and beyond.

What It Does

Capability	What it does	Where it works
Tool-output filtering	Compacts noisy output when content is repetitive; preserves unique data	All 8 agents
Compact mode	Keeps responses concise and professional	All 8 agents
Context hygiene	Avoids re-reads, broad scans, and context waste	All 8 agents
Memory compression	Rewrites bloated prompt files into denser, safer forms	Claude Code
Telemetry	Reports measured savings, failures, compactions, and waste heat	Claude Code
Drift guardrails	Adds planning and scope checks for broad tasks	Claude Code

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:

Condition	Avg token savings	Avg VCLR	Decision preserved	Wrong decision
Caveman	69.1%	0.14	87.5%	12.5%
Governor	45.5%	0.00	100.0%	0.0%

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.

Condition	Output Tokens	Cost	Turns	Intent Preserved	Obvious Regression Found
Control	10,997	$0.5169	21	Yes	No
Governor	10,113	$0.4933	22	Yes	No
Delta	-8.0%	-4.6%	+4.8%	Tie	Tie

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.

Case	Filtered?	Blocked	Signal Preserved
Noisy pytest failure buried in long log	Yes	64.0%	Yes
Burp-style MCP payload with large history + one critical finding	Yes	90.9%	Yes
Large `Read` output containing source code	No	0.0%	Yes

Compared To

Governor sits in a different layer from the other token-savers, so it stacks with them rather than replacing them.

Tool	Shrinks	Overlap with Governor
Ponytail	The code the agent writes	None
Caveman	The prose the agent speaks	None
RTK	The shell output you pipe through it	Partial
Governor	The context the session consumes	—

Ponytail

Ponytail is a YAGNI enforcer: before writing code it walks a ladder — does this need to exist, is it already in the codebase, does the stdlib or platform do it — and stops at the first rung that holds. Their published benchmark reports ~54% less code written against a no-skill baseline. Those are their numbers on their fixtures, not something Governor has independently reproduced.

Ponytail does not read tool output. Governor does not touch code generation. Run both: Ponytail keeps the agent from over-building, Governor keeps the test logs and MCP payloads from that build out of your context window.

RTK

RTK is excellent at shrinking shell output.

Governor is aimed at the wider coding session:

tool-output filtering across all agents
recurring prompt-file hygiene
MCP and structured payload handling
drift-sensitive long sessions
measured savings and waste heat

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:

Ponytail shrinks what gets built. Caveman shrinks what gets said. RTK shrinks what a command prints. Governor protects the session that holds all three.

Best Fit

Governor is best for:

Claude Code Max users who hit long-session limits
Cursor / Windsurf / Cline / Hermes / DeepSeek users who want context hygiene without switching tools
MCP-heavy workflows (Burp, Playwright, structured tool output)
prompt-heavy repos with large rules or command docs
teams using multiple AI agents on the same codebase

Governor is less useful for:

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

Features

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. Works in all supported agents.
Always-on compact mode: keeps responses concise and professional. In Claude Code via hooks; in other agents via rules files.
Professional memory compression: /governor:compress CLAUDE.md rewrites verbose memory files into dense prose. (Claude Code)
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.
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. (Claude Code)
Prompt guidance: vague broad prompts get soft, non-blocking suggestions.
Plan and drift guard: explicit contracts for broad builds, then scope checks by running /governor:plan again. (Claude Code)

Commands

Governor is designed to work without commands. Everything below is optional.

Automatic — no command needed

Behavior	When it runs
Tool-output filtering	Every tool call, once output is noisy and large
Compact response mode	Every session, from the moment the plugin loads
Telemetry + statusline	Continuously in the background
Prompt-risk suggestions	When a prompt would trigger a broad scan or retry loop
Mode switching by plain language	"turn off governor" / "enable governor"
Full output for one command	Prefix it: `GOVERNOR_FULL=1 pytest -vv`

The five commands

Command	Purpose
`/governor:status`	Usage dashboard, waste heat map, current mode
`/governor:mode [on\|off\|full\|strict]`	Control Governor; no argument reports current mode
`/governor:audit [paths]`	Find bloated memory/rule files and context waste
`/governor:compress [level] [file]`	Compress memory files with protected-span validation
`/governor:plan "task"`	Write an implementation contract; run again later to check drift

/governor:plan picks its phase automatically: no saved contract for this project means it writes one, an existing contract means it reports drift against it. Contracts are scoped to the project that created them.

Two things that used to be slash commands are now plain scripts:

python3 scripts/run_benchmark.py                                    # was /governor:benchmark
python3 scripts/install_rules.py --project . --agents all --force   # was /governor:install-rules

Install

Claude Code (Full Plugin)

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

Other Agents

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

Or install for specific agents:

bash install.sh --project . --agents cursor,windsurf
bash install.sh --project . --agents cline,codex,gemini
bash install.sh --project . --agents hermes,deepseek

Local Development

claude --plugin-dir .

How Compression Works

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

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

Compression levels:

Level	Target
`light`	Remove filler and repetition; preserve most rationale
`medium`	Collapse narrative into decision bullets
`aggressive`	Keep only rules, facts, commands, risks, and decisions

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

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

Run:

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

Refreshing the captured Caveman and Governor comparator replays is documented in benchmarks/README.md.

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.
When you need unfiltered logs, prefix the command with GOVERNOR_FULL=1, or run /governor:mode full before the diagnostic step.
For installed-but-inactive behavior, launch Claude Code with GOVERNOR_DEFAULT_MODE=off.