Add OpenCode integration and adoption plan

2026-06-10 20:35:15 +02:00 · 2026-06-08 13:12:06 -05:00 · 2026-06-08 13:12:06 -05:00 · 575d02a6f5
commit 575d02a6f5
parent 6324bb7a24
20 changed files with 508 additions and 25 deletions
--- a/docs/integrations/opencode.md
+++ b/docs/integrations/opencode.md
@ -0,0 +1,217 @@
+# OpenCode
+
+> Give OpenCode persistent local memory across TUI, CLI, and desktop sessions.
+
+OpenCode supports local MCP servers through its `mcp` config. Add Vestige once and your OpenCode agents can remember project decisions, architecture context, preferences, and previous fixes between sessions.
+
+Verified with OpenCode `1.16.2` on June 8, 2026.
+
+---
+
+## Setup
+
+### 1. Install Vestige
+
+```bash
+npm install -g vestige-mcp-server@latest
+```
+
+Verify the binary:
+
+```bash
+vestige-mcp --version
+```
+
+If you prefer not to install globally, use `npx` directly in the OpenCode command array:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["npx", "-y", "-p", "vestige-mcp-server@latest", "vestige-mcp"],
+      "enabled": true,
+      "timeout": 60000
+    }
+  }
+}
+```
+
+The higher timeout is for the first cold `npx` run, which may need to download the npm package before OpenCode can connect. If you install `vestige-mcp-server` globally, `10000` is enough for normal startup.
+
+If `npx` times out against an older published Vestige build, install globally once and use `command: ["vestige-mcp"]`. The current integration keeps the MCP handshake fast by moving embedding startup work into the background.
+
+### 2. Add Vestige To OpenCode
+
+For global use across projects, create or edit:
+
+```bash
+mkdir -p ~/.config/opencode
+${EDITOR:-vi} ~/.config/opencode/opencode.json
+```
+
+Add:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["vestige-mcp"],
+      "enabled": true,
+      "timeout": 10000
+    }
+  }
+}
+```
+
+OpenCode also supports project-local config. Put the same block in `opencode.json` at the repo root when you want the setting checked in with a project.
+
+For a custom config file, set `OPENCODE_CONFIG=/path/to/opencode.json` before launching OpenCode.
+
+### 3. Verify
+
+Restart OpenCode, then validate the resolved config and MCP server list:
+
+```bash
+opencode debug config
+opencode mcp list
+```
+
+You should see `vestige` listed. In a session, ask:
+
+> "What MCP tools can you use?"
+
+Vestige tools should be available with the `vestige_` prefix, such as `vestige_search`, `vestige_smart_ingest`, `vestige_session_context`, and `vestige_deep_reference`.
+
+---
+
+## First Use
+
+In OpenCode:
+
+> "Remember that this project uses Rust with Axum and SQLite."
+
+Start a new OpenCode session, then ask:
+
+> "What stack does this project use?"
+
+It remembers.
+
+---
+
+## Project-Specific Memory
+
+To isolate memory per repo, add `--data-dir` to OpenCode's command array:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["vestige-mcp", "--data-dir", "./.vestige"],
+      "enabled": true,
+      "timeout": 10000
+    }
+  }
+}
+```
+
+For an absolute path:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["/usr/local/bin/vestige-mcp", "--data-dir", "/Users/you/projects/my-app/.vestige"],
+      "enabled": true,
+      "timeout": 10000
+    }
+  }
+}
+```
+
+---
+
+## Automatic Setup
+
+If `opencode` is installed or `~/.config/opencode` exists, Vestige's installer can add the global config automatically:
+
+```bash
+npx @vestige/init
+```
+
+The installer writes a backup before modifying an existing config file. It also migrates Vestige entries copied from older `mcpServers` examples into OpenCode's current `mcp.vestige` shape.
+
+---
+
+## Troubleshooting
+
+<details>
+<summary>Vestige tools do not appear</summary>
+
+1. Verify OpenCode can see configured MCP servers:
+   ```bash
+   opencode debug config
+   opencode mcp list
+   ```
+2. Verify the binary is on your path:
+   ```bash
+   which vestige-mcp
+   ```
+3. Use an absolute binary path if OpenCode cannot resolve `vestige-mcp`.
+4. Restart OpenCode after changing `opencode.json`.
+5. Keep `timeout` at `10000` or higher for installed binaries. If you use the direct `npx` command, use `60000` so the first cold npm download does not fail OpenCode startup.
+</details>
+
+<details>
+<summary>Config does not validate</summary>
+
+OpenCode uses the top-level `mcp` key. Do not use the `mcpServers` shape from Claude Desktop, Cursor, or Windsurf.
+
+If you copied an older Vestige example that used `mcpServers`, rerun:
+
+```bash
+npx @vestige/init
+```
+
+Correct:
+
+```json
+{
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["vestige-mcp"],
+      "timeout": 10000
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Too many MCP tools in context</summary>
+
+OpenCode loads MCP tools alongside built-in tools. If you have many MCP servers enabled, disable unused servers or restrict MCP tools per agent in your OpenCode config.
+</details>
+
+---
+
+## Also Works With
+
+| IDE | Guide |
+|-----|-------|
+| Codex | [Setup](./codex.md) |
+| Cursor | [Setup](./cursor.md) |
+| VS Code (Copilot) | [Setup](./vscode.md) |
+| JetBrains | [Setup](./jetbrains.md) |
+| Windsurf | [Setup](./windsurf.md) |
+| Xcode 26.3 | [Setup](./xcode.md) |
+| Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
+| Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |