{"slug": "settings-up-headroom-ai-with-opencode", "title": "Settings up headroom ai with opencode", "summary": "A developer published a guide for integrating headroom-ai with OpenCode for context compression and proxy routing, including fixes for absolute path resolution and dynamic chunk binding. The guide warns that OpenCode's Bun module resolver does not expand the ~ symbol, requiring full absolute paths in configuration.", "body_md": "A refined, battle-tested guide to successfully integrating `headroom-ai`\n\nwith `opencode`\n\nfor context compression and proxy routing, incorporating fixes for absolute path resolution and dynamic chunk binding.\n\nEnsure you have `headroom`\n\ninstalled locally and note its absolute path:\n\n```\nwhich headroom\n# Example output: /Users/username/.local/bin/headroom\n```\n\nNavigate to your OpenCode configuration directory and install `headroom-ai`\n\nand the required plugin package:\n\n```\ncd ~/.config/opencode\nnpm install headroom-ai\nnpm install @opencode-ai/plugin@latest\n```\n\nSince pre-compiled chunks must match the build hash, clone the repository and build the plugin from source:\n\n```\nrm -rf /tmp/headroom-build && mkdir -p /tmp/headroom-build\ncd /tmp/headroom-build\ngit clone --filter=blob:none --sparse --depth=1 https://github.com/headroomlabs-ai/headroom.git .\ngit sparse-checkout set plugins/opencode\ncd plugins/opencode\nnpm install\nnpm run build\n```\n\nCreate the target directory structure and move the built distribution files:\n\n```\nPLUGIN=~/.config/opencode/plugins/headroom-opencode\nSRC=/tmp/headroom-build/plugins/opencode\n\nrm -rf \"$PLUGIN\" && mkdir -p \"$PLUGIN/hook-shim\"\ncp \"$SRC/package.json\" \"$PLUGIN/\"\ncp -R \"$SRC/dist\" \"$PLUGIN/dist\"\ncp \"$SRC/hook-shim/handler.js\" \"$PLUGIN/hook-shim/\"\n```\n\nCreate or verify a `package.json`\n\nin both the plugin root and the hook-shim folder to enforce ESM (`\"type\": \"module\"`\n\n):\n\n```\n# Plugin root package.json\ncat > \"$PLUGIN/package.json\" <<'EOF'\n{ \"private\": true, \"type\": \"module\" }\nEOF\n\n# Hook-shim package.json\ncat > \"$PLUGIN/hook-shim/package.json\" <<'EOF'\n{ \"private\": true, \"type\": \"module\" }\nEOF\n```\n\n*Crucial:* Hardcoding a generic chunk name will break child-process interception. Use this snippet to automatically detect your build's specific hashed chunk name and write it into `handler.js`\n\n:\n\n```\nCHUNK=$(ls \"$PLUGIN/dist/chunk-\"*.js | head -1 | xargs basename)\ncat > \"$PLUGIN/hook-shim/handler.js\" <<EOF\nimport { installHeadroomTransport } from \"../dist/$CHUNK\";\n\nconst proxyUrl = process.env.HEADROOM_OPENCODE_TRANSPORT_PROXY_URL;\nif (proxyUrl) {\n  installHeadroomTransport({ proxyUrl });\n}\nEOF\n```\n\n**Warning:** OpenCode uses Bun's module resolver, which **never expands the ~ symbol**. Using\n\n`~/.config/...`\n\nwill cause the plugin to be silently skipped. Always use full **absolute paths**:\n\n```\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"plugin\": [\n    \"/Users/YOUR_USERNAME/.config/opencode/plugins/headroom-opencode/dist/entry.opencode.js\"\n  ],\n  \"mcp\": {\n    \"headroom\": {\n      \"type\": \"local\",\n      \"command\": [\n        \"/Users/YOUR_USERNAME/.local/bin/headroom\",\n        \"mcp\",\n        \"serve\"\n      ],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n*(Replace /Users/YOUR_USERNAME/ with your actual home directory path).*\n\n- Start the Headroom proxy daemon in a separate terminal tab or background process:\n\n```\nheadroom proxy &\n```\n\n- Launch OpenCode:\n\n```\nopencode\n```\n\n- Verify the proxy connection using the test script:\nA\n\n``` js\nnode --input-type=module -e \"try { const res = await fetch('http://localhost:8787/v1/retrieve/000000000000000000000000', { signal: AbortSignal.timeout(2000) }); console.log(res.status, await res.text()); } catch (err) { console.error(err); process.exit(1); }\"\n```\n\n`404 Entry not found`\n\nresponse confirms the proxy is fully up and routing correctly.", "url": "https://wpnews.pro/news/settings-up-headroom-ai-with-opencode", "canonical_source": "https://gist.github.com/gciluffo/12cd5f5015053a52d9cef6c8b9457b58", "published_at": "2026-07-25 14:49:21+00:00", "updated_at": "2026-07-27 07:29:24.578634+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-infrastructure"], "entities": ["headroom-ai", "OpenCode", "Bun", "headroomlabs-ai"], "alternates": {"html": "https://wpnews.pro/news/settings-up-headroom-ai-with-opencode", "markdown": "https://wpnews.pro/news/settings-up-headroom-ai-with-opencode.md", "text": "https://wpnews.pro/news/settings-up-headroom-ai-with-opencode.txt", "jsonld": "https://wpnews.pro/news/settings-up-headroom-ai-with-opencode.jsonld"}}