opencode-raven

Why Raven Raven delegates search and on-demand MCP retrieval to separate focused agents, then returns compact evidence to the calling session. Routes local search and filesystem discovery through lightweight raven_seek. Uses a separately configurable model for MCP-first online research, with built-in web fallbacks, through raven_mcp. Keeps optional on-demand MCP schemas out of the main model's tool list. Preconfigures Context7, Exa, and Grep.app endpoints. Tracks estimated main-session context avoided by delegation.

Install

Raven 2.3 supports OpenCode V2 (2.0.26+). OpenCode V1 (1.18.29+) remains supported in the same package—no separate plugin is needed.

OpenCode V2

In OpenCode’s Install plugin feature, enter opencode-raven.

Or install globally from the CLI:

opencode plugin add opencode-raven

Either way, OpenCode manages the plugin configuration and automatically loads Raven’s terminal companion—no separate terminal plugin install is needed.

For manual configuration, use the v2 plugins key in opencode.jsonc instead:

{
  "plugins": ["opencode-raven"]
}

OpenCode V1

Use the v1 plugin key in opencode.jsonc:

{
  "plugin": ["opencode-raven"]
}

Restart OpenCode, then run /raven to verify the loaded version, model, routing, MCP health, and estimated savings. A fresh install may ask for one additional restart after selecting its model.

OpenCode resolves the package from npm and caches it automatically.

Upgrading From OpenCode 1 To 2

Keep using opencode-raven; change its OpenCode config entry from plugin to plugins. Raven’s existing ~/.config/opencode/opencode-raven/raven-config.json is shared by both versions, including models, on-demand MCPs, routing settings, and stats. Quit and restart OpenCode after upgrading.

OpenCode 1 uses Raven’s server() entrypoint; OpenCode 2 uses setup() and automatically loads the terminal companion. The terminal companion displays /raven command results in a scrollable dialog (arrow keys, Page Up/Down, or mouse wheel; Esc to close) and delivers startup/update warnings as toasts, without sending a prompt to the model. The v2 server also exposes the typed opencode-raven/rpc command contract for other clients.

The v1 minimum is 1.18.29 because earlier versions cannot load the shared object entrypoint. See OpenCode’s plugin migration guide for the upstream lifecycle and config changes.

For local development, v1 can load file:///path/to/opencode-raven/index.ts; v2 requires the package directory, file:///path/to/opencode-raven.

First-Time Setup

On first start, Raven checks OpenCode’s connected provider catalog and automatically selects an available zero-cost, tool-capable model from the opencode provider for both Raven agents. Free-model availability is controlled by the provider and can change.

If a free model is found, Raven writes it to the config and asks you to restart OpenCode once to load it. After restarting, /raven shows it with (auto). Raven rechecks auto-selected models after startup and replaces one only when it is no longer available. A model you set manually is never replaced.

If no suitable free model is available, Raven shows a setup warning and leaves search routing inactive rather than silently using a paid model. Open OpenCode’s model picker to choose an available model, then run:

/raven seek model <provider/model>
/raven mcp model <provider/model>

Restart OpenCode afterward. You can retry free-model detection at any time with /raven seek model auto and /raven mcp model auto.

Example

In this run, Raven handled the search-heavy web research in a child session and returned only the compact findings, keeping roughly 71K tokens of estimated tool and search context from flooding the main session. Actual savings vary by task, model, and tool output.

How It Works

Raven works automatically. Ask OpenCode for what you need as usual. You do not need to mention Raven, run a command, or manually call a delegation tool.

1. Your agent attempts to use a routed search, fetch, shell-discovery, or MCP tool.
2. Raven blocks the noisy direct call and gives the agent the exact retry: raven_seek for local searches, or raven_mcp for web search, URL fetching, and global MCP tools.
3. The selected Raven agent creates a session attached directly to the root session or resumes one for a related follow-up.
4. Raven performs retrieval work and returns compact evidence to the calling agent, which retains analysis and judgment.

The main model receives Raven’s final answer instead of its raw tool output. Each result includes a Raven session ID that the main agent can pass back for a context-aware follow-up. Child sessions remain available in OpenCode’s session/subagent view for inspection.

Background Retrieval (OpenCode V2)

