feat(components): add Headroom MCP component for context compression#970
Open
RoX452 wants to merge 3 commits into
Open
feat(components): add Headroom MCP component for context compression#970RoX452 wants to merge 3 commits into
RoX452 wants to merge 3 commits into
Conversation
Add Headroom (headroomlabs-ai/headroom) as an optional MCP component that compresses LLM context via three tools: compress, retrieve, and stats. Key changes: - New ComponentHeadroom type and catalog entry - Generalized mcp.Inject() with componentID parameter - 7 agent overlay variants (Claude, OpenCode, OpenClaw, VS Code, Antigravity, Kimi, Codex) - Pip auto-install: detects headroom binary, falls back to pip install - Uninstall support: MCP config cleanup across all strategies - 18 inject tests + 8 headroom shape tests - Pinned version 0.27.0 with Renovate directives
📝 WalkthroughWalkthroughAdds a new ChangesHeadroom component support
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Suggested labels
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Document Headroom in the components reference and update preset descriptions to reflect it is included in full-gentleman and ecosystem-only presets.
- New docs/headroom.md explaining what Headroom is, the problem it solves, how to install/use/uninstall, and how it compares to Engram - Updated docs/components.md with Headroom entry and preset descriptions
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@internal/cli/doctor.go`:
- Line 41: The doctor check is treating the optional Headroom binary like a
required tool because `knownTools` feeds `checkToolBinaries()` unconditionally
and `checkOneTool()` turns missing binaries into a failure. Update the logic
around `knownTools`, `checkToolBinaries()`, and `checkOneTool()` so `headroom`
is only checked when that component is selected/installed, or otherwise report
it as informational instead of failing `doctor`.
In `@internal/cli/run.go`:
- Around line 1317-1333: The Headroom path collection in the ComponentHeadroom
branch is missing the YAML-backed config write used by StrategyMergeIntoYAML, so
install/sync bookkeeping does not include the actual user config file. Update
the adapter.MCPStrategy() handling in this section to also append the YAML
config path for Headroom when the adapter uses StrategyMergeIntoYAML, alongside
the existing StrategyMergeIntoSettings, StrategyMCPConfigFile, and
StrategyTOMLFile cases, so backup/restore tracking covers ~/.hermes/config.yaml.
In `@internal/components/mcp/inject_test.go`:
- Around line 684-710: Add second-run idempotency checks for the new Headroom
config paths in TestInjectCodexHeadroomTOML and
TestInjectHermesHeadroomIntoYAML. After the initial Inject call that uses
codex.NewAdapter()/hermes adapter and model.ComponentHeadroom, run Inject again
on the same home directory and assert Changed is false and the resulting config
content stays identical. This should validate the TOML/YAML upsert helpers do
not duplicate the [mcp_servers.headroom] or equivalent Headroom block.
In `@internal/components/uninstall/service.go`:
- Around line 718-754: The uninstall flow in headroomOperations/headroomTargets
only removes JSON MCP wiring, but headroom is also injected into TOML and YAML
configs by the MCP injector. Update headroomOperations to handle the same
adapter strategies for those config formats and remove the headroom server entry
from the appropriate TOML/YAML target paths, using the existing
adapter.MCPStrategy(), adapter.MCPConfigPath(), and adapter.SettingsPath()
patterns so Codex/Hermes-style adapters clean up all headroom config on
uninstall.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: f98706e6-84ec-41ab-a672-c7ae6ef5838b
⛔ Files ignored due to path filters (6)
openspec/changes/archive/2026-06-27-headroom-mcp-component/archive-report.mdis excluded by!openspec/**openspec/changes/archive/2026-06-27-headroom-mcp-component/design.mdis excluded by!openspec/**openspec/changes/archive/2026-06-27-headroom-mcp-component/proposal.mdis excluded by!openspec/**openspec/changes/archive/2026-06-27-headroom-mcp-component/specs/headroom-mcp/spec.mdis excluded by!openspec/**openspec/changes/archive/2026-06-27-headroom-mcp-component/tasks.mdis excluded by!openspec/**openspec/specs/headroom-mcp/spec.mdis excluded by!openspec/**
📒 Files selected for processing (15)
internal/catalog/components.gointernal/cli/doctor.gointernal/cli/install_test.gointernal/cli/run.gointernal/cli/sync.gointernal/cli/validate.gointernal/components/mcp/headroom.gointernal/components/mcp/headroom_test.gointernal/components/mcp/inject.gointernal/components/mcp/inject_test.gointernal/components/uninstall/service.gointernal/model/types.gointernal/planner/graph.gointernal/tui/model.gointernal/versions/versions.go
| } | ||
|
|
||
| var knownTools = []string{"gentle-ai", "engram", "gga", "claude", "opencode"} | ||
| var knownTools = []string{"gentle-ai", "engram", "gga", "claude", "opencode", "headroom"} |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Don't fail doctor for an optional tool.
checkToolBinaries() iterates every knownTools entry unconditionally, and checkOneTool() marks a missing binary as fail. Adding headroom here means doctor will now report a failing installation for users who never enabled the optional Headroom component. Gate this check on selected/installed components, or downgrade it to a non-failing informational check.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@internal/cli/doctor.go` at line 41, The doctor check is treating the optional
Headroom binary like a required tool because `knownTools` feeds
`checkToolBinaries()` unconditionally and `checkOneTool()` turns missing
binaries into a failure. Update the logic around `knownTools`,
`checkToolBinaries()`, and `checkOneTool()` so `headroom` is only checked when
that component is selected/installed, or otherwise report it as informational
instead of failing `doctor`.
Comment on lines
+1317
to
+1333
| 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) | ||
| } | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Track the YAML strategy file for Headroom too.
Hermes uses StrategyMergeIntoYAML, and the new Headroom injector writes ~/.hermes/config.yaml. This path list skips that strategy, so install/sync bookkeeping misses the actual user config write. That leaves the change outside the backup/restore set. As per path instructions, internal/components/**/*.go: "Any write to user config must have a backup/restore path."
💡 Suggested fix
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.StrategyMergeIntoYAML:
+ if p := adapter.MCPConfigPath(homeDir, "headroom"); p != "" {
+ paths = append(paths, p)
+ }
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 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.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.StrategyMergeIntoYAML: | |
| if p := adapter.MCPConfigPath(homeDir, "headroom"); p != "" { | |
| paths = append(paths, p) | |
| } | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@internal/cli/run.go` around lines 1317 - 1333, The Headroom path collection
in the ComponentHeadroom branch is missing the YAML-backed config write used by
StrategyMergeIntoYAML, so install/sync bookkeeping does not include the actual
user config file. Update the adapter.MCPStrategy() handling in this section to
also append the YAML config path for Headroom when the adapter uses
StrategyMergeIntoYAML, alongside the existing StrategyMergeIntoSettings,
StrategyMCPConfigFile, and StrategyTOMLFile cases, so backup/restore tracking
covers ~/.hermes/config.yaml.
Source: Path instructions
Comment on lines
+684
to
+710
| // TestInjectCodexHeadroomTOML verifies that Headroom injection for Codex | ||
| // creates config.toml with [mcp_servers.headroom] block using local command. | ||
| func TestInjectCodexHeadroomTOML(t *testing.T) { | ||
| home := t.TempDir() | ||
|
|
||
| result, err := Inject(home, codex.NewAdapter(), model.ComponentHeadroom) | ||
| if err != nil { | ||
| t.Fatalf("Inject(codex,headroom) error = %v", err) | ||
| } | ||
| if !result.Changed { | ||
| t.Fatal("Inject(codex,headroom) first call changed = false; want true") | ||
| } | ||
|
|
||
| configTOML := filepath.Join(home, ".codex", "config.toml") | ||
| content, err := os.ReadFile(configTOML) | ||
| if err != nil { | ||
| t.Fatalf("ReadFile(config.toml) error = %v", err) | ||
| } | ||
| text := string(content) | ||
|
|
||
| if !strings.Contains(text, "[mcp_servers.headroom]") { | ||
| t.Fatalf("config.toml missing [mcp_servers.headroom]; got:\n%s", text) | ||
| } | ||
| if !strings.Contains(text, `command = "headroom"`) { | ||
| t.Fatalf("config.toml missing headroom command; got:\n%s", text) | ||
| } | ||
| } |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Add second-run assertions for the new Headroom TOML/YAML paths.
TestInjectCodexHeadroomTOML and TestInjectHermesHeadroomIntoYAML only check the first write. Those branches exercise different upsert helpers than the JSON-based Headroom injectors, so a duplicate-block regression would still pass this suite. As per path instructions, internal/components/**/*.go: "Install/sync operations must be idempotent (running twice equals running once)."
Also applies to: 1174-1206
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@internal/components/mcp/inject_test.go` around lines 684 - 710, Add
second-run idempotency checks for the new Headroom config paths in
TestInjectCodexHeadroomTOML and TestInjectHermesHeadroomIntoYAML. After the
initial Inject call that uses codex.NewAdapter()/hermes adapter and
model.ComponentHeadroom, run Inject again on the same home directory and assert
Changed is false and the resulting config content stays identical. This should
validate the TOML/YAML upsert helpers do not duplicate the
[mcp_servers.headroom] or equivalent Headroom block.
Source: Path instructions
Comment on lines
+718
to
+754
| func headroomTargets(adapter agents.Adapter, homeDir string) []string { | ||
| switch adapter.MCPStrategy() { | ||
| case model.StrategySeparateMCPFiles: | ||
| return []string{adapter.MCPConfigPath(homeDir, "headroom")} | ||
| case model.StrategyMergeIntoSettings, model.StrategyMCPConfigFile: | ||
| return []string{adapter.MCPConfigPath(homeDir, "headroom")} | ||
| default: | ||
| return nil | ||
| } | ||
| } | ||
|
|
||
| func headroomOperations(adapter agents.Adapter, homeDir string) []operation { | ||
| switch adapter.MCPStrategy() { | ||
| case model.StrategySeparateMCPFiles: | ||
| path := adapter.MCPConfigPath(homeDir, "headroom") | ||
| return []operation{removeFile(path), removeDirIfEmpty(filepath.Dir(path))} | ||
| case model.StrategyMergeIntoSettings: | ||
| path := adapter.SettingsPath(homeDir) | ||
| if adapter.Agent() == model.AgentOpenCode { | ||
| return []operation{rewriteJSONFile(path, jsonPath{"mcp", "headroom"})} | ||
| } | ||
| return []operation{rewriteJSONFile(path, jsonPath{"mcpServers", "headroom"})} | ||
| case model.StrategyMCPConfigFile: | ||
| path := adapter.MCPConfigPath(homeDir, "headroom") | ||
| switch adapter.Agent() { | ||
| case model.AgentVSCodeCopilot: | ||
| return []operation{rewriteJSONFile(path, jsonPath{"servers", "headroom"})} | ||
| case model.AgentAntigravity: | ||
| return []operation{rewriteJSONFile(path, jsonPath{"mcpServers", "headroom"})} | ||
| default: | ||
| return []operation{rewriteJSONFile(path, jsonPath{"mcpServers", "headroom"})} | ||
| } | ||
| default: | ||
| return nil | ||
| } | ||
| } | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Handle TOML and YAML Headroom configs on uninstall.
headroomOperations only removes JSON-based MCP wiring, but the installer adds headroom to TOML and YAML configs too (internal/components/mcp/inject.go:20-45 and internal/components/mcp/inject.go:55-110). On Codex/Hermes-style adapters, uninstall will leave the headroom server configured in user settings.
Suggested direction
func headroomTargets(adapter agents.Adapter, homeDir string) []string {
switch adapter.MCPStrategy() {
case model.StrategySeparateMCPFiles:
return []string{adapter.MCPConfigPath(homeDir, "headroom")}
case model.StrategyMergeIntoSettings, model.StrategyMCPConfigFile:
return []string{adapter.MCPConfigPath(homeDir, "headroom")}
+ case model.StrategyTOMLFile, model.StrategyMergeIntoYAML:
+ return []string{adapter.MCPConfigPath(homeDir, "headroom")}
default:
return nil
}
}
func headroomOperations(adapter agents.Adapter, homeDir string) []operation {
switch adapter.MCPStrategy() {
case model.StrategySeparateMCPFiles:
path := adapter.MCPConfigPath(homeDir, "headroom")
return []operation{removeFile(path), removeDirIfEmpty(filepath.Dir(path))}
case model.StrategyMergeIntoSettings:
path := adapter.SettingsPath(homeDir)
if adapter.Agent() == model.AgentOpenCode {
return []operation{rewriteJSONFile(path, jsonPath{"mcp", "headroom"})}
}
return []operation{rewriteJSONFile(path, jsonPath{"mcpServers", "headroom"})}
case model.StrategyMCPConfigFile:
path := adapter.MCPConfigPath(homeDir, "headroom")
switch adapter.Agent() {
case model.AgentVSCodeCopilot:
return []operation{rewriteJSONFile(path, jsonPath{"servers", "headroom"})}
case model.AgentAntigravity:
return []operation{rewriteJSONFile(path, jsonPath{"mcpServers", "headroom"})}
default:
return []operation{rewriteJSONFile(path, jsonPath{"mcpServers", "headroom"})}
}
+ case model.StrategyTOMLFile:
+ path := adapter.MCPConfigPath(homeDir, "headroom")
+ return []operation{rewriteTOMLFile(path, /* remove headroom block */)}
+ case model.StrategyMergeIntoYAML:
+ path := adapter.MCPConfigPath(homeDir, "headroom")
+ return []operation{rewriteYAMLFile(path, /* remove headroom block */)}
default:
return nil
}
}🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@internal/components/uninstall/service.go` around lines 718 - 754, The
uninstall flow in headroomOperations/headroomTargets only removes JSON MCP
wiring, but headroom is also injected into TOML and YAML configs by the MCP
injector. Update headroomOperations to handle the same adapter strategies for
those config formats and remove the headroom server entry from the appropriate
TOML/YAML target paths, using the existing adapter.MCPStrategy(),
adapter.MCPConfigPath(), and adapter.SettingsPath() patterns so
Codex/Hermes-style adapters clean up all headroom config on uninstall.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/components.md`:
- Line 15: The Headroom entry in the components table lists the wrong MCP tool
names, so update the description to match the actual symbols exposed by
Headroom: headroom_compress, headroom_retrieve, and headroom_stats. Keep the
rest of the Headroom summary intact, but replace the unprefixed tool list in the
docs/components.md table so users see the correct callable names consistent with
docs/headroom.md.
In `@docs/headroom.md`:
- Line 69: The VS Code Copilot entry in the headroom docs uses an incomplete
relative path for the MCP config, so update the documentation entry to show the
full platform-specific absolute path instead of Code/User/mcp.json. Adjust the
row in the table under the VS Code Copilot reference so it clearly points users
to the correct mcp.json location for macOS and Linux, using the same
servers.headroom reference.
- Line 73: Update the Antigravity MCP path reference in docs/headroom.md so it
points to the supported config root under
~/.gemini/antigravity-cli/mcp_config.json instead of the old
~/.gemini/antigravity/mcp_config.json value. Make this change in the Antigravity
row of the headroom table, keeping the rest of the documentation entry
unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 514b92c5-0c95-45cf-81dd-b95d703bc84b
📒 Files selected for processing (2)
docs/components.mddocs/headroom.md
| | 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) | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Clarify actual MCP tool names.
The description lists the tools as `compress`, `retrieve`, and `stats`, but the actual MCP tool names exposed by Headroom are headroom_compress, headroom_retrieve, and headroom_stats (as shown in docs/headroom.md). Users referencing this table may try to invoke unprefixed names that won't exist.
- | 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) |
+ | Headroom | `headroom` | MCP context compression server — compresses verbose tool outputs and LLM responses to stay within context window limits via three tools: `headroom_compress`, `headroom_retrieve`, and `headroom_stats`. Installed via pip (`headroom-ai[all]`). See [headroom docs](headroom.md) |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| | 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) | | |
| | Headroom | `headroom` | MCP context compression server — compresses verbose tool outputs and LLM responses to stay within context window limits via three tools: `headroom_compress`, `headroom_retrieve`, and `headroom_stats`. Installed via pip (`headroom-ai[all]`). See [headroom docs](headroom.md) | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/components.md` at line 15, The Headroom entry in the components table
lists the wrong MCP tool names, so update the description to match the actual
symbols exposed by Headroom: headroom_compress, headroom_retrieve, and
headroom_stats. Keep the rest of the Headroom summary intact, but replace the
unprefixed tool list in the docs/components.md table so users see the correct
callable names consistent with docs/headroom.md.
| | 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 | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Incomplete file path for VS Code Copilot.
Code/User/mcp.json is not a valid absolute path. Users won't know where to find this. Specify the full platform-dependent path (e.g., ~/Library/Application Support/Code/User/mcp.json on macOS, ~/.config/Code/User/mcp.json on Linux).
- | VS Code Copilot | `Code/User/mcp.json` `servers.headroom` | Merge |
+ | VS Code Copilot | `~/Library/Application Support/Code/User/mcp.json` `servers.headroom` | Merge |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/headroom.md` at line 69, The VS Code Copilot entry in the headroom docs
uses an incomplete relative path for the MCP config, so update the documentation
entry to show the full platform-specific absolute path instead of
Code/User/mcp.json. Adjust the row in the table under the VS Code Copilot
reference so it clearly points users to the correct mcp.json location for macOS
and Linux, using the same servers.headroom reference.
| | 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 | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify Antigravity's expected config path
rg -n "antigravity" --glob '*.go' | head -20Repository: Gentleman-Programming/gentle-ai
Length of output: 169
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '== Files mentioning antigravity =='
rg -n -i "antigravity" . || true
printf '\n%s\n' '== Files mentioning gemini and mcp_config =='
rg -n -i "gemini|mcp_config" docs . || true
printf '\n%s\n' '== docs/headroom.md context =='
cat -n docs/headroom.md | sed -n '60,85p'Repository: Gentleman-Programming/gentle-ai
Length of output: 50388
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo '== docs/headroom.md =='
cat -n docs/headroom.md | sed -n '68,78p'
echo
echo '== docs/platforms.md =='
cat -n docs/platforms.md | sed -n '38,52p'
echo
echo '== antigravity support spec =='
cat -n openspec/specs/antigravity-support/spec.md | sed -n '1,50p'
echo
echo '== headroom component design/task references =='
rg -n "antigravity|mcp_config.json|antigravity-cli" openspec/changes/archive/2026-06-27-headroom-mcp-component openspec/changes/antigravity-2.0-compatibility -g '*.md'Repository: Gentleman-Programming/gentle-ai
Length of output: 10737
Update Antigravity’s MCP path to ~/.gemini/antigravity-cli/mcp_config.json. docs/headroom.md:73 still points at ~/.gemini/antigravity/mcp_config.json, which doesn’t match the supported Antigravity config root.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/headroom.md` at line 73, Update the Antigravity MCP path reference in
docs/headroom.md so it points to the supported config root under
~/.gemini/antigravity-cli/mcp_config.json instead of the old
~/.gemini/antigravity/mcp_config.json value. Make this change in the Antigravity
row of the headroom table, keeping the rest of the documentation entry
unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add Headroom (headroomlabs-ai/headroom) as an optional MCP component that compresses LLM context via three tools: compress, retrieve, and stats.
Headroom is a local MCP server installed via pip (headroom-ai[all]). gentle-ai auto-detects the binary and falls back to pip install before injecting MCP config files across all supported agents.
Changes
Test Plan
Summary by CodeRabbit