opencode-mcp

MCP server that lets Claude Code pick an OpenCode model and delegate jobs to the opencode CLI (which must already be installed and authenticated: opencode auth login).

Intended use case

This exists so a Claude Code session can offload work that doesn't need Claude's own reasoning to a cheap/free model instead, without spending Claude tokens on it — code review passes, exploratory bug hunts, well-scoped implementation from a written spec, or any "have someone else look at this" request that doesn't name a specific Anthropic model. It is not a way to run Claude itself more cheaply, and it's not meant for tasks that genuinely need Claude-level reasoning (architecture decisions, ambiguous requirements, anything where a wrong answer is costly) — those should stay on Claude. The tier system (low/mid/high/max, see below) exists specifically so the caller never has to know or care which OpenCode model is currently cheapest-yet-good-enough; it just asks for an intelligence level and gets whatever the data says best fits it today.

Related MCP server: OpenCode MCP Tool

Tools

• opencode_check_go_status — confirms the OpenCode Go credential is configured, lists its current model lineup, and reports currently-blocked models. Pass probe:true to also manually ping the mid/high/max tier models right now (costs a little time/tokens — this is a diagnostic option, not part of the automatic failure-handling below).

• opencode_refresh_tiers — recompute the low/mid/high/max tier map from live data (see "Model tiers" below). Pure local computation, effectively free. On-demand only, not routine (it already runs automatically once a day).

• opencode_unblock_model — manually clear a model from the failure blocklist (exponential backoff, not a flat block — see "Automatic failure handling" below) and recompute immediately, e.g. right after re-enabling it in the OpenCode dashboard.

• opencode_start_job — send a prompt/task to a tier (low/mid/high/max) or an explicit model+variant, in a given directory. Pass waitMs to block until it finishes and get the full result back in this same call (recommended — see "No push notifications" below); omit it for fire-and-forget (returns just a jobId).

• opencode_job_status — check on a job started earlier (works across a server restart or a different process — see "Job state survives a restart" below); pass waitMs to block until it finishes.

• opencode_resume_job — nudge an existing opencode session to continue instead of starting over, e.g. after a transient hiccup derailed it. See "Resuming a derailed job" below.

• opencode_list_jobs — list all jobs started this server session (in-memory only, unlike the two above).

• opencode_usage_stats — aggregate tokens/cost/response-chars across every job this server has ever delegated (persisted, survives across sessions/processes — unlike opencode_list_jobs). See "Usage tracking" below.

• opencode_cancel_job — kill a running job.

• opencode_list_providers — configured credentials (e.g. OpenCode Zen, OpenCode Go, OpenRouter).

• opencode_list_models — list provider/model ids, optionally filtered by provider. Only needed when a job requires a model outside the tier map.

• opencode_model_info — verbose metadata (cost, context window) for one model.

• opencode_audit — fan N forced-read-only reviewers out over uncommitted changes (or a commit range), confidence-ranked and adversarially re-checked. See "Multi-agent orchestration" below.

• opencode_investigate — same read-only fan-out/reconcile shape as opencode_audit, but for an arbitrary question instead of a diff.

• opencode_goal — sequential passes toward a goal, with real lint/test output fed to each next pass, verified read-only at the end.

• opencode_job — runs opencode_goal then opencode_audit on whatever it produced, and hands both results back untouched.

Jobs shell out to opencode run --format json, parsing its newline-delimited JSON event stream (text, step_finish, error) to assemble the final response text, token usage, and cost as the process runs.

Completion detection uses exit, not just close (src/jobs.js)

Node's close event on a spawned child only fires once ALL of its stdio file descriptors are closed — if opencode run leaves a descendant process running (a backgrounded bash command, another MCP server it connected to, an orphaned watcher) that inherited those pipes, close can be delayed by seconds, minutes, or indefinitely, even though opencode's own process — and the real work it did (files written, answer produced) — finished long ago. Observed 2026-08-09: a multi-agent orchestration session had jobs whose actual output files were already written, but opencode_job_status kept reporting them as still running, forcing a workaround of reading the files directly instead of trusting the job status. Reproduced in isolation: a child that backgrounds a sleep and exits fires exit at ~15ms but close at ~5000ms — a 5-second gap from one lingering subprocess, with no ceiling on how long a real one could hold it.