On V2, raven_seek and raven_mcp run in the background by default. The initial response contains a child-session handle, not the findings. The calling agent can continue independent work; Raven delivers compact findings or a failure notice to that same calling session when retrieval finishes, including when the caller is itself a child session.

raven_mcp(query="Find the current API documentation")
raven_mcp(query="Retrieve library examples", background=true)
raven_seek(query="Find the definition needed for my next step", background=false)

Use background: false when the next step depends on the answer. Do not poll, repeat a pending retrieval, or finalize conclusions that need its findings. Wait for the completion message before reusing its sessionId for a follow-up.

Background retrieval keeps Raven’s configured timeouts, permissions, continuation checks, and context estimates. Returning the handle ends the calling tool, not the child retrieval. To stop it, open the returned child session and interrupt it. Deleting the calling session also cancels its pending retrievals.

Results are delivered through V2’s durable synthetic inbox input, which can resume the calling agent and therefore cause another model turn. Undelivered results are retained in plugin storage and retried when that location’s plugin next loads. A plugin/service restart cancels running work; Raven reports the interruption instead of automatically replaying searches or potentially stateful MCP calls. V1 keeps its existing foreground behavior.

Raven manages its own background child sessions using the public plugin APIs. This does not add native Ctrl+B background support to Raven’s custom tools.

For direct search control, mention @Raven in any chat. This sends the request to the search agent, but it is optional and not required for automatic routing.

Under the hood, Raven registers two public delegation tools and one internal bridge:

Tool	Purpose
raven_seek	Creates or resumes a lightweight Raven Search session for local file search, discovery, and command-output inspection.
raven_mcp	Creates or resumes an MCP-first online research session using global or on-demand MCPs, built-in web fallbacks, and local retrieval tools when needed for context.
raven_mcp_bridge	Internal bridge used only by the Raven MCP agent.

On OpenCode V2, Raven auto-approves permission checks for the public raven_seek and raven_mcp delegation tools instead of prompting on every call. Inside either Raven agent, any permission check that would otherwise ask is automatically approved, including skill loading and MCP calls. Explicit deny rules still apply. These execution-time approvals do not add a blanket agent permission or change the main agent’s tool permissions, model request, or access restrictions on the internal MCP bridge.

For a related follow-up, the main agent can reuse the ID returned by the earlier call:

raven_mcp(query="Research the available options")
raven_mcp(query="Compare the first two in more detail", sessionId="ses_...")

Raven accepts a resumed session only when it belongs to the same root session tree and matching Raven agent. Do not pass session IDs between raven_seek and raven_mcp. Delegated sessions attach directly to the root so they remain visible in the main session’s child switcher even when delegation starts inside another child.

OpenCode’s built-in tools already exist; Raven routes selected calls instead of replacing those tools. Global MCPs also remain globally registered, so their schemas still enter the main session even when Raven routes their calls.

On-demand MCPs are different: Raven discovers and calls them internally, so their full schemas are not registered globally. Enabled servers are probed after startup to discover tools and health, then per-session connections are opened when Raven uses them. “On-demand” describes schema exposure and normal use, not the absence of a startup health probe.

On OpenCode V2, reopening the TUI triggers a fresh background health and tool-discovery check even if the shared service is still running. This runs once per workspace per TUI launch; returning from sessions or reactivating the plugin does not repeat it. Overlapping attachment checks share the same refresh. Use /raven mcp refresh [server_name] to retry manually without restarting the service.

Automatic and manual MCP refreshes use top-right notifications for progress and results, without opening a command dialog or a session tab.

Configuration

Raven creates its global configuration here:

~/.config/opencode/opencode-raven/raven-config.json

Manual edits require an OpenCode restart. Route and timeout commands apply immediately unless the command says otherwise.

