feat(components): add Headroom MCP component for context compression

docs/components.md

@@ -12,6 +12,7 @@
 | SDD | `sdd` | Spec-Driven Development workflow (10 phases, including `sdd-onboard`) — the agent handles SDD organically when the task warrants it, or when you ask; you don't need to learn the commands |
 | Skills | `skills` | Curated coding skill library |
 | Context7 | `context7` | MCP server for live framework/library documentation |
+| Headroom | `headroom` | MCP context compression server — compresses verbose tool outputs and LLM responses to stay within context window limits via three tools: `compress`, `retrieve`, and `stats`. Installed via pip (`headroom-ai[all]`). See [headroom docs](headroom.md) |
 | Persona | `persona` | Managed Gentleman/neutral persona injection, or unmanaged custom persona mode |
 | Permissions | `permissions` | Security-first defaults and guardrails. Applied to Claude Code and OpenCode (the two adapters with permissions overlay support). Default sensitive-paths deny list: `~/.ssh/*`, `~/.ssh/**/*`, `**/*.pem`, `**/*.key`, `**/.env*`, `~/.credentials/*`, `~/.aws/credentials`, `~/.config/gh/hosts.yml`, `~/Library/Keychains/*`, `**/secrets/*`, `**/*.p12`, `**/*.pfx` |
 | GGA | `gga` | Gentleman Guardian Angel — AI provider switcher |
@@ -80,8 +81,8 @@ For framework-specific skills (React 19, Angular, TypeScript, Tailwind 4, Zod 4,
 
 | Preset | ID | What's Included |
 |--------|-----|-----------------|
-| Dev Stack + Polish | `full-gentleman` | All components (Engram + SDD + Skills + Context7 + GGA + Permissions + Theme) + all skills |
-| Dev Stack | `ecosystem-only` | Core components (Engram + SDD + Skills + Context7 + GGA) + all skills |
+| Dev Stack + Polish | `full-gentleman` | All components (Engram + SDD + Skills + Context7 + Headroom + GGA + Permissions + Theme) + all skills |
+| Dev Stack | `ecosystem-only` | Core components (Engram + SDD + Skills + Context7 + Headroom + GGA) + all skills |
 | Memory Only | `minimal` | Engram + SDD skills only |
 | Custom | `custom` | You choose components and skills manually while keeping any existing persona/settings unmanaged |
 

docs/headroom.md

@@ -0,0 +1,116 @@
+# Headroom — Context Compression MCP Server
+
+← [Back to README](../README.md) · [Components & Presets](components.md)
+
+---
+
+Headroom is an MCP server that compresses verbose content — tool outputs, LLM responses, file contents — to help you stay within context window limits without losing information you might need later.
+
+## The Problem
+
+AI coding agents produce enormous tool outputs: directory listings, file reads, git diffs, search results, linter output, test logs. Each one eats into your context window. When the window fills, the agent starts forgetting earlier instructions, decisions, or code context.
+
+Engram solves the **cross-session** memory problem. Headroom solves the **within-session** context pressure problem. They are complementary.
+
+## How It Works
+
+Headroom exposes three MCP tools that the agent can call on demand:
+
+| Tool | What it does |
+|------|-------------|
+| `headroom_compress` | Compresses a text block and returns a short reference handle |
+| `headroom_retrieve` | Decompresses a reference handle back to full text |
+| `headroom_stats` | Reports compression ratios and total savings for the session |
+
+The agent decides when to compress — typically when it notices the context is getting full or when a tool output is unusually large. Compressed content is stored locally; nothing leaves your machine.
+
+## Installation
+
+Headroom is installed automatically by `gentle-ai` when you select it as a component:
+
+### Via TUI
+
+```
+gentle-ai install
+```
+
+Select `Headroom` in the components screen (included by default in the `full-gentleman` and `ecosystem-only` presets).
+
+### Via CLI
+
+```bash
+gentle-ai install --component headroom
+```
+
+The installer will:
+1. Check if `headroom` is already on your PATH
+2. If not, find `pip` or `pip3` and run `pip install "headroom-ai[all]"`
+3. Inject MCP configuration into all your configured agents
+
+### Manual Installation
+
+If you prefer to install Headroom yourself:
+
+```bash
+pip install "headroom-ai[all]"
+```
+
+Then run `gentle-ai install --component headroom` to configure your agents, or `gentle-ai sync` if Headroom is already in your selection.
+
+## What Gets Configured
+
+For each agent you have installed, gentle-ai writes the correct MCP config:
+
+| Agent | Config File | Format |
+|-------|-------------|--------|
+| Claude Code | `~/.claude/mcp/headroom.json` | Separate file |
+| OpenCode / Kilo Code | `opencode.json` `mcp.headroom` | Merge overlay |
+| Cursor | `~/.cursor/mcp.json` `mcpServers.headroom` | Merge |
+| VS Code Copilot | `Code/User/mcp.json` `servers.headroom` | Merge |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | Merge |
+| Codex | `~/.codex/config.toml` `[mcp_servers.headroom]` | TOML block |
+| Gemini CLI | `~/.gemini/settings.json` `mcpServers.headroom` | Merge |
+| Antigravity | `~/.gemini/antigravity/mcp_config.json` | Merge |
+| Kimi Code | `~/.kimi/settings.json` | Merge |
+| Qwen Code | `~/.qwen/settings.json` | Merge |
+| Kiro IDE | `~/.kiro/settings/mcp.json` | Merge |
+| OpenClaw | `~/.openclaw/openclaw.json` | Merge |
+| Trae | App support dir `mcp.json` | Merge |
+| Pi | `.pi/settings.json` | Merge |
+| Hermes | `~/.hermes/config.yaml` | YAML block |
+
+All entries point to a local `headroom` process with `args: ["mcp", "serve"]`.
+
+## Uninstalling
+
+```bash
+gentle-ai uninstall --component headroom
+```
+
+This removes all MCP config entries from your agents. To also remove the pip package:
+
+```bash
+pip uninstall headroom-ai
+```
+
+## Usage Tips
+
+- Headroom is most useful during long coding sessions where the agent performs many read/search/write operations
+- The agent calls `headroom_compress` automatically when it detects large outputs — you don't need to interact with it directly
+- Check savings with `headroom_stats` if you're curious how much context you've recovered
+- If the agent seems to forget earlier context, try asking: "check your context usage with headroom_stats and compress anything you don't need right now"
+
+## Comparison
+
+| | Engram | Headroom |
+|--|--------|----------|
+| What | Cross-session persistent memory | Within-session context compression |
+| When | Between coding sessions | During a long session |
+| How | FTS5 search + save/recall | Compress/decompress large text blocks |
+| Analogy | Your project notebook | Vacuum packing bulky items in your current workspace |
+
+## References
+
+- [Headroom GitHub](https://github.com/headroomlabs-ai/headroom)
+- [Headroom PyPI](https://pypi.org/project/headroom-ai/)
+- [Components & Presets Reference](components.md)

internal/catalog/components.go

@@ -19,6 +19,7 @@ var mvpComponents = []Component{
 	{ID: model.ComponentTheme, Name: "Theme", Description: "Gentleman Kanagawa theme overlay"},
 	{ID: model.ComponentClaudeTheme, Name: "Claude Gentleman Theme", Description: "Claude Code Gentleman custom theme"},
 	{ID: model.ComponentOpenCodeGentleLogo, Name: "OpenCode Gentle Logo", Description: "OpenCode home logo TUI plugin with Braille rose"},
+	{ID: model.ComponentHeadroom, Name: "Headroom", Description: "AI memory compression and retrieval for tool-use chains"},
 }
 
 func MVPComponents() []Component {

internal/cli/doctor.go

@@ -38,7 +38,7 @@ type DoctorReport struct {
 	Checks []CheckResult
 }
 
-var knownTools = []string{"gentle-ai", "engram", "gga", "claude", "opencode"}
+var knownTools = []string{"gentle-ai", "engram", "gga", "claude", "opencode", "headroom"}
 
 const (
 	engramHealthEnvVar = "ENGRAM_BASE_URL"

internal/cli/install_test.go

@@ -79,6 +79,7 @@ func TestNormalizeInstallFlagsDefaults(t *testing.T) {
 			model.ComponentContext7,
 			model.ComponentPermission,
 			model.ComponentGGA,
+			model.ComponentHeadroom,
 			model.ComponentClaudeTheme,
 			model.ComponentOpenCodeGentleLogo,
 			model.ComponentPersona,

internal/cli/run.go

@@ -34,6 +34,7 @@ import (
 	"github.com/gentleman-programming/gentle-ai/internal/planner"
 	"github.com/gentleman-programming/gentle-ai/internal/state"
 	"github.com/gentleman-programming/gentle-ai/internal/system"
+	"github.com/gentleman-programming/gentle-ai/internal/versions"
 	"github.com/gentleman-programming/gentle-ai/internal/verify"
 )
 
@@ -866,11 +867,32 @@ func (s componentApplyStep) Run() error {
 		return nil
 	case model.ComponentContext7:
 		for _, adapter := range adapters {
-			if _, err := mcp.Inject(s.homeDir, adapter); err != nil {
+			if _, err := mcp.Inject(s.homeDir, adapter, model.ComponentContext7); err != nil {
 				return fmt.Errorf("inject context7 for %q: %w", adapter.Agent(), err)
 			}
 		}
 		return nil
+	case model.ComponentHeadroom:
+		if _, err := cmdLookPath("headroom"); err != nil {
+			// headroom not on PATH — install the pip package.
+			pipCmd := "pip"
+			if _, pipErr := cmdLookPath(pipCmd); pipErr != nil {
+				pipCmd = "pip3"
+				if _, pip3Err := cmdLookPath(pipCmd); pip3Err != nil {
+					return fmt.Errorf("headroom: %[1]w and pip/pip3 not found — install headroom-ai[all] via pip or add headroom to PATH before running install: %[1]w", err)
+				}
+			}
+			fmt.Fprintf(os.Stderr, "INFO: headroom binary not found on PATH — installing headroom-ai[all]==%s via %s\n", versions.HeadroomMCP, pipCmd)
+			if installErr := runCommand(pipCmd, "install", fmt.Sprintf("headroom-ai[all]==%s", versions.HeadroomMCP)); installErr != nil {
+				return fmt.Errorf("install headroom via %s: %w", pipCmd, installErr)
+			}
+		}
+		for _, adapter := range adapters {
+			if _, err := mcp.Inject(s.homeDir, adapter, model.ComponentHeadroom); err != nil {
+				return fmt.Errorf("inject headroom for %q: %w", adapter.Agent(), err)
+			}
+		}
+		return nil
 	case model.ComponentPersona:
 		for _, adapter := range adapters {
 			targetDir := componentInjectionDirScoped(s.homeDir, s.workspaceDir, s.scope, adapter)
@@ -1292,6 +1314,23 @@ func componentPathsWithWorkspaceScoped(homeDir, workspaceDir string, scope Insta
 					paths = append(paths, p)
 				}
 			}
+		case model.ComponentHeadroom:
+			switch adapter.MCPStrategy() {
+			case model.StrategySeparateMCPFiles:
+				paths = append(paths, adapter.MCPConfigPath(homeDir, "headroom"))
+			case model.StrategyMergeIntoSettings:
+				if p := adapter.SettingsPath(homeDir); p != "" {
+					paths = append(paths, p)
+				}
+			case model.StrategyMCPConfigFile:
+				if p := adapter.MCPConfigPath(homeDir, "headroom"); p != "" {
+					paths = append(paths, p)
+				}
+			case model.StrategyTOMLFile:
+				if p := adapter.MCPConfigPath(homeDir, "headroom"); p != "" {
+					paths = append(paths, p)
+				}
+			}
 		case model.ComponentPersona:
 			if selection.Persona == model.PersonaCustom {
 				break

internal/cli/sync.go

@@ -295,6 +295,7 @@ func BuildSyncSelection(flags SyncFlags, agentIDs []model.AgentID) model.Selecti
 		model.ComponentSDD,
 		model.ComponentEngram,
 		model.ComponentContext7,
+		model.ComponentHeadroom,
 		model.ComponentGGA,
 		model.ComponentSkills,
 	}
@@ -629,14 +630,24 @@ func (s componentSyncStep) Run() error {
 
 	case model.ComponentContext7:
 		for _, adapter := range adapters {
-			res, err := mcp.Inject(s.homeDir, adapter)
+			res, err := mcp.Inject(s.homeDir, adapter, model.ComponentContext7)
 			if err != nil {
 				return fmt.Errorf("sync context7 for %q: %w", adapter.Agent(), err)
 			}
 			s.countChanged(boolToInt(res.Changed), res.Files...)
 		}
 		return nil
 
+	case model.ComponentHeadroom:
+		for _, adapter := range adapters {
+			res, err := mcp.Inject(s.homeDir, adapter, model.ComponentHeadroom)
+			if err != nil {
+				return fmt.Errorf("sync headroom for %q: %w", adapter.Agent(), err)
+			}
+			s.countChanged(boolToInt(res.Changed), res.Files...)
+		}
+		return nil
+
 	case model.ComponentSDD:
 		profileStrategy := sdd.ResolveProfileStrategy(s.homeDir, s.selection.SDDProfileStrategy)
 

internal/cli/validate.go

@@ -161,7 +161,7 @@ func componentsForPreset(preset model.PresetID, persona model.PersonaID) []model
 	case model.PresetMinimal:
 		components = []model.ComponentID{model.ComponentEngram}
 	case model.PresetEcosystemOnly:
-		components = []model.ComponentID{model.ComponentEngram, model.ComponentSDD, model.ComponentSkills, model.ComponentContext7, model.ComponentGGA}
+		components = []model.ComponentID{model.ComponentEngram, model.ComponentSDD, model.ComponentSkills, model.ComponentContext7, model.ComponentGGA, model.ComponentHeadroom}
 	case model.PresetCustom:
 		return nil
 	default: // full-gentleman
@@ -172,6 +172,7 @@ func componentsForPreset(preset model.PresetID, persona model.PersonaID) []model
 			model.ComponentContext7,
 			model.ComponentPermission,
 			model.ComponentGGA,
+			model.ComponentHeadroom,
 			model.ComponentClaudeTheme,
 			model.ComponentOpenCodeGentleLogo,
 		}

internal/components/mcp/headroom.go

@@ -0,0 +1,66 @@
+package mcp
+
+var defaultHeadroomServerJSON = []byte("{\n  \"command\": \"headroom\",\n  \"args\": [\n    \"mcp\",\n    \"serve\"\n  ]\n}\n")
+
+var defaultHeadroomOverlayJSON = []byte("{\n  \"mcpServers\": {\n    \"headroom\": {\n      \"command\": \"headroom\",\n      \"args\": [\n        \"mcp\",\n        \"serve\"\n      ]\n    }\n  }\n}\n")
+
+// openCodeHeadroomOverlayJSON is the opencode.json overlay using the new MCP format.
+// Headroom is a local stdio MCP server.
+// The headroom entry must replace atomically so legacy local keys do not survive
+// deep merge into OpenCode/KiloCode's strict MCP schema.
+var openCodeHeadroomOverlayJSON = []byte("{\n  \"mcp\": {\n    \"headroom\": {\n      \"__replace__\": {\n        \"type\": \"local\",\n        \"command\": \"headroom\",\n        \"args\": [\n          \"mcp\",\n          \"serve\"\n        ],\n        \"enabled\": true\n      }\n    }\n  }\n}\n")
+
+// openClawHeadroomOverlayJSON is the OpenClaw openclaw.json overlay.
+var openClawHeadroomOverlayJSON = []byte("{\n  \"mcp\": {\n    \"servers\": {\n      \"headroom\": {\n        \"command\": \"headroom\",\n        \"args\": [\n          \"mcp\",\n          \"serve\"\n        ]\n      }\n    }\n  }\n}\n")
+
+// vsCodeHeadroomOverlayJSON is the VS Code mcp.json overlay using the "servers" key.
+var vsCodeHeadroomOverlayJSON = []byte("{\n  \"servers\": {\n    \"headroom\": {\n      \"command\": \"headroom\",\n      \"args\": [\n        \"mcp\",\n        \"serve\"\n      ]\n    }\n  }\n}\n")
+
+// antigravityHeadroomOverlayJSON is the Antigravity mcp_config.json overlay.
+// Uses mcpServers key with command/args for local stdio.
+var antigravityHeadroomOverlayJSON = []byte("{\n  \"mcpServers\": {\n    \"headroom\": {\n      \"__replace__\": {\n        \"command\": \"headroom\",\n        \"args\": [\n          \"mcp\",\n          \"serve\"\n        ]\n      }\n    }\n  }\n}\n")
+
+// kimiHeadroomOverlayJSON follows Kimi's documented mcp.json format for local servers.
+var kimiHeadroomOverlayJSON = []byte("{\n  \"mcpServers\": {\n    \"headroom\": {\n      \"__replace__\": {\n        \"command\": \"headroom\",\n        \"args\": [\n          \"mcp\",\n          \"serve\"\n        ]\n      }\n    }\n  }\n}\n")
+
+func DefaultHeadroomServerJSON() []byte {
+	content := make([]byte, len(defaultHeadroomServerJSON))
+	copy(content, defaultHeadroomServerJSON)
+	return content
+}
+
+func DefaultHeadroomOverlayJSON() []byte {
+	content := make([]byte, len(defaultHeadroomOverlayJSON))
+	copy(content, defaultHeadroomOverlayJSON)
+	return content
+}
+
+func OpenCodeHeadroomOverlayJSON() []byte {
+	content := make([]byte, len(openCodeHeadroomOverlayJSON))
+	copy(content, openCodeHeadroomOverlayJSON)
+	return content
+}
+
+func OpenClawHeadroomOverlayJSON() []byte {
+	content := make([]byte, len(openClawHeadroomOverlayJSON))
+	copy(content, openClawHeadroomOverlayJSON)
+	return content
+}
+
+func VSCodeHeadroomOverlayJSON() []byte {
+	content := make([]byte, len(vsCodeHeadroomOverlayJSON))
+	copy(content, vsCodeHeadroomOverlayJSON)
+	return content
+}
+
+func AntigravityHeadroomOverlayJSON() []byte {
+	content := make([]byte, len(antigravityHeadroomOverlayJSON))
+	copy(content, antigravityHeadroomOverlayJSON)
+	return content
+}
+
+func KimiHeadroomOverlayJSON() []byte {
+	content := make([]byte, len(kimiHeadroomOverlayJSON))
+	copy(content, kimiHeadroomOverlayJSON)
+	return content
+}