opencode-router-mcp

Cost-aware, multimodal OpenCode task router and sub-agent MCP server for Claude Code.

This is a Windows-first optional OpenCode execution channel for Claude Code, based on the intended refactoring of AlaeddineMessadi/opencode-mcp. Claude remains the primary agent and may work natively or use Claude subagents; this MCP only manages OpenCode after Claude has selected that path. It exposes only seven compact high-level tools: opencode_delegate, opencode_status, opencode_review, opencode_revise, opencode_abort, opencode_models, and opencode_usage.

Run

Requires Node.js 20+ and an OpenCode installation on PATH. Start over stdio with node src/server.mjs. The repository includes .mcp.json for Claude Code; update its absolute paths if the project is moved.

Run npm run models:refresh after OpenCode Go is configured. Model IDs are read from opencode models; this project never guesses IDs from display names. The registry remains empty when OpenCode is unavailable. npm run models:probe-vision reports whether a real probe was possible; it never fabricates success.

The router defaults to run for cheap/balanced tasks and session for powerful tasks after Claude has already selected OpenCode. mode: auto only chooses one-shot versus persistent OpenCode execution; it never chooses Claude or a Claude subagent. It retries/fails over transient model errors within a tier, disables a provider after shared quota errors, and only upgrades capability when explicitly allowed. Provider remaining quota is always reported as unknown; local usage is estimated only.

Security

Directories and attachments must be absolute and existing. System roots, secrets, credential files, unsupported MIME extensions, oversized files, and more than five attachments are rejected. OpenCode should be configured to listen on localhost only. No global unrestricted permissions, raw shell tool, session sharing, or secret-bearing configuration is provided.

Development

npm run build, npm test, npm run test:skill, npm run test:security, npm run test:failover, npm run test:smoke, npm run test:e2e, and npm run test:closed-loop are the local verification commands. npm run test:opencode-free performs a real, read-only smoke test using a discovered model whose ID is explicitly marked free; it never selects an unmarked model. npm run test:vision reports SKIPPED when no verified image model exists. See docs/ and .claude/skills/opencode-use/ for routing guidance. No commits or pushes are performed automatically.