Claude Context Governor

Claude Context Governor

Claude Code Control Plane for MCPs, Skills, and Model Routing.

Not memory restoration. Not another MCP server. A runtime governor for what enters Claude Code context.

Run a dozen MCP servers and a hundred skills. Pay context for only the ones doing work right now.

Install · Configure · gov.* tools · Skills · Verification · Comparison · Audit · Routing · Architecture · Benchmarks · Tests · FAQ · Contributing

New here? Start with Install → Configure backends → Route prompts.

---

The control governor for Claude Code

Your existing MCP servers stay where they are. Your skill library stays where it is. Your hooks stay where they are. The governor sits one layer above them and decides three things:

1. Which MCP backends are awake right now, and which are sleeping.
2. Which skills load into the session prompt, and which sit on disk until called.
3. Which kinds of prompts deserve which model.

Claude Code sees one MCP entry. The governor handles the fan-out, the lifecycle, and the routing. Sessions start fast because dormant capability stops costing tokens.

The cost you're paying right now

Every MCP server you've added to Claude Code registers its full tool catalog at session start. Every skill in ~/.claude/skills/ loads its manifest into the system prompt. Every hook fires on every turn. None of that depends on whether you'll use those tools today.

                        BEFORE                         AFTER
─────────────────────────────────────  ─────────────────────────────────────
12 MCP servers           ~18,400 tok   1 MCP server               ~2,100 tok
91 skills loaded         ~11,700 tok   24 skills loaded           ~3,200 tok
8 hooks                     ~400 tok   8 hooks                      ~400 tok
─────────────────────────────────────  ─────────────────────────────────────
Session start            ~30,500 tok   Session start              ~5,700 tok
                                                                      (–81%)

Illustrative numbers from a typical power-user setup. Actual savings depend on which backends and skills you run. The governor doesn't make any single tool cheaper to call. It removes the cost of the ones you aren't calling.

Measurement tooling

Illustrative numbers are useful for explaining the shape of the problem, but the project also ships a measurement command so teams can inspect their own environment.

CLI:

context-governor measure
context-governor measure --baseline ~/.claude/settings.json
context-governor measure --skills
context-governor measure --mcp

Target output:

Baseline:
12 MCP servers, 184 tools, estimated 18,420 tokens
91 skills, estimated 11,740 tokens

Governor:
1 MCP entry, 12 gov tools, estimated 2,100 tokens
24 active skills, estimated 3,200 tokens

Estimated saved: 24,860 tokens / session

The goal is to make the promise concrete: show the before/after inventory, expose the assumptions behind token estimates, and let users compare their actual Claude Code setup instead of relying on generic examples.

Benchmarks

Measurement output is not enough on its own, so the repo keeps benchmark fixtures and generated result artifacts under benchmarks/.

npm run bench

Current artifact:

• [benchmarks/results/fixture-mcp-tool-catalog.md](./benchmarks/results/fixture-mcp-tool-catalog.md)
• [benchmarks/results/fixture-mcp-tool-catalog.json](./benchmarks/results/fixture-mcp-tool-catalog.json)

The fixture benchmark is intentionally conservative: it reports projected baseline tokens, projected governor tokens, and the caveat that this is not a live Claude usage run. If the fixture shows negative savings, the result stays negative. The point is to make the benchmark honest and reproducible, not to force a flattering number.

Highlights