Field	Fresh-install default	Description
raven_seek.model	Auto-detected free OpenCode model, otherwise unset	Search-agent model. Manual values are preserved.
raven_seek.autoSelectedModel	Managed by Raven	Tracks whether the Search model can be safely refreshed automatically.
raven_seek.reasoning_effort	low	Search-agent reasoning option.
raven_seek.instructions	""	Extra search-agent instructions.
raven_seek.routeTools	Search/fetch tools plus bash	Exact tools routed through Raven Search.
raven_seek.routeToolKeywords	[]	Case-insensitive routed tool-name substrings.
raven_seek.excludeAgents	[]	Agents allowed to bypass search routing.
raven_seek.excludeTools	[]	Exact tools never routed through Raven Search.
raven_seek.timeout	600	Search delegation timeout in seconds.
raven_mcp.model	Auto-detected free OpenCode model, otherwise unset	MCP-agent model. Manual values are preserved.
raven_mcp.autoSelectedModel	Managed by Raven	Tracks whether the MCP model can be safely refreshed automatically.
raven_mcp.reasoning_effort	low	MCP-agent reasoning option.
raven_mcp.instructions	""	Extra MCP-agent instructions.
raven_mcp.timeout	600	MCP delegation and fallback connection timeout in seconds.
raven_mcp.descriptionDetail	"full"	Full or minimized generated MCP guidance.
raven_mcp.onDemandMcpServers	Context7, Exa, Grep.app	Remote HTTP/SSE or local stdio MCP definitions.

Existing flat configuration is migrated automatically on startup without a version field. Shared model, reasoning effort, instructions, and timeout values seed both sections; routing and MCP fields move to their corresponding sections.

On-Demand MCPs

Fresh installs include:

MCP	Endpoint	Authentication
Context7	https://mcp.context7.com/mcp	Optional key for higher limits
Exa	https://mcp.exa.ai/mcp	Optional key for higher limits
Grep.app	https://mcp.grep.app	Public API

Provider access policies can change. /raven mcp shows the result of Raven’s current startup probe.

Merge changes into the existing raven_mcp.onDemandMcpServers object; replacing it removes omitted defaults. Header and environment values support {env:VARIABLE} placeholders.

Custom remote MCP or keyed endpoint:

{
  "raven_mcp": {
    "onDemandMcpServers": {
      "myDocs": {
        "type": "remote",
        "url": "https://example.com/mcp",
        "headers": { "Authorization": "Bearer {env:MY_DOCS_TOKEN}" }
      }
    }
  }
}

Custom local stdio MCP:

{
  "raven_mcp": {
    "onDemandMcpServers": {
      "myLocal": {
        "type": "local",
        "command": ["bunx", "some-mcp-server"],
        "environment": { "API_KEY": "{env:MY_LOCAL_KEY}" },
        "cwd": "C:\\path\\to\\workspace",
        "timeout": 60000
      }
    }
  }
}

Per-server timeout values are milliseconds. Local servers inherit the OpenCode process environment. Set enabled: false to keep an entry without probing or loading it.

Generated MCP metadata and main-model guidance live beside raven-config.json. Refresh them with /raven mcp refresh [server].

Interactive MCP manager (OpenCode V2)

Run /raven mcp or /raven-mcps to open Raven’s searchable MCP popup. Click a server, or select it with the arrow keys and Enter, to see its actions:

• Sign in through the browser, continue a pending sign-in, or sign out.
• Refresh the server’s connection and discovered tools.
• Enable or disable it immediately, saving the setting in Raven’s configuration.
• View server details and the last connection error.

The list includes disabled servers and shows connection/authentication status and discovered tool counts. Ready · on demand means discovery succeeded; it does not claim a permanent connection. Connected means Raven currently holds an open connection. Choose Refresh all servers to recheck enabled servers. Disabling closes cached connections and cancels pending sign-in without deleting saved credentials. Signing out asks for confirmation before clearing credentials.

The sign-in action opens the browser on the TUI’s machine and also displays the sign-in URL as a fallback. On a remote setup, the browser still needs access to the server’s loopback callback. Escape closes the manager; an explicit Back action returns from a server’s action menu to the server list.

This menu manages Raven’s on-demand servers only. OpenCode’s native /mcps menu and globally registered servers are unchanged. OpenCode V1 keeps the text-based /raven mcp status command.

OAuth sign-in

Remote on-demand MCPs support OAuth directly through Raven; they do not need to be registered as global OpenCode MCPs. For example, merge Basecamp into the existing raven_mcp.onDemandMcpServers configuration:

{
  "basecamp": {
    "enabled": true,
    "type": "remote",
    "url": "https://mcp.basecamp.com/mcp",
    "description": "Basecamp projects, to-dos, messages, and schedules."
  }
}

After loading the updated Raven configuration, run /raven mcp auth basecamp. Open the displayed URL in a browser and approve access. Raven waits up to five minutes for the loopback callback, exchanges the authorization code using PKCE, then refreshes tool discovery and shows a completion notification. Startup probes and agent calls never initiate an interactive sign-in; authentication failures show the sign-in command instead. An expired access token is refreshed by the MCP SDK when the server rejects it, if a valid refresh token is available.

OAuth is enabled by default for remote servers without an explicit Authorization header. Set "oauth": false to disable it. Servers without dynamic registration can use pre-registered client settings:

{
  "type": "remote",
  "url": "https://example.com/mcp",
  "oauth": {
    "clientId": "{env:MY_MCP_CLIENT_ID}",
    "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
    "scope": "read",
    "callbackPort": 19847
  }
}

All settings are optional. Public clients should omit clientSecret. clientMetadataUrl is also supported for servers accepting URL-based client IDs. For a pre-registered client, register http://127.0.0.1:19847/oauth/callback (or your configured port). Otherwise Raven picks a free port on first sign-in and reuses that port for subsequent sign-ins. The callback listener binds only to 127.0.0.1, validates a random state value, and closes on completion, cancellation, timeout, or plugin unload. OAuth endpoints must use HTTPS, except loopback servers. When OpenCode runs remotely, the browser must be able to reach its loopback callback, for example through port forwarding.

Credentials are stored separately under ~/.config/opencode/opencode-raven/oauth/, with per-endpoint/client isolation and atomic writes. Files use owner-only Unix permissions; on Windows they inherit the user’s directory ACLs. They contain unencrypted tokens and must be treated as secrets; they are not written to Raven’s configuration, generated guidance, or RPC output. Do not commit or share them. Raven’s OAuth sign-in is separate from OpenCode’s native /mcps sign-in.

Use /raven mcp logout basecamp to cancel a pending sign-in, clear the saved credentials, and close Raven’s cached connections. Logout does not revoke the provider’s grant; revoke it in the provider’s account settings if needed. Avoid configuring the same server globally and on-demand, which exposes duplicate tools.

Routing

Default routed tools are grep, glob, webfetch, fetch, websearch, and search-like bash commands. On OpenCode 2, Raven also recognizes the native shell tool; bash and shell are routing aliases, so existing routing settings continue to work. Exact excludeTools entries use the host’s actual tool name.

Local search tools route to raven_seek; webfetch, fetch, websearch, and recognized global MCP tools route to raven_mcp. Each route uses its target agent’s configured model and recovery instructions.

Raven MCP’s prompt and capability guidance require MCP-first retrieval: honor a suitable caller-named MCP; otherwise use Context7 for supported library/API documentation, Exa for web research, official-site discovery and page fetching (including documentation outside Context7 coverage), and Grep.app for public code examples. Exact URLs also use a suitable MCP fetch capability first. Built-in web tools remain available only as a reported fallback when no suitable MCP is available, retrieval fails, or evidence is insufficient. This is an agent instruction, not a runtime tool lock; local reads and searches for context or saved output are unaffected.

Global MCPs are automatically routed when their OpenCode tool names use the normal <server>_<tool> prefix. Use a keyword for suffix-style names:

/raven route keyword add exa

Route or unroute exact tools:

/raven route tool add linear_search_issues
/raven route tool remove bash

raven_seek.excludeTools leaves selected tools direct even if their MCP prefix is routed. raven_seek.excludeAgents bypasses routing for selected agents.

When bash is routed, Raven intercepts primary discovery commands such as rg, recursive grep, find -name, dir /s, and Get-ChildItem -Recurse, including common quoted shell wrappers. Bounded output filters such as command | grep ... remain direct.

For blocked shell calls, the error identifies the matching search command and its original command fragment, even when it occurs late in a longer job. The whole tool call is blocked before execution; Raven does not automatically split or run any part of it. Delegate only the lookup to raven_seek, with its working directory and desired facts. Keep image generation, builds, and other non-retrieval work in the main agent’s shell tool, preserving ordering, variable state, and exit-code dependencies when splitting mixed commands.