Fixed by listening to both exit and close, settling the job on whichever fires first (exit will normally win when this scenario occurs; a settled guard prevents double-finalizing on the completely normal case where both fire within milliseconds of each other). When the second event does arrive much later, its gap is logged to stderr — real production evidence of how often/how badly this happens, not just a synthetic test's word for it.

No push notifications — jobs don't "ping back" when done

MCP tool calls are strictly request/response: this server has no way to interrupt a Claude Code conversation on its own when a background job finishes. This is not like Claude Code's native run_in_background: true for Bash/Agent, where the harness itself pushes a notification the instant the task completes — that mechanism is specific to the harness's own process tracking and doesn't extend to arbitrary MCP servers. jobs.js's internal EventEmitter ("done") only resolves a call that's actively await-ing it (waitForJob); it can't reach into a conversation that already moved on.

Two ways to actually get a result, neither of which involves waiting for a ping that will never arrive:

• Block on waitMs (recommended for most jobs): pass waitMs to opencode_start_job (or a follow-up opencode_job_status) — up to 540000ms (9 min) — and the call itself won't return until the job finishes, with the full result (text, tokens, cost) in the same response.

• Fire-and-forget + manual follow-up: omit waitMs to get just a jobId back immediately, do other work, then call opencode_job_status({ jobId }) yourself later. There is no notification to wait for — if you don't check back, the result just sits there until you do (or the server process exits).

Job state survives a restart (src/job-store.js)

In-memory-only job tracking means the instant this MCP server process restarts or crashes — or a DIFFERENT process (another Claude Code session) tries to look up a job it didn't start — opencode_job_status returns No job with id "...", even though the real opencode session and everything it produced (files written, answer given) are completely intact. Observed 2026-08-09 right after this exact scenario.

Every job's state (model, variant, dir, sessionId, tokens, cost, and the assembled response text) is checkpointed to disk at ~/.local/share/opencode-mcp/jobs/<jobId>.json on every step_finish event and on final completion/failure — frequent enough that a killed process still leaves recent progress recoverable, not so frequent it's meaningful I/O overhead. getJob/opencode_job_status/opencode_resume_job all fall back to this file when a job isn't in the current process's memory. opencode_list_jobs does NOT include disk-only jobs (it only enumerates what THIS process remembers) — it's for browsing the current session's own work, not a full history; look a specific job up by id instead if you know it.

Resuming a derailed job (opencode_resume_job)

Sometimes a job goes in circles, loses context, or a transient hiccup (a network blip, a tool call that failed weirdly) visibly derails it without an outright process failure — the kind of thing you'd fix by hand in the opencode TUI by finding the session and typing "hubo un error de red, continuá desde donde quedaste." opencode_resume_job does exactly that programmatically: it starts a new job continuing the SAME opencode session (via --session <id>, not --continue, so it targets a specific session rather than "whatever was last") with a nudge prompt (a sensible default, or your own if you know what actually went wrong).

Pass jobId (works across a restart/different process, per the above) or sessionId directly. Verified end-to-end, including across a simulated server restart: a fresh process with zero shared memory recovered a job's sessionId from disk, resumed it, and the model correctly recalled context from before the "restart."

Clean hand-off output, not a transcript

jobSummary(...).text (what opencode_job_status/opencode_start_job return) is built only from type: "text" events — tool calls (file reads, bash, skill loads), step markers, and any reasoning/thinking events are parsed but never included. This is structural (in src/jobs.js's handleEvent), not prompt-dependent, so it holds regardless of style.

On top of that, opencode_start_job's style param (default "handoff") appends a short instruction telling the model to skip preamble/meta-commentary and return just the deliverable — a caller can pass style: "verbose" to get the model's own narration back for debugging (e.g. "why did it read files it didn't need to"). In testing this made a bigger difference on models prone to chatty preambles than on big-pickle, which was already fairly direct — treat it as a nudge, not a guarantee.

Model tiers (src/tiers.js + src/rank.js + src/leaderboard.js)

Callers pick an intelligence tier (low/mid/high/max) instead of memorizing model names or guessing which one is actually good. The map is data-driven, built by computeTierMap() (src/rank.js):

1. Pull every opencode-go/* model's real per-token cost from opencode models opencode-go --verbose (local, authoritative — no scraping needed for this axis; the Go plan's advertised "requests per week" chart is just this cost data divided into a dollar budget, confirmed by cross-check).

2. Scrape arena.ai/leaderboard/code/webdev (src/leaderboard.js, plain server-rendered HTML table, no JS execution needed) for each model's WebDev/code score — matching handles the leaderboard's reasoning-effort suffixes (-max, -high, -xhigh, dated snapshots), trying an exact id match first so a real distinct SKU like qwen3.8-max isn't mistaken for qwen3.8 at variant max.

3. Sort all matched models by cost ascending and compute a cost ceiling per tier from the quartile cutoffs (low's ceiling = 25th-percentile cost, mid's = 50th, high's = 75th, max has none). Each tier's pool is cumulative — every candidate at or under its ceiling, not just the ones in its own quartile.

4. Within a tier's pool, the winner is not simply the highest score — it's the cheapest model within SCORE_TOLERANCE_PCT (1%, rank.js) of the pool's best score. A 1676-vs-1668 gap (0.5%) doesn't justify paying 50% more, so the cheaper one wins; a 1577-vs-1523 gap (3.5%) is treated as a real quality difference and the higher scorer still wins outright. This also means a cheap model that's merely "good enough" relative to a tier's ceiling can win it without being the pool's outright top scorer — e.g. observed 2026-08-05, qwen3.8-max ($2, score 1668) beat kimi-k3 ($3, score 1676) for max under this rule. Pools nest (low ⊆ mid ⊆ high ⊆ max) so scores are still monotonically non-decreasing from low to max.

5. Flag a tier inherited: true (with inheritedFrom: "<cheaper tier>") when its final winner is the same model+variant as a cheaper tier's — i.e. one model was good/cheap enough to win multiple tiers. Informational only.

6. Persist the result (including each tier's full fallback list, not just the winner) to tiers.generated.json (gitignored — regenerate, don't hand-edit).

This is a pure local computation — one opencode models --verbose call plus one HTTP fetch of the arena leaderboard, no opencode run calls at all. See "Automatic failure handling" below for how broken models get excluded without needing to proactively probe every one of them.

This refresh happens automatically, at most once a day, with no tool call and no tokens spent describing it — opencode_start_job (and opencode_check_go_status, and server startup) check tiers.isStale() and fire the refresh in the background (fire-and-forget) if the saved map is missing or >24h old. The job that triggered the check still runs against whatever's on disk right now; the refreshed map is ready for the next call. opencode_refresh_tiers still exists as a manual override for "I need this recomputed right now," not for routine use.

Models the leaderboard has no entry for (e.g. qwen3.7-plus as of 2026-08) are excluded from tiers but reported in unmatched, never silently dropped.

Token/cost discipline: default to low unless the task clearly needs more reasoning depth — mid/high/max don't cost extra dollars under a Go subscription, but every job still burns real tokens and wall-clock time. An explicit model (+ optional variant) param on opencode_start_job overrides the tier for one-off cases outside the map.

Automatic failure handling — no proactive probing (recordJobOutcome in index.js)

Earlier versions of this ranker live-probed every tier's pick with a trivial prompt before saving, to catch models that score well but are actually unreachable (region-locked, disabled in the OpenCode dashboard, etc). That cost real tokens/time on every refresh — small per probe, but recurring, and it got a false positive: a legitimately slow reasoning model (kimi-k3/max, 30-60s for even a 1-word answer) got treated as "broken" by a too-short probe timeout. Both problems are solved by not probing at all:

• Every opencode_start_job tier resolution is tried for real. If it fails with a genuine error (non-zero exit / an error message — e.g. deepseek-v4-flash returning "requires explicit opt-in" when disabled in the dashboard), that model+variant is blocked with exponential backoff and the tier map is recomputed immediately to exclude it — this happens whether or not the caller passed waitMs, so even fire-and-forget jobs self-heal the map for next time.

• "Still running" past a timeout is never treated as a failure — only an actual error is. This is the fix for the kimi-k3/max false positive: a slow-but-working model is never penalized just for being slow.

• If waitMs was passed, a hard failure is retried automatically (up to 5 attempts) with the next-best candidate in the same cost pool, within the same opencode_start_job call — the caller gets a working result without needing to notice the failure and retry manually.

• Backoff, not a flat block (BACKOFF_SCHEDULE_MS, tiers.js): 5min for a first failure, escalating to 30min → 2h → 8h → 24h only if the model keeps failing on repeated real attempts. A single success clears the failure history entirely, so the next isolated blip starts back at 5min instead of compounding. This exists because a flat 24h block (the original design) meant a brief real outage — observed 2026-08-08, deepseek-v4-flash down for what was probably minutes — kept routing to a pricier fallback (gpt-5.6-luna) for the rest of the day until manually unblocked, visibly spiking that day's spend for no good reason. To force a block clear sooner regardless of backoff — e.g. right after re-enabling a model you'd disabled in the OpenCode dashboard — call opencode_unblock_model. Current blocks (with remaining backoff time) are visible in opencode_check_go_status's blocked field.

• Cost is paid only on real usage, only when something's actually broken — not on a schedule, not "just in case." A model that's simply never used is never checked and never costs anything.

Notable free/no-extra-cost models seen on this machine

• opencode/big-pickle — free on OpenCode Zen (cost: 0).

• opencode-go/* — included in the OpenCode Go subscription. Some entries can be slow, region-restricted, or hang depending on OpenCode's backend that day — opencode_cancel_job exists for exactly that.

Usage tracking (src/usage.js)

Every job, on completion (success or failure), appends one line to ~/.local/share/opencode-mcp/usage-log.jsonl — outside the repo, machine-local, grows forever, same convention as opencode's own ~/.local/share/opencode. Each record has tokens, list-price cost, prompt/response character counts, tier, model, and duration. opencode_usage_stats reads it back and aggregates totals + a per-model breakdown; pass sinceHours to scope to recent activity only.

cost is OpenCode's own list price for the tokens used — under the Go subscription (flat-rate) or Zen (free tier) the dollars actually charged is $0 regardless, so the aggregated total is the savings from delegating instead of paying per-token. It is not a comparison to Claude/Anthropic API pricing — there's no reliable way to know what equivalent work would have cost in a different model's tokenizer, so this tool doesn't claim to measure that.

This log is separate from (and complements) OpenCode's own opencode stats --models, which aggregates all opencode usage on the machine regardless of what started it — use that for the full-machine picture, use opencode_usage_stats to scope specifically to what this MCP server delegated.

Pinning one model for a whole session (OPENCODE_MCP_PIN_MODEL)

Every opencode-mcp server process is tied 1:1 to the Claude Code session that spawned it, and an env var is fixed for that process's whole lifetime — so setting OPENCODE_MCP_PIN_MODEL (and optionally OPENCODE_MCP_PIN_VARIANT) when registering the server forces literally every opencode_start_job call in that session to one fixed model, bypassing cost/score ranking and the failure blocklist entirely:

claude mcp add opencode --scope user \
  --env OPENCODE_MCP_PIN_MODEL=opencode-go/deepseek-v4-flash \
  --env OPENCODE_MCP_PIN_VARIANT=high \
  -- node /path/to/opencode-mcp/src/index.js

The pin is a HARD override — it wins even over an explicit model param. That's deliberate: the whole point is "this session always uses X, no exceptions," including the exact case a pin exists for — you forget it's pinned and ask for something else by name (model: "opencode-go/kimi-k3") or via tier. When the actual request differs from the pin, the response carries a warning field spelling out what was asked for vs what got forced, so the override is never silent — no warning field means nothing was overridden (including the normal case of a plain tier call, which a pin always "overrides" by design and doesn't warn about).

Useful when you want predictable, consistent model usage for a session regardless of day-to-day ranking drift or in-flight failures. Whether a pin is active (and what it's pinned to) is visible in opencode_check_go_status's pinnedModel field. Note this only affects the session that registers it this way — concurrent sessions each run their own server process with their own env, so this isn't a machine-wide setting.

Multi-agent orchestration: audit / investigate / goal / job (src/orchestrate.js)

One model call is one opinion. These four tools spend extra parallel calls — close to free when OPENCODE_MCP_PIN_MODEL points at a local model, since sending 1 request or 16 costs the same wall-clock time and money — to get a more reliable answer than a single pass would: many independent read-only reviewers instead of one, confidence-ranked instead of blindly trusted, adversarially re-checked instead of taken at face value. defaultWidth() detects whether the resolved model is actually the free local one (or a paid tier) and scales default participant counts up or down accordingly, so a paid-tier call doesn't silently balloon in cost just because the code assumes parallelism is free.

One-time setup: the mcp-readonly opencode agent

Every read-only reviewer/aggregator/verifier across all four tools runs as a dedicated opencode agent, mcp-readonly, registered once in ~/.config/opencode/opencode.jsonc (a machine-level config file, NOT part of this repo — each machine running this MCP server needs this added once):

{
  "agent": {
    "mcp-readonly": {
      "mode": "primary",
      "description": "Forced read-only agent used by opencode-mcp's audit/investigate/goal-verify commands — cannot edit files, run shell commands, or invoke skills/sub-tasks.",
      "permission": {
        "read": "allow",
        "grep": "allow",
        "glob": "allow",
        "list": "allow",
        "webfetch": "allow",
        "websearch": "allow",
        "edit": "deny",
        "bash": "deny",
        "task": "deny",
        "skill": "deny",
        "todowrite": "deny"
      }
    }
  }
}

mode must be "primary", not "subagent". opencode run --agent <name> silently falls back to the default agent (defeating the whole read-only guarantee, with only a stderr warning to notice it) if the named agent isn't a primary one — found this the hard way while testing. Verify it registered with opencode agent list — it should show mcp-readonly (primary).

opencode_audit and opencode_investigate

Both fan N participants out in parallel, all forced onto mcp-readonly (a real permission-engine guarantee, not a prompt asking nicely), then run them through the same confidence-ranked reconciliation:

1. Round 0: N participants' independent findings go to ONE aggregator, which builds a single report and explicitly notes how many participants corroborated each finding — 2+ is CONFIRMED, exactly 1 is LOW CONFIDENCE.

2. Adversarial round(s) (depth times, default 1): a FRESH batch of N reviewers gets ONLY the current report, framed as "a low-confidence agent reported this, your job is to determine its falseness" — each independently tries to refute the low-confidence items using its own read-only access to the real code. One more aggregator then reconciles [previous report + all adversarial reviews], promoting survivors to "adversarially confirmed" and calling out (never silently dropping) anything refuted. depth=0 skips this; depth=2 repeats the whole round-then-reaggregate step twice for higher-stakes reviews.

opencode_audit reviews a git diff — uncommitted changes by default, or everything since baseCommit (a whole branch/PR) when given. If the diff is too large (~100k+ tokens) to hand every participant in full, participants each get a distinct subset of the changed files instead. Each participant is also assigned a rotating "lens" (correctness, security, simplification, efficiency, tests, consistency, error handling, readability) so N reviews of the same diff under the same (often deterministic, local) model actually diverge instead of producing near-duplicate output.

opencode_investigate is the same shape driven by an arbitrary prompt instead of a diff — use it to have several independent agents look into one question and get back a reconciled answer, e.g. "does the test suite actually cover the new drill-down interaction, or just that it renders?"

opencode_goal

Sequential, not parallel — these agents actually edit code, and running them concurrently in the same working tree would corrupt each other's changes. (An earlier version ran independent parallel attempts judged by a panel — reverted after real testing showed the judge panel, being the same weak model, reject genuinely correct candidates outright; see the git history around runGoal if curious.) Pass 1 attempts the goal fresh; each later pass continues the previous pass's own opencode session.

The actual defense against a weak model trusting its own "done!" self-report: after every pass, real lint/test commands run against dir — a mechanical, ground-truth signal, not another LLM's opinion — and the genuine pass/fail output gets attached to the next pass's prompt. Commands auto-detect from dir's package.json (scripts.lint/scripts.test) if not given explicitly; pass lintCommand/testCommand to override, or explicit null to force-disable one. Once every pass finishes, one final mcp-readonly pass inspects the repo's actual current state (not the passes' self-reports) and returns a consolidated verification report.

opencode_job

Runs opencode_goal to completion, then immediately runs opencode_audit on whatever it left uncommitted, and returns both results verbatim — it does not interpret the QA findings, decide they're serious, or trigger another goal pass on its own. Deciding what to do with what QA found (fix it, ignore it, ask the user) is explicitly the caller's job, not this tool's — matches this whole project's stance of surfacing information rather than silently resolving it on the caller's behalf.

Try it yourself

mkdir -p /tmp/opencode-mcp-demo && cd /tmp/opencode-mcp-demo
git init -q && git config user.email "demo@demo.com" && git config user.name "Demo"

cat > calc.js << 'EOF'
function multiply(a, b) {
  return a * b;
}
module.exports = { multiply };
EOF

cat > calc.test.js << 'EOF'
const assert = require("assert");
const { multiply, divide } = require("./calc");
assert.strictEqual(multiply(2, 3), 6);
assert.strictEqual(divide(10, 2), 5);
console.log("all tests passed");
EOF

cat > package.json << 'EOF'
{
  "name": "opencode-mcp-demo",
  "scripts": {
    "test": "node calc.test.js",
    "lint": "node -e \"require('./calc.js'); console.log('lint ok')\""
  }
}
EOF

git add -A && git commit -q -m "initial"

Then, from Claude Code (with this MCP server registered — see "Register with Claude Code" below), ask something like:

Use opencode_job on /tmp/opencode-mcp-demo with the goal "the test suite in calc.test.js is failing — fix calc.js so npm test and npm run lint both pass," then tell me what happened.

Expected: pass 1 adds the missing divide function, the lint/test checks that run right after come back green, and the QA audit that follows finds nothing wrong with the (correct, minimal) diff. To see the reconciliation mechanism do real work instead of rubber-stamping, try opencode_audit directly on a deliberately messier diff — introduce an actual bug (e.g. an inverted comparison or a copy-pasted line) before auditing, and check that it shows up as CONFIRMED (if more than one lens/reviewer flags it) rather than buried in a wall of text.

Install

npm install

Register with Claude Code

claude mcp add opencode --scope user -- node /path/to/opencode-mcp/src/index.js

Replace /path/to/opencode-mcp with wherever you cloned this repo (e.g. run pwd from inside it to get the absolute path).

Takes effect in new Claude Code sessions (an already-running session won't pick up newly registered servers). This also means different concurrent sessions can be running different versions of this server's code — a session started before a fix landed keeps running its old behavior until it's restarted. If you see inconsistent model choices across sessions on the same day, this is the first thing to check, not necessarily a ranking bug.

Safety note

opencode_start_job accepts an auto flag that maps to opencode's --auto (auto-approve all tool permissions). It's off by default; only set it for jobs you trust to edit files / run commands unattended.