Skip to content
Back to search

governor

MarketplaceWorks with Claude CodeGitHub

Governor: always-on compact professional output, usage telemetry, memory compression, and tool-output filtering for Claude Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/0xhimanshu-governor/badge.svg)](/listings/0xhimanshu-governor)

HTML

<a href="/listings/0xhimanshu-governor"><img src="/api/listings/0xhimanshu-governor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "governor",
  4. "description": "Governor: always-on compact professional output, usage telemetry, memory compression, and tool-output filtering for Claude Code.",
  5. "owner": {
  6. "name": "0xhimanshu",
  7. "url": "https://github.com/0xhimanshu"
  8. },
  9. "plugins": [
  10. {
  11. "name": "governor",
  12. "description": "Governor for Claude Code Max: compact output, context slimming, telemetry, noisy-tool filtering, and drift guardrails.",
  13. "source": "./",
  14. "category": "productivity"
  15. }
  16. ]
  17. }
README.md · README · 453 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/governor-icon.png" width="128" alt="Governor icon" />
  3. </p>
  4. <h1 align="center">Governor for Claude Code</h1>
  5. <p align="center">
  6. <strong>Keep long AI coding sessions sharp under quota pressure.</strong>
  7. </p>
  8. <p align="center">
  9. Now also works with Cursor · Windsurf · Cline · Codex CLI · Gemini CLI · Hermes · DeepSeek
  10. </p>
  11. <p align="center">
  12. <img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-plugin-6D4AFF" />
  13. <img alt="Cursor" src="https://img.shields.io/badge/Cursor-skill-00A67E" />
  14. <img alt="Windsurf" src="https://img.shields.io/badge/Windsurf-skill-3B82F6" />
  15. <img alt="Cline" src="https://img.shields.io/badge/Cline-skill-F59E0B" />
  16. <img alt="Codex CLI" src="https://img.shields.io/badge/Codex%20CLI-skill-10A37F" />
  17. <img alt="Gemini CLI" src="https://img.shields.io/badge/Gemini%20CLI-skill-4285F4" />
  18. <img alt="Hermes" src="https://img.shields.io/badge/Hermes-skill-E44D26" />
  19. <img alt="DeepSeek" src="https://img.shields.io/badge/DeepSeek-skill-536DFE" />
  20. <img alt="Version" src="https://img.shields.io/badge/version-0.2.5-black" />
  21. <img alt="License" src="https://img.shields.io/badge/license-MIT-0F766E" />
  22. </p>
  23. <p align="center">
  24. <a href="#quick-start">Quick Start</a> ·
  25. <a href="#multi-agent-support">Multi-Agent</a> ·
  26. <a href="#why-governor">Why Governor</a> ·
  27. <a href="#benchmarks">Benchmarks</a> ·
  28. <a href="#commands">Commands</a> ·
  29. <a href="#install">Install</a>
  30. </p>
  31. Governor started as a Claude Code plugin for context hygiene, tool-output
  32. filtering, memory compression, telemetry, and drift guardrails.
  33. **As of v0.2.4, Governor's core behavior — content-aware tool-output filtering
  34. and context hygiene — works with any AI coding agent** via prompt-based skills.
  35. No hooks or MCP required.
  36. > Keep long coding sessions efficient without making the model dumber.
  37. The Claude Code command namespace is `/governor:*`.
  38. ## Quick Start
  39. ### Claude Code (full plugin)
  40. ```bash
  41. bash install.sh --force
  42. ```
  43. Restart Claude Code. Filtering, compact mode, and telemetry are already running —
  44. there is nothing to turn on. When you want to look under the hood:
  45. ```text
  46. /governor:status
  47. /governor:audit
  48. /governor:compress CLAUDE.md
  49. ```
  50. ### Other Agents (prompt-based skill)
  51. ```bash
  52. bash install.sh --project /path/to/project --agents all
  53. ```
  54. This copies a Governor rules file into your project for each agent. The rules
  55. teach the agent to self-filter noisy tool output, preserve unique data, and
  56. maintain context hygiene — automatically, every session.
  57. ## Multi-Agent Support
  58. Governor works at two levels:
  59. | Agent | Integration | What You Get |
  60. |---|---|---|
  61. | **Claude Code** | Plugin with hooks | Full: auto-filtering, telemetry, compression, drift guard, `/governor:*` commands |
  62. | **Cursor** | `.cursor/rules/governor.mdc` | Self-filtering, compact mode, context hygiene |
  63. | **Windsurf** | `.windsurf/rules/governor.md` | Self-filtering, compact mode, context hygiene |
  64. | **Cline** | `.clinerules/governor.md` | Self-filtering, compact mode, context hygiene |
  65. | **Codex CLI** | `AGENTS.md` | Self-filtering, compact mode, context hygiene |
  66. | **Gemini CLI** | `GEMINI.md` | Self-filtering, compact mode, context hygiene |
  67. | **Hermes** 🆕 | `.hermes.md` | Self-filtering, compact mode, context hygiene |
  68. | **DeepSeek** 🆕 | `.dsh/rules/governor.md` | Self-filtering, compact mode, context hygiene |
  69. **How it works for non-Claude agents:** Governor's rules file teaches the agent
  70. to apply content-aware filtering itself. When tool output has >40% duplicate
  71. lines (test failures, log spam, build warnings), the agent compresses it —
  72. keeping the first error, file:line, and exit code. When output is unique (API
  73. responses, JSON, code), it passes through intact. No external dependencies.
  74. Claude Code gets the deepest integration because it supports plugin hooks.
  75. Other agents get the core behavior via prompt engineering.
  76. ## Why Governor
  77. Long coding sessions usually do not fail because the AI writes one extra
  78. paragraph.
  79. They fail because context gets polluted:
  80. - verbose test, build, and MCP output floods the transcript
  81. - bloated recurring files like `CLAUDE.md`, notes, and rules tax every session
  82. - broad prompts trigger repo-wide scans and retries
  83. - scope drift compounds over time
  84. Governor is designed for that failure mode — in Claude Code and beyond.
  85. ## What It Does
  86. | Capability | What it does | Where it works |
  87. |---|---|---|
  88. | Tool-output filtering | Compacts noisy output when content is repetitive; preserves unique data | All 8 agents |
  89. | Compact mode | Keeps responses concise and professional | All 8 agents |
  90. | Context hygiene | Avoids re-reads, broad scans, and context waste | All 8 agents |
  91. | Memory compression | Rewrites bloated prompt files into denser, safer forms | Claude Code |
  92. | Telemetry | Reports measured savings, failures, compactions, and waste heat | Claude Code |
  93. | Drift guardrails | Adds planning and scope checks for broad tasks | Claude Code |
  94. ## Why It Feels Different
  95. Most token-saving tools optimize one layer:
  96. - shorter replies
  97. - shorter command output
  98. Governor is built for the broader session problem:
  99. - tool spam
  100. - recurring context tax
  101. - MCP-heavy workflows
  102. - long-task drift
  103. - wasted retries
  104. That is why Governor's benchmark story starts with valid-context loss and
  105. decision preservation, not only token counts.
  106. ## Benchmarks
  107. ### V2 Sonnet Fixture Run
  108. Recent measured Sonnet run with Claude decision grading:
  109. | Condition | Avg token savings | Avg VCLR | Decision preserved | Wrong decision |
  110. |---|---:|---:|---:|---:|
  111. | Caveman | 69.1% | 0.14 | 87.5% | 12.5% |
  112. | Governor | 45.5% | 0.00 | 100.0% | 0.0% |
  113. What this means:
  114. - Caveman still wins on raw compression.
  115. - Governor preserved more valid context in this run.
  116. - Governor won on decision quality in the latest Sonnet pass.
  117. Artifacts:
  118. - `benchmarks/v2-fixture-results.md`
  119. - `benchmarks/v2-fixture-results.json`
  120. - `benchmarks/sonnet-v2-report.md`
  121. ### Early Multi-Turn Pilot
  122. Same machine, fresh Claude CLI Sonnet sessions, same multi-turn task, same
  123. starting repo snapshot.
  124. | Condition | Output Tokens | Cost | Turns | Intent Preserved | Obvious Regression Found |
  125. |---|---:|---:|---:|---|---|
  126. | Control | 10,997 | $0.5169 | 21 | Yes | No |
  127. | Governor | 10,113 | $0.4933 | 22 | Yes | No |
  128. | Delta | -8.0% | -4.6% | +4.8% | Tie | Tie |
  129. This was a narrow pilot, not a universal claim. It matters because Governor
  130. kept the implementation contract intact while shaving cost on a real multi-turn
  131. coding task.
  132. ### Tool Filter Signal Checks
  133. Structured/local cases focused on the criticism that compaction can miss the
  134. real clue.
  135. | Case | Filtered? | Blocked | Signal Preserved |
  136. |---|---:|---:|---:|
  137. | Noisy pytest failure buried in long log | Yes | 64.0% | Yes |
  138. | Burp-style MCP payload with large history + one critical finding | Yes | 90.9% | Yes |
  139. | Large `Read` output containing source code | No | 0.0% | Yes |
  140. ## Compared To
  141. Governor sits in a different layer from the other token-savers, so it stacks
  142. with them rather than replacing them.
  143. | Tool | Shrinks | Overlap with Governor |
  144. |---|---|---|
  145. | [Ponytail](https://github.com/DietrichGebert/ponytail) | The code the agent writes | None |
  146. | [Caveman](https://github.com/JuliusBrussee/caveman) | The prose the agent speaks | None |
  147. | RTK | The shell output you pipe through it | Partial |
  148. | **Governor** | **The context the session consumes** | — |
  149. ### Ponytail
  150. Ponytail is a YAGNI enforcer: before writing code it walks a ladder — does this
  151. need to exist, is it already in the codebase, does the stdlib or platform do it —
  152. and stops at the first rung that holds. Their
  153. [published benchmark](https://github.com/DietrichGebert/ponytail/blob/main/benchmarks/results/2026-06-18-agentic.md)
  154. reports ~54% less code written against a no-skill baseline. Those are their
  155. numbers on their fixtures, not something Governor has independently reproduced.
  156. Ponytail does not read tool output. Governor does not touch code generation. Run
  157. both: Ponytail keeps the agent from over-building, Governor keeps the test logs
  158. and MCP payloads from that build out of your context window.
  159. ### RTK
  160. RTK is excellent at shrinking shell output.
  161. Governor is aimed at the wider coding session:
  162. - tool-output filtering across all agents
  163. - recurring prompt-file hygiene
  164. - MCP and structured payload handling
  165. - drift-sensitive long sessions
  166. - measured savings and waste heat
  167. ### Caveman
  168. Caveman is excellent when the main goal is making Claude talk in fewer tokens.
  169. Governor is built for the broader session problem:
  170. - less tool spam
  171. - less recurring context tax
  172. - less drift
  173. - more decision preservation under pressure
  174. Short version:
  175. > Ponytail shrinks what gets built. Caveman shrinks what gets said. RTK shrinks
  176. > what a command prints. Governor protects the session that holds all three.
  177. ## Best Fit
  178. Governor is best for:
  179. - Claude Code Max users who hit long-session limits
  180. - Cursor / Windsurf / Cline / Hermes / DeepSeek users who want context hygiene without switching tools
  181. - MCP-heavy workflows (Burp, Playwright, structured tool output)
  182. - prompt-heavy repos with large rules or command docs
  183. - teams using multiple AI agents on the same codebase
  184. Governor is less useful for:
  185. - tiny chats
  186. - already-clean prompt files
  187. - users who only want meme-simple answer shortening
  188. ## Features
  189. - **Content-aware tool filtering:** large outputs are only compacted when
  190. content is repetitive noise (>40% duplicate lines). Unique data — API
  191. responses, Burp proxy history, curl output, structured JSON — passes through
  192. unfiltered. Works in all supported agents.
  193. - **Always-on compact mode:** keeps responses concise and professional.
  194. In Claude Code via hooks; in other agents via rules files.
  195. - **Professional memory compression:** `/governor:compress CLAUDE.md` rewrites
  196. verbose memory files into dense prose. (Claude Code)
  197. - **Protected-span safety:** code blocks, inline code, paths, URLs, commands,
  198. env vars, versions, headings, tables, and warnings are preserved.
  199. - **Quality guard:** low-savings compression is rejected and the backup is
  200. restored instead of pretending success.
  201. - **Inline full-output bypass:** set `GOVERNOR_FULL=1` as an env var in the
  202. same Bash call to skip compaction without a separate command. Immune to
  203. parallel-call cancellation.
  204. - **Telemetry ledger:** `/governor:status` reports blocked tokens, failures,
  205. compactions, and statusline snapshots when available. (Claude Code)
  206. - **Prompt guidance:** vague broad prompts get soft, non-blocking suggestions.
  207. - **Plan and drift guard:** explicit contracts for broad builds, then scope
  208. checks by running `/governor:plan` again. (Claude Code)
  209. ## Commands
  210. Governor is designed to work without commands. Everything below is optional.
  211. ### Automatic — no command needed
  212. | Behavior | When it runs |
  213. |---|---|
  214. | Tool-output filtering | Every tool call, once output is noisy and large |
  215. | Compact response mode | Every session, from the moment the plugin loads |
  216. | Telemetry + statusline | Continuously in the background |
  217. | Prompt-risk suggestions | When a prompt would trigger a broad scan or retry loop |
  218. | Mode switching by plain language | "turn off governor" / "enable governor" |
  219. | Full output for one command | Prefix it: `GOVERNOR_FULL=1 pytest -vv` |
  220. ### The five commands
  221. | Command | Purpose |
  222. |---|---|
  223. | `/governor:status` | Usage dashboard, waste heat map, current mode |
  224. | `/governor:mode [on\|off\|full\|strict]` | Control Governor; no argument reports current mode |
  225. | `/governor:audit [paths]` | Find bloated memory/rule files and context waste |
  226. | `/governor:compress [level] [file]` | Compress memory files with protected-span validation |
  227. | `/governor:plan "task"` | Write an implementation contract; run again later to check drift |
  228. `/governor:plan` picks its phase automatically: no saved contract for this
  229. project means it writes one, an existing contract means it reports drift against
  230. it. Contracts are scoped to the project that created them.
  231. Two things that used to be slash commands are now plain scripts:
  232. ```bash
  233. python3 scripts/run_benchmark.py # was /governor:benchmark
  234. python3 scripts/install_rules.py --project . --agents all --force # was /governor:install-rules
  235. ```
  236. ## Install
  237. ### Claude Code (Full Plugin)
  238. ```bash
  239. gh repo clone 0xhimanshu/governor
  240. cd governor
  241. bash install.sh --force
  242. ```
  243. ### Other Agents
  244. ```bash
  245. bash install.sh --project /path/to/project --agents all
  246. ```
  247. Or install for specific agents:
  248. ```bash
  249. bash install.sh --project . --agents cursor,windsurf
  250. bash install.sh --project . --agents cline,codex,gemini
  251. bash install.sh --project . --agents hermes,deepseek
  252. ```
  253. ### Local Development
  254. ```bash
  255. claude --plugin-dir .
  256. ```
  257. ## How Compression Works
  258. `/governor:compress` is automatic from the user's point of view:
  259. 1. Create a timestamped backup.
  260. 2. Mark protected spans.
  261. 3. Rewrite the file with dense professional prose.
  262. 4. Strip markers.
  263. 5. Validate protected content.
  264. 6. Attempt protected-span recovery if needed.
  265. 7. Reject low-savings output and restore the backup if the quality guard fails.
  266. 8. Report exact before/after token estimates and backup location.
  267. Compression levels:
  268. | Level | Target |
  269. |---|---|
  270. | `light` | Remove filler and repetition; preserve most rationale |
  271. | `medium` | Collapse narrative into decision bullets |
  272. | `aggressive` | Keep only rules, facts, commands, risks, and decisions |
  273. Set `GOVERNOR_ALLOW_LOW_SAVINGS=1` only if you intentionally want to keep a
  274. low-savings compression result.
  275. ## Telemetry
  276. Governor stores a local JSONL ledger. The status command automatically discovers
  277. and merges ledger files from all known locations, including the plugin data
  278. directory set by Claude Code (`CLAUDE_PLUGIN_DATA`) and the manual fallback
  279. path. Deduplication uses resolved paths so symlinks and non-canonical paths
  280. do not cause double-counting.
  281. It tracks:
  282. - tool-output tokens blocked
  283. - full-output overrides
  284. - prompt-risk suggestions
  285. - Bash failures
  286. - compactions
  287. - statusline snapshots
  288. - memory compression savings
  289. ## Benchmarking
  290. Use `benchmarks/` for measured comparisons.
  291. Recommended conditions:
  292. - `control`: no token/style plugin
  293. - `caveman`: Caveman enabled as normal
  294. - `governor-hooks`: Governor hooks enabled, memory unchanged
  295. - `governor-compressed`: Governor after `/governor:compress CLAUDE.md`
  296. - `governor-strict`: optional strict-mode run for broad tasks
  297. Run:
  298. ```bash
  299. python3 scripts/run_benchmark.py \
  300. --write-json benchmarks/v2-fixture-results.json \
  301. --write-md benchmarks/v2-fixture-results.md
  302. ```
  303. Refreshing the captured Caveman and Governor comparator replays is documented in
  304. [benchmarks/README.md](benchmarks/README.md).
  305. ## Design Principles
  306. - Helpful by default, strict only when invoked.
  307. - Professional dense prose, never novelty dialect.
  308. - Measure exact savings where possible.
  309. - Treat 1M context as a ceiling, not a target.
  310. - Keep broad planning and drift checks opt-in.
  311. - Restore backups instead of accepting unsafe or low-value compression.
  312. ## Gotchas
  313. - If hooks do not fire, `/governor:status` will show little or no telemetry.
  314. - Existing custom statuslines are not overwritten by the installer.
  315. - Compression sends file content through the active Claude Code/model workflow.
  316. Do not compress secrets or sensitive private files.
  317. - When you need unfiltered logs, prefix the command with `GOVERNOR_FULL=1`, or
  318. run `/governor:mode full` before the diagnostic step.
  319. - For installed-but-inactive behavior, launch Claude Code with
  320. `GOVERNOR_DEFAULT_MODE=off`.
  321. ## Contributing
  322. Contributions are welcome when they make Governor more useful, safer, or easier
  323. to trust. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull
  324. request, especially for compression, hook, telemetry, agent rules, or benchmark
  325. changes.
  326. ## Star History
  327. <a href="https://star-history.com/#0xhimanshu/governor&Date">
  328. <picture>
  329. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=0xhimanshu/governor&type=Date&theme=dark" />
  330. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=0xhimanshu/governor&type=Date" />
  331. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=0xhimanshu/governor&type=Date" />
  332. </picture>
  333. </a>
  334. ## License
  335. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.