OpenCode

OpenCode loads context-mode as a native TypeScript plugin rather than JSON stdin/stdout hooks. The plugin keeps the bulk of raw payload bytes out of your window by routing data-heavy output into the sandbox and answering from the FTS5 knowledge base.

OpenCode exposes no real SessionStart hook, so context-mode uses two surrogates. The experimental.chat.system.transform stage stands in for SessionStart and restores session memory across sessions, while the chat.message stage stands in for user-prompt capture so each request is recorded for later search.

Install

OpenCode has no plugin marketplace, so install the package globally first, then point the host config at it.

node --version

npm install -g context-mode

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["context-mode"]
}

Configure

The native plugin already exposes the ctx_* tools in-process and sets CONTEXT_MODE_EMBEDDED_PLUGIN_TOOLS=1 for itself, so the plugin-only config above needs no extra environment variable. If you ever run the standalone MCP server alongside the plugin (for example, a leftover mcp.context-mode entry), set this variable where the spawned server can read it — an env block in the opencode.json MCP entry, not a transient shell export — so the duplicate copy of each tool is suppressed:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["context-mode"],
  "mcp": {
    "context-mode": {
      "type": "local",
      "command": ["context-mode"],
      "env": { "CONTEXT_MODE_EMBEDDED_PLUGIN_TOOLS": "1" }
    }
  }
}

For the normal plugin-only install, prefer removing the mcp entry entirely (run context-mode upgrade) over running both. See /docs/configuration for the full list of environment variables, storage paths, and permission rules.

Verify

Confirm the install with the doctor. It checks language runtimes, the FTS5 knowledge base, and plugin registration, then reports anything that needs attention.

context-mode doctor

A clean run means the plugin is loaded and context-mode is ready to route your next data-heavy command. In the OpenCode session you can also type ctx stats to your agent to confirm the tools respond.

Related