← All guidance

Optional tools

Optional user- and system-level tools that affect a person's machine rather than a governed repository. Skills, MCP servers, and day-to-day sessions can benefit from them, but none is required merely to read or audit the harness. Install and get started explains ki bootstrap, explicit skill activation, and when optional user-environment setup is appropriate.

chezmoi (dotfile and machine-config management)

chezmoi manages the dotfiles and machine-level config this guide references — the per-repo CLAUDE.md imports, the headroom-ai and mcporter LaunchAgent plists, and the harness-mode notes chezmoi templates into CLAUDE.md. Machine-specific state (which headroom-ai mode is active, OAuth client secrets resolved from 1Password) is chezmoi-templated rather than hand-edited, so chezmoi diff / chezmoi apply is the way to pick up drift rather than editing the rendered files directly.

brew install chezmoi
chezmoi init <your-dotfiles-repo>
chezmoi apply

Quick reference: re-add a Claude Desktop configuration

Use this only to bring an app-edited configuration back into chezmoi source state. Quit Claude Desktop first. The KI-managed MCP server list belongs in its canonical source, not in the rendered Desktop file.

chezmoi re-add --dry-run "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
chezmoi re-add "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
chezmoi diff
chezmoi apply -v

re-add preserves an existing chezmoi template; review chezmoi diff before applying. Use this path for settings outside the template-owned MCP server block.

headroom-ai

headroom-ai provides context compaction management (PreCompact hook) and shell-output compression via its bundled RTK component.

brew install headroom-ai

headroom-ai runs in one of two modes:

• Proxy mode — headroom proxy starts a local proxy on port 8787; Claude Code is pointed at it via ANTHROPIC_BASE_URL=http://127.0.0.1:8787.
• Wrap mode — headroom claude wraps the Claude CLI directly without a separate proxy process.

The harness CLAUDE.md notes which mode is active in the current machine's chezmoi config.

Coverage by runtime

Headroom is not a machine-wide or generic desktop-application proxy.

Treat an agent as covered only when its model requests appear in Headroom's proxy statistics or logs.

An installed Headroom MCP server, a running local proxy, or a healthy /health response does not establish model-traffic coverage.

Claude Code is the supported, measured path: ANTHROPIC_BASE_URL or the Headroom wrapper points its CLI at the local proxy.

Claude Desktop's subscription-backed traffic is not routed by the CLI integration.

Its MCP configuration is separate and does not proxy chat traffic.

The formerly managed ChatGPT/Codex proxy route is intentionally disabled until a supported path proves reliable telemetry and meaningful savings.

Verify every other client separately; coverage never carries over from another runtime.

Check a claimed route with headroom perf --hours 1 --format json or the local /stats endpoint, and confirm the relevant client appears in the result before relying on it for token savings.

Codex skill discovery and experiments

The skills command-line tool can install third-party skills into a user's Codex skill directory. These are personal, user-scope additions: they do not become part of a governed repository or alter its declared KI skill set. Review a skill's source and behaviour before adding it, especially if it installs hooks or changes agent instructions.

Caveman in Codex

Caveman is an optional agent-local response-compression skill, not a model-traffic proxy or a KI harness dependency.

Use it as a narrow Codex trial first:

npx skills add JuliusBrussee/caveman -a codex

Start a new Codex session after installation, then activate it explicitly with /caveman lite for ordinary work.

Use /caveman full only when terse output remains clear for the task.

Use normal mode or stop caveman to return to normal output.

The documented integration is Codex CLI.

For ChatGPT or Codex Desktop, treat availability in a fresh session as an acceptance test rather than assuming the installed Codex skill transfers to that surface.

Keep Headroom as the only request proxy.

Caveman does not route model requests through Headroom, and it cannot make ChatGPT or Codex Desktop traffic appear in Headroom's coverage.

Continue to prove a Headroom route with its proxy statistics or logs as described in Coverage by runtime.

Do not add a Caveman-to-Headroom proxy chain, caveman-shrink, Cavemem, or Caveman Code as part of this trial.

No chezmoi change is required for an individual trial.

If the skill proves useful enough to standardise across machines, add a narrow, reviewable chezmoi profile with an explicit version, target runtime, and removal path; do not capture generated Codex state or install it for every runtime.

To add the find-skills discovery skill:

npx skills add vercel-labs/skills@find-skills

Start a new Codex turn after installation so the newly installed skills are available for selection.

Future tooling under observation

These are research leads, not harness dependencies or recommendations. Nothing below has been assessed by this site, and a link here is a record of where an evaluation could start — not evidence that a project is secure, active, maintained, compatible, or suitable for Knowledge Islands use.

What to establish before adopting any of them

The same five questions decide every candidate, and they are worth asking in this order because each one can end the evaluation:

1. Supply-chain provenance. Who publishes it, from where, and is a release pinned to something immutable? A tool that installs from a moving branch into your agent's path is a standing risk regardless of how good it is.
2. Permission model. What can it read, and what can it send? Anything sitting between an agent and a model sees every prompt, including whatever was in context at the time.
3. Runtime fit. Does it work with the runtimes you actually use, or only with the one its author uses? Multi-runtime claims are common and often thin.
4. Maintenance. Is there evidence of sustained upkeep rather than a strong first release? Agent tooling moves fast enough that a six-month gap is usually terminal.
5. Claimed effects, measured. Token and cost claims are the reason most of these exist and the least often verified. Measure in a contained evaluation against your own traffic; vendor benchmarks rarely transfer.

The Headroom coverage table above is the worked example of why the last one matters: an installed tool, a running proxy and a healthy endpoint together establish nothing about whether your model traffic is actually routed through it.

Model routing and identity

The problem is sending different requests to different models — cheap ones for mechanical work, capable ones for reasoning — without rewriting how each agent is configured. The risk is that a router becomes an undeclared dependency sitting in the credential path of every request.

Claude Code Router releases, routectl releases, 9router.

MCP aggregation and gateways

The problem is that each MCP server added to a runtime is another process, another entry in a configuration file, and another thing to keep alive. A gateway consolidates them behind one endpoint. This is the area where something is already adopted here — mcporter, below — so the watch is for whether a better consolidation appears, particularly around discovery.

MCPorter change log, AIRIS MCP Gateway.

Context compression

The problem is that long sessions fill a context window with material that has stopped earning its place, and the compaction a runtime does by itself is blunt. The risk is specific and worth naming: a compressor that silently drops or rewrites content changes what the agent believes, and a wrong answer produced from a lossily compressed context looks exactly like a wrong answer produced from a complete one.

RTK releases, Headroom releases, LeanCTX.

Harnesses and working methods

The problem is the one Knowledge Islands exists to solve, approached differently. These are other people's answers to how an agent should be given capability and discipline, and they are worth reading for their ideas whether or not anything is adopted. The evaluation question is not "is this good" but "does this contain a mechanism that would work better than ours" — which is a reading exercise, not an installation.

Superpowers, OpenClaw 2026.7.1, Pi releases, caveman releases, Odysseus, Omnigent, Claurst.

The watch sources above were last reviewed on 2026-07-20.

mcporter (MCP proxy daemon)

mcporter consolidates all KI-owned MCP servers behind a single keep-alive daemon and exposes them through a single HTTP MCP endpoint, reducing the ~/.claude.json mcpServers block from many stdio entries to one URL entry.

brew install steipete/tap/mcporter

Two LaunchAgents are deployed and activated by chezmoi:

mcporter's config lives at ~/.mcporter/mcporter.json (chezmoi-managed). It embeds full server definitions with "lifecycle": "keep-alive" for each server, resolved from the same mcp-servers-json chezmoi template that generates the Claude Desktop config.

After chezmoi apply loads the plists, activate them:

launchctl load ~/Library/LaunchAgents/sh.mcporter.daemon.plist
launchctl load ~/Library/LaunchAgents/sh.mcporter.http-bridge.plist

Tools are exposed as server__tool (double underscore). ~/.claude.json should contain only a single ki-mcporter URL entry under mcpServers:

"ki-mcporter": { "type": "url", "url": "http://localhost:3333/mcp" }

Verify with:

mcporter daemon status          # all servers idle/running
curl http://localhost:3333/mcp  # should return a valid MCP JSON response

Both mcporter's config add and Claude Code's own claude mcp add only accept http / sse / stdio transports — a server that speaks raw WebSocket only (no HTTP/SSE/stdio front end) cannot be registered through either, mcporter included. It is not a universal bridge between transports; confirm a candidate server's transport before assuming mcporter can front it.

claude.ai connectors — the managed alternative

For a third-party SaaS integration (GitHub, Linear, Slack, Notion, the Google and Microsoft suites, and the like) there are two ways to get its tools into a session, and a local MCP server is only one of them. The other is a claude.ai managed connector, authorised once in claude.ai connector settings. Given this setup, the managed route is often the lower-friction one: Anthropic handles the OAuth, so there is no local OAuth flow to complete, no keep-alive daemon or secrets on the machine, and it works on surfaces where an interactive OAuth flow cannot run (a non-interactive Claude Code session, for instance, cannot complete one — it can only use a connector that is already authorised). Managed-connector schemas load on the claude.ai web / Desktop surface, where you toggle them per-conversation in the compose-bar tools menu, rather than into the Claude Code local surface.

Which route to prefer, per integration:

† The KI-owned mcp-* servers (workspace MCPs with the annotation-driven access-level gate and audit logging) are always the local route — there is no managed equivalent.

Do not wire the same integration both ways on the same surface — that loads two copies of its tool schemas. ki-binding governs which surface runs which server from the single mcps.yaml source and audits that the surfaces agree; see Tuning for the leanness view of the same choice.

VS Code command-execution MCP servers — evaluate before installing

A recurring want on this surface: letting the agent trigger a VS Code command directly (e.g. "Developer: Reload Web Views" after a session /rename, since the extension does not refresh its own UI on rename). Community MCP servers exist that expose vscode.commands.executeCommand() as a callable tool — for example louisfghbvc/mcp-vscode-commands. Before adopting one, check two things: whether it ships a signed .vsix/verified publisher (unsigned third-party extensions granting arbitrary command execution over an unauthenticated local socket are a real trust boundary, not a formality), and which transport it speaks — Claude Code's claude mcp add and mcporter's config add both only accept http / sse / stdio, so a WebSocket-only server (as mcp-vscode-commands currently is) cannot be wired into either regardless of how it is packaged. No such server is currently adopted here; this is a note for the next time the want resurfaces, not a recommendation.