• [One MCP entry, N backends](#configure-backends). Multiplex whichever MCP servers you already use (Serena, Context7, Playwright, Supabase, GitHub, Figma, etc.) behind one connection. Nothing extra to install.
• [Lazy lifecycle](#configure-backends). always_on backends run as launchd services; on-demand backends spawn on first call and die after idle.
• [gov.* intent tools](#the-gov-tools). High-level tools (gov.search_code, gov.search_docs, gov.browser_task, gov.project_tool) that route to your backends.
• [Skill governor](#manage-skills). Move skills between ~/.claude/skills/ (loaded) and ~/.claude/skills-inactive/ (parked) with one command.
• [Prompt routing](#route-prompts-to-the-right-model). Regex classifier tags risky work for Opus, read-only work for Haiku, everything else for Sonnet.
• [Secret hygiene](#faq). ${ENV_VAR} placeholders expand at connect time; logs auto-redact Bearer tokens, JWTs, and key=value patterns.
• [Reversible install](#why-a-governor-not-another-tool). Uninstall in 30 seconds; the installer writes a settings.json.backup-* file before patching.

What it is

Not another MCP server. Not a skill collection. Not a Claude Code fork.

Context Governor is the layer that sits between Claude Code and everything else. Claude Code sees one MCP entry. Behind that entry, the governor:

• Multiplexes MCP traffic. N backends, one connection upstream. Tools surface only when their backend is registered.
• Lifecycles backends. Always-on backends run as launchd services and stay warm. On-demand backends spawn on first call and die after an idle timeout. Disabled backends list nothing.
• Governs skills. ~/.claude/skills/ auto-loads; ~/.claude/skills-inactive/ doesn't. Move a skill between them with one command.
• Classifies prompts. A UserPromptSubmit hook tags risky work (auth, schema, billing, large refactor) for Opus and read-only work (why, what, find, summarize) for Haiku. The agent reads the tag and decides.
• Redacts secrets. Bearer tokens, JWTs, and key=value patterns get stripped before anything reaches governor.log. Log rotates at 2 MB.
• Expands env vars. Put ${EXAMPLE_API_TOKEN} in your registry; the governor resolves it at connect time. Secrets live in your shell, never in JSON.

The whole thing is one Node process behind one mcpServers entry. No daemon to babysit, no proprietary protocol, no lock-in.

Why a governor, not another tool

Every MCP server you've installed is a good tool. Every skill in your library is a good prompt. The problem isn't your tools. The problem is that Claude Code loads all of them at session start, whether you'll touch them today or not.

The governor doesn't compete with what you've installed. It decides when each thing earns its space in your current context budget.

A load balancer doesn't replace web servers; it decides which one answers each request. A kernel scheduler doesn't replace processes; it decides which one runs next. The governor works the same way for Claude Code: your backends do the work, your skills carry the prompts, and the governor decides which ones are awake, loaded, and routed for the session you're in right now.

You can uninstall it in 30 seconds. Delete the mcpServers.context-governor entry, restore your original MCP entries from the settings.json.backup-* file the installer wrote, and you're back where you started. Nothing about your existing setup is destructive or one-way.

Comparison

Context Governor focuses on preventing unnecessary context from entering the session in the first place: dormant MCP tools, inactive skills, and wrong-model workflows.

That makes it different from tools that primarily help recover, summarize, or reuse context after a session has already grown. Those approaches can be valuable. They solve a different problem. Context Governor sits earlier in the path and asks whether a backend, skill, hook, or route should enter Claude Code context at all.

It is also not trying to be a better MCP server than the servers you already use. It is a control plane above them: one Claude Code entry, governed fan-out underneath, and reversible configuration if you decide to go back.

Audit trail

Runtime decisions are written as local JSONL audit events. The audit trail records the things that matter for trust:

• backend connect/disconnect
• blocked disabled or unknown backends
• tool call start/success/error/timeout
• MCP tool-list requests
• user-facing gov.list_tools calls

Inspect it with:

context-governor audit

The audit path defaults to audit.jsonl next to the governor runtime and can be overridden with CONTEXT_GOVERNOR_AUDIT_PATH for tests or sandboxed installs.

Install

git clone https://github.com/TribalHouse/claude-context-governor
cd claude-context-governor
node install.mjs

The installer is idempotent. It creates the directory layout, copies the CLIs, runs npm install, backs up your ~/.claude/settings.json, adds the one context-governor entry, and grants the mcp__context-governor__* permission. Re-run any time.

Inspect first:

node install.mjs --dry-run        # show every action, write nothing
node install.mjs --no-settings    # install files, leave settings.json alone

Verify locally:

npm run verify

Configure backends

Drop one block per MCP server you already use into ~/.claude/context-governor/registry.json. The block tells the governor how to reach the backend and how to manage its lifecycle. The names below (serena, playwright, private-api) are just example identifiers, not required backends. Pick whatever names match your setup. See [docs/registry.md](./docs/registry.md) for the annotated registry guide. Three lifecycle modes:

{
  "serena": {
    "transport": "streamable-http",
    "endpoint": "http://127.0.0.1:12301/mcp",
    "always_on": true
  },

  "playwright": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@playwright/mcp@latest"],
    "always_on": false,
    "idle_timeout_seconds": 300
  },

  "private-api": {
    "transport": "streamable-http",
    "endpoint": "https://api.example.com/mcp",
    "headers": { "Authorization": "Bearer ${EXAMPLE_API_TOKEN}" },
    "always_on": false,
    "disabled": true
  }
}

| Mode | Behavior | |---|---| | always_on: true | Managed by launchd. Reconnects at startup. | | always_on: false | Spawned on first tool call. SIGTERM'd after idle. | | disabled: true | Never started. Tools not listed. |

Full schema and worked examples in [registry.example.json](./registry.example.json).

The gov.* tools

The agent sees a small set of high-level intent tools that route to whichever backends you've registered. None of these backends ship with the governor. Each shortcut appears only if you have a backend by that name in your registry; if you don't, the shortcut simply isn't listed.

| Tool | Routes to a backend named… | Appears when | |---|---|---| | gov.search_code | serena (any code-intelligence MCP) | You've registered a backend named serena | | gov.search_docs | context7 (any docs MCP) | You've registered a backend named context7 | | gov.browser_task | playwright (any browser MCP) | You've registered a backend named playwright | | gov.project_tool | any on-demand backend in your registry | You have at least one on-demand backend registered | | gov.list_tools | — | Always | | gov.tool_status | — | Always | | gov.cleanup_idle | — | Always |

In other words: the governor doesn't require Serena, Context7, or Playwright. It just provides nice shortcuts if those backends happen to be what you have. Bring your own MCP servers; the gov.project_tool target enum is built dynamically from your registry at startup. Add a backend and it appears; remove it and the tool disappears.

For debugging, set _settings.exposePassthroughTools: true in the registry; every backend tool surfaces as backend__toolname. Off by default to keep the catalog small.

Manage skills

Two directories. The governor moves directories between them.

skill-status                     # active + inactive, with [protected] flags
skill-status --search seo        # filter by name
skill-enable seo                 # inactive → active
skill-disable seo                # active → inactive
skill-disable caveman --force    # override protection
skill-use "seo audit"            # resolve alias, enable, print usage

Changes take effect after the next /clear or session restart.

Route prompts to the right model

Claude Code ships three model families (Opus, Sonnet, Haiku) and a subagent system that includes read-only scouts. Most teams pick one model and use it for everything because deciding per turn is annoying. The governor encodes a routing policy in regex so the agent does the deciding.

Add this hook to ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [{ "type": "command",
        "command": "node ~/.claude/context-governor/hooks/route-prompt.mjs" }]
    }]
  }
}

The hook doesn't change the active model. Claude Code's model is session-scoped and only you (or /model) can switch it. The hook reads stdin, classifies the text against two pattern lists, and emits at most one line of [ROUTING ADVICE: ...] into the agent's context for that turn. The agent reads it and decides whether to /model, delegate to a subagent, or stay put.

The three buckets

Opus route (high-risk, plan-first work). Matches auth, migration, schema change, rls, security audit, encryption, billing, payment, stripe, permissions model, large refactor, architectural decision, failed again, audit everything, and similar phrases. The hook emits:

[ROUTING ADVICE: opus — prompt looks high-risk (auth, schema, security,
billing, large refactor, or repeated failure). If not already on Opus,
consider /model opus or delegating to the opus-planner subagent before
editing files. Save the plan to .claude/last-opus-plan.md and wait for
user approval.]

This is where opusplan mode earns its keep. Claude Code's opusplan model auto-handles plan-then-execute handoff: the planner agent writes to .claude/last-opus-plan.md, you approve, the builder agent implements. The governor's hook is the trigger that escalates risky prompts into that workflow instead of letting Sonnet improvise.

Haiku route (read-only diagnostics, summaries, exploration). Matches prompts starting with why, what, where, when, how, which, who, plus summarize, tldr, find, locate, grep, where is, check the logs, diagnose, investigate, explain this, list all, read-only. The hook emits:

[ROUTING ADVICE: haiku — prompt looks like read-only diagnostics, summary,
or search. Consider delegating to the haiku-scout / explorer subagent
(Haiku 4.5 — read-only, ~5× cheaper). Do not edit files from the scout
agent.]

The haiku-scout and explorer subagents are read-only by design (no Edit, Write, or NotebookEdit tools). The hook routes log digging, "where is X defined", and noisy summary work to them.

Sonnet route (default). Anything that matches neither list. The hook stays silent and Claude Code sees the original prompt unchanged.

What you can override

The hook is advice, not enforcement. Three layers above it:

• Manual override in the prompt: "use sonnet for this" / "use haiku" / "use opus".
• Session-level: /model opus, /model sonnet, /model haiku.
• Agent delegation: Agent(subagent_type="haiku-scout", ...) from Sonnet/Opus regardless of route advice.

The classifier is a starting point, not a verdict. Tune the regex tables in route-prompt.mjs to match your team's vocabulary. The file is 111 lines and the patterns are the top half.

Why this matters for cost

Haiku 4.5 is roughly 5× cheaper than Sonnet per token. Opus is roughly 5× more expensive. A

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TribalHouse
• Source: TribalHouse/claude-context-governor
• License: MIT
• Homepage: https://github.com/TribalHouse/claude-context-governor

Install and usage instructions live in the source repository linked above.