Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
docs(mcp): using Ix behind headroom or another compressing proxy (HR-05) (#824)
Ian Hock1546c0d62ff6
diff --git a/docs-site/src/content/docs/integrations/mcp.md b/docs-site/src/content/docs/integrations/mcp.mdindex eef83525..a1b50b2d 100644--- a/docs-site/src/content/docs/integrations/mcp.md+++ b/docs-site/src/content/docs/integrations/mcp.md@@ -74,6 +74,39 @@ claude mcp remove ix-memoryix mcp install```+## Behind a compressing proxy++Some proxies shrink tool results before the model sees them. headroom (`headroom wrap claude`) is one: it compresses+every tool result except those on its exclude list, and Ix's tools are not on that list by default. Ix has already+ranked its answer and cut it to a budget, and it says so in the output (`truncated ...` records and the shown/total+counts). A second cut can drop rows Ix ranked high, and the agent loses the signal that something is missing.++Add the Ix tools to headroom's excluded tools:++```bash+HEADROOM_EXCLUDE_TOOLS='mcp__ix-memory__*' headroom wrap claude+```++`mcp__ix-memory__*` matches the names Claude Code gives the tools of the `ix-memory` server that `ix mcp install`+registers. If you registered Ix under another name, use that name. Set it as an environment variable:+`headroom wrap claude` has no flag for it and passes options it does not know on to `claude`, but it hands its+environment to the proxy it starts. The proxy reads the setting when it starts, so restart it after changing it.+Excluded results skip headroom's lossy compression, but it can still rewrite them without losing data: JSON is+minified, repeated log lines are collapsed and search hits are grouped under their path. In token mode, excluded+results far back in a long session can also be compressed; `HEADROOM_PROTECT_TOOL_RESULTS` turns that off, but it+also protects Read, Glob, Grep, Write and Edit results.++If the agent calls `ix` through the shell, prefer `--format llm`, or set it once with `IX_FORMAT=llm` or+`ix config set format llm` (see [output formats](/concepts/output-formats/)). Ix's core MCP tools already answer+in this format. JSON arrays are what headroom's array compressor cuts. This avoids that compressor only: headroom+does not exclude shell output by default, so its text compression can still shorten the result. To limit it to the+lossless rewrites, name the shell tool in the environment, `HEADROOM_PROTECT_TOOL_RESULTS=Bash`, which also protects+the tools above.++headroom's `--code-memory` (Serena, installed by default by `wrap`) and `--code-graph` (codebase-memory-mcp) are+separate tools. Ix runs alongside them, or instead of Serena with `--code-memory none`. headroom is a third-party+tool and this is not an official integration; these notes describe its behaviour as of its 976aa71 commit.+## Process isolationTool calls run inside the server process. Set `IX_MCP_SUBPROCESS=1` to run each call as a separate `ix` childdiff --git a/docs/mcp.md b/docs/mcp.mdindex 8c41aeb1..c0e4b117 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -75,6 +75,39 @@ Tool calls run inside the server process. Set `IX_MCP_SUBPROCESS=1` to run eachone as a separate `ix` child process instead — slower by roughly the CLI'sstartup time per call, but fully isolated.+## Behind a compressing proxy++Some proxies shrink tool results before the model sees them. headroom (`headroom wrap claude`) is one: it compresses+every tool result except those on its exclude list, and Ix's tools are not on that list by default. Ix has already+ranked its answer and cut it to a budget, and it says so in the output (`truncated ...` records and the shown/total+counts). A second cut can drop rows Ix ranked high, and the agent loses the signal that something is missing.++Add the Ix tools to headroom's excluded tools:++```bash+HEADROOM_EXCLUDE_TOOLS='mcp__ix-memory__*' headroom wrap claude+```++`mcp__ix-memory__*` matches the names Claude Code gives the tools of the `ix-memory` server that `ix mcp install`+registers. If you registered Ix under another name, use that name. Set it as an environment variable:+`headroom wrap claude` has no flag for it and passes options it does not know on to `claude`, but it hands its+environment to the proxy it starts. The proxy reads the setting when it starts, so restart it after changing it.+Excluded results skip headroom's lossy compression, but it can still rewrite them without losing data: JSON is+minified, repeated log lines are collapsed and search hits are grouped under their path. In token mode, excluded+results far back in a long session can also be compressed; `HEADROOM_PROTECT_TOOL_RESULTS` turns that off, but it+also protects Read, Glob, Grep, Write and Edit results.++If the agent calls `ix` through the shell, prefer `--format llm`, or set it once with `IX_FORMAT=llm` or+`ix config set format llm` (see [output formats](llm-format.md)). Ix's core MCP tools already answer+in this format. JSON arrays are what headroom's array compressor cuts. This avoids that compressor only: headroom+does not exclude shell output by default, so its text compression can still shorten the result. To limit it to the+lossless rewrites, name the shell tool in the environment, `HEADROOM_PROTECT_TOOL_RESULTS=Bash`, which also protects+the tools above.++headroom's `--code-memory` (Serena, installed by default by `wrap`) and `--code-graph` (codebase-memory-mcp) are+separate tools. Ix runs alongside them, or instead of Serena with `--code-memory none`. headroom is a third-party+tool and this is not an official integration; these notes describe its behaviour as of its 976aa71 commit.+## See also- [Consolidating the per-host plugins onto `ix mcp`](mcp-plugin-consolidation.md)