Commands

Command	Action
/raven	Show status, routing, MCP health, version, model, timeout, and stats.
/raven help	Show command help.
/raven route	Show and edit routed tools and keywords.
/raven mcp	Open the interactive MCP manager on V2; show text status on V1.
/raven-mcps	Open the interactive MCP manager on V2 (also available in the command palette).
/raven mcp auth <server>	Display a browser sign-in URL for a remote on-demand MCP.
/raven mcp logout <server>	Cancel sign-in, clear saved OAuth credentials, and close cached connections.
/raven mcp refresh [server]	Recheck MCP health and regenerate metadata.
`/raven mcp detail full	minimized`
/raven seek model <provider/model>|auto	Change or auto-detect the search model; restart afterward.
/raven seek effort <value>	Change search reasoning effort; restart afterward.
/raven seek timeout <seconds>	Change the search delegation timeout.
/raven mcp model <provider/model>|auto	Change or auto-detect the MCP model; restart afterward.
/raven mcp effort <value>	Change MCP reasoning effort; restart afterward.
/raven mcp timeout <seconds>	Change the MCP delegation timeout.
/raven stats	Show estimated context avoided.
/raven update	Check npm, clear Raven’s OpenCode package cache when needed, and show restart instructions.

Security And Privacy

Raven is optimized for autonomous retrieval:

• Raven Search has read, search, unrestricted shell, external-directory, and globally configured MCP access without normal permission prompts.
• Raven MCP has the same retrieval access as Raven Search, plus the internal on-demand MCP bridge. Its MCP-first instructions retain built-in web tools for fallback and local file access for research context; these instructions are not access restrictions.
• Both agents deny edit tools and nested delegation, but shell access is not a read-only sandbox and can modify the system. MCP tools may also modify external systems; V2 auto-approval trusts the Raven agents rather than enforcing read-only execution.
• Queries are sent to Raven’s configured model provider.
• Remote MCP requests are sent to their services; local MCP entries launch local commands and inherit environment values.
• Startup performs an npm update check and probes enabled on-demand MCPs.

Review Raven.md, RavenMcp.md, and your MCP commands before using Raven in sensitive environments.

Context Estimates

/raven stats reports delegated-session context and avoided on-demand MCP schema bytes. These are heuristic estimates based on OpenCode token metadata and serialized schemas, not billing measurements or guaranteed savings.

Troubleshooting

• First-time model warning: select a model in OpenCode’s model picker, run /raven seek model <provider/model> and /raven mcp model <provider/model>, then restart. Use auto as the model value to retry free-model detection.
• Search provider or quota failure: run /raven seek model <provider/model>, then restart OpenCode.
• MCP-agent provider or quota failure: run /raven mcp model <provider/model>, then restart OpenCode.
• MCP failure: run /raven mcp, then /raven mcp refresh <server> after correcting its URL, command, environment, or credentials.
• OAuth required or expired: run /raven mcp auth <server> and approve access in the browser. If its callback port is busy, configure a free oauth.callbackPort. Use /raven mcp logout <server> to clear credentials and cancel an unfinished sign-in.
• Stale plugin version: run /raven update, restart OpenCode, and follow the cache-clearing instructions it prints if needed.
• Remove Raven: delete "opencode-raven" from plugin, restart, then optionally remove ~/.config/opencode/opencode-raven/.

On OpenCode 2, remove it from plugins instead. /raven update uses v1 cache-clearing behavior only on OpenCode 1; on v2 it checks the version and provides restart/pinned-version instructions while leaving cache management to OpenCode.

Development Checks

bun install
bun test
bun run typecheck
bun scripts/smoke-compat.ts v1 /path/to/opencode-v1
bun scripts/smoke-compat.ts v2 /path/to/opencode-v2

The native smoke checks use isolated configuration and data directories. The v2 check uses a deterministic local model endpoint to exercise routed main-agent search, direct Raven child search, delegation completion, and command/RPC output without calling a paid model provider.

See CHANGELOG.md for release history.

Disclaimer

opencode-raven is an independent project and is not affiliated with the OpenCode team. Released under the MIT License.