Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.md
index 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-memory
ix 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 isolation
Tool calls run inside the server process. Set `IX_MCP_SUBPROCESS=1` to run each call as a separate `ix` child
diff --git a/docs/mcp.md b/docs/mcp.md
index 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 each
one as a separate `ix` child process instead — slower by roughly the CLI's
startup 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)