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 server

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_submit — queue a batch of work orders for the scheduler daemon; returns order ids immediately, runs nothing in-call. The way to dispatch parallel work — see "The work-order queue" below.

• opencode_wait — long-poll until listed orders finish (short work only; otherwise watch the sentinel files).

• opencode_order / opencode_batch — collect results for one order or a whole batch.

• opencode_queue_status — order counts, what's running, and each backend pool's limit / KV budget / breaker state.

• opencode_roster — the model fleet routing picks from: bench score, context, cost, measured health.

• opencode_cancel_order — stop an order or an entire batch.

• opencode_loop — implement ONE work package end to end (write, gate, review, decide) in an isolated worktree. See "The work/review loop" below.

• opencode_loop_status — check a loop's progress, gate result, surviving claims, and (if escalated) exactly why.

• opencode_loop_cancel — stop a running loop; its worktree and branch are left in place.

• 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_sweep — audit an ENTIRE codebase in path-coherent segments, feeding confirmed findings forward so later segments hunt new instances instead of re-reporting known ones. Long-running: returns a sweepId, poll it.

• opencode_sweep_status — progress, the confirmed-findings ledger, and the path to the markdown report (rewritten after every segment).

• 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 — but there IS a reliable way to be woken

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.

The scheduler solves this properly — see "The work-order queue" below. Every finished work order gets a sentinel file, which a single background shell command can watch (until [ -f ... ]; do sleep 20; done); the harness then notifies the agent when that command exits. The daemon guarantees the file appears for every terminal outcome, so the watcher cannot hang on work that quietly died.

The rest of this section describes the older per-job path, still valid for one-off opencode_start_job calls. There, the server genuinely cannot reach you: unlike Claude Code's native run_in_background: true for Bash/Agent — where the harness 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.

Matching the concurrency ceiling to your backend (OPENCODE_MCP_MAX_CONCURRENCY)

opencode_audit/opencode_investigate/opencode_sweep fan participants out through a rolling-window concurrency limiter, not fixed batches — as soon as any one job finishes, the next queued one starts immediately, rather than waiting for a whole wave to complete before starting the next. The ceiling on how many run at once defaults to a conservative 4, since this server has no way to know what your actual model backend can serve. If yours can genuinely handle more — e.g. a local multi-agent-capable server advertising a real concurrency limit of 16 — set that once at registration instead of passing maxConcurrency on every call:

claude mcp add opencode --scope user \
  --env OPENCODE_MCP_MAX_CONCURRENCY=16 \
  -- node /path/to/opencode-mcp/src/index.js

The full chain is: maxConcurrency passed on that specific call → the env var → 4. Nothing in it is cached at server startup — the env var is read fresh on every single dispatch, not baked into a frozen default the moment this process boots. That mostly matters for the ordinary case: pass maxConcurrency directly on any call whenever you want to change the ceiling right now, no server restart needed either way. The effective fallback is visible in opencode_check_go_status's defaultMaxConcurrency field. Getting this wrong in either direction has a real cost: too low and you leave real backend capacity idle for no reason; too high and you get exactly the failure mode this setting exists to prevent — observed 2026-08-22, a sweep at replicas:4 (48 concurrent participants) against a backend that couldn't actually serve that many ran 5h42m without a single segment completing.

Transient failure retries (SQLite lock contention)

Aggregation and read-only participant jobs are wrapped in a short retry-with-backoff (runOneJob in src/orchestrate.js): if a job fails with an error matching a known-transient pattern — database is locked, SQLITE_BUSY, or a generic "unexpected server error" — it's retried up to 2 more times with a 1.5s backoff before being treated as a real failure. This exists because opencode's own local session-store database is shared across every opencode run process this server spawns, so a high maxConcurrency against it can produce a transient lock contention failure that has nothing to do with your actual review logic — observed 2026-08-22 on a replicas:4/lenses:"all" (48-participant) single-segment run, where a tree-aggregation job failed outright with database is locked and killed the whole segment's result before the retry existed; the same run with the retry in place recovered from one such failure mid-aggregation and completed normally. This does not apply to opencode_goal's sequential edit-making passes — retrying a job that may have partially edited files carries real idempotency risk that a pure read-only reconciliation call doesn't have, so those are left to fail straight through.

The work-order queue (src/scheduler/)

The oldest bug in this server was that concurrency was bounded per call. Each opencode_audit / opencode_sweep built its own limiter, and opencode_start_job had none at all — so a single orchestrator dispatching a handful of jobs in one turn could put an unbounded number of processes on one backend. Against a local model server that crashes past a known request count, that is not a throughput problem, it is a lost multi-hour run.

opencode_submit replaces all of it. You hand the scheduler everything you want done; it decides what runs when. You never compute concurrency, and you cannot overload a backend by submitting too much — surplus orders wait.

It survives you

The queue lives in a daemon, not in this MCP process. It listens on a unix socket (~/.local/share/opencode-mcp/scheduler.sock), is spawned automatically on first use, and is detached — its parent becomes init, in its own session.

The MCP server restarting, the agent restarting, Claude Code exiting: none of them stop the work. Reconnect and the daemon still has your orders, running and finished alike. This is verified, not assumed: a client was killed mid-flight with six orders running and all six completed and were collected afterwards by a different client.

Because the daemon outlives your edits too, it does a protocol-version handshake. A daemon older than its client stops taking new work, finishes what it has, and exits so the next connect gets a current one — otherwise you spend an afternoon debugging code that is not the code that is running.

Admission control is per backend, not one global number

The constraints are physically different and one number cannot express both.

Slots alone do not protect a shared KV pool — eight requests at 64K fit in 511K, eight at 262K do not, and counting processes cannot see the difference. So the local pool also admits against a token budget, and every order carries a reserveTokens estimate.

Remote ceilings are learned by AIMD: climb one slot every eight successes, halve on a 429 or a dropped connection. A plain failure — the model ran and returned something bad — deliberately does not shrink the limit, because it says nothing about capacity.

A burst of connection failures is treated as one event (the backend went down), not N independent ones: the breaker trips, the pool pauses, and after a cooldown exactly one probe is let through to find out whether it is back. Retrying all of them immediately is a retry-storm against something already on the floor.

Routing: bench, health, and deliberate diversity

You do not pick models. The router picks per order, at the instant a slot opens — which pool has capacity is not knowable when the batch is queued. It weighs:

• Arena bench score for code work (the same ranking behind tier).

• Measured health from the real usage log: success rate, and empty-response rate. A free model that returns 200 OK with an off-format body is worse than one that errors, because it enters a swarm as silent noise instead of a visible failure.

• Role fit: an aggregator is routed to a big-context model (the fleet has several free 1M-context ones, which is what lets aggregation leave the local pool entirely); a worker is routed to top bench.

• Cost: free-only by default. The roster reaches ~89 models of which ~55 are metered, several sitting at the top of the bench table. Routing on score alone quietly bills for a 48-participant swarm. Opting in is per order (allowPaid).

Replica diversity is a hard constraint, and it is a correctness mechanism rather than a performance one. Orders sharing a lens never run on the same checkpoint. The swarm treats "2+ reviewers of a lens agree" as corroboration, which is worth something only if their errors are independent — four replicas on one model are four correlated opinions. Observed in this repo: twelve reviewers unanimously confirmed a HIGH-severity bug that did not exist. A duplicate replica does not merely fail to corroborate, it manufactures agreement. So when the only checkpoint with a free slot is one the lens already used, the order waits rather than taking it.

Nothing is ever lost

Four distinct ways to lose state, four mechanisms:

Every terminal transition funnels through one function, which is what makes the sentinel guarantee hold — there is exactly one place that can end an order, so exactly one place that has to write the file. Verified by SIGKILLing the daemon with four orders in flight: the next boot closed all four out with sentinels and an explanatory message, so nothing waiting on them could hang.

Retries are not applied to worker orders. Replaying a job that may have half-applied an edit is worse than reporting the failure.

Mandatory wait protocol

After opencode_submit, do exactly one of these — and never invent a third.

(A) Preferred, for anything beyond a couple of minutes. One background shell command watching the sentinels:

until [ -f ~/.local/share/opencode-mcp/done/<orderId> ]; do sleep 20; done

For a batch, count them:

until [ "$(ls ~/.local/share/opencode-mcp/done | grep -Fcf /tmp/order-ids)" = "12" ]; do sleep 20; done

Then collect with opencode_batch. The harness notifies you when the watcher exits.

(B) Short work only: opencode_wait, which long-polls and returns the finished orders directly.

Never poll opencode_queue_status in a loop — that burns your context on status text. One watcher per batch, nothing more.

Tools

opencode_queue_status is for understanding why something is queued — a pool at its limit or a tripped breaker is ordinary backpressure, not a stall.

The work/review loop (src/loop/, opencode_loop)

opencode_submit dispatches independent work orders. opencode_loop is the layer above it for a SINGLE work package that needs to be built, checked, and iterated on until it is actually right — not just until something got written. It runs entirely inside the scheduler daemon, so it survives this MCP process (and the agent driving it) restarting mid-run, exactly like the queue underneath it.

The shape, per iteration

  A. WORKER writes            (edits files directly, in an isolated worktree)
  0. GATE proves               (the repo's own lint/typecheck/test — see below)
     ├─ red  → raw output straight back to the worker, skip B/C/D entirely
     └─ green → continue
  B. CONFORMANCE checks         (2 reviewers: does the diff match the spec?)
  C. REFUTATION tries to break B's claims (3 reviewers, default = "not a defect")
  D. ARBITER decides            (done | needs-fix | escalate)

Gate 0 runs before a single review token is spent, because the compiler is the cheapest and most reliable reviewer there is. Spending five model calls to learn what tsc or a test runner would have said in two seconds is pure waste — and worse, a reviewer asked to read code that does not build tends to report the downstream symptom instead of the actual cause. A red gate sends its raw output straight back to the worker and skips B/C/D for that iteration entirely.

Round B is separated from Round C on purpose. "Did it build the right thing" and "is what it built correct" are different questions, and a reviewer asked both at once reliably answers only the second — the spec silently stops being checked. Round C exists because reviewers told to find problems will find them whether or not they are real; its whole job is to try to knock B's claims down, defaulting to "not a defect" unless it can independently reproduce the failure. A claim needs upholdThreshold (default 2) independent UPHELD rulings to survive — and silence is not assent: a refuter that died or gave an unparseable answer casts no vote either way, so a round where reviewers failed cannot promote a claim on one opinion.

Zero votes is not the same as refuted

Caught on a real run, not in review: a genuine SQL syntax error (create schema_migrations (...), missing the table keyword) was correctly flagged in Round B, then silently discarded — the refutation round mostly failed to complete (two of three reviewers never finished), and the one survivor's reply didn't parse into any per-claim ruling. The old adjudication code treated "0 votes" the same as "refuted by everyone", because both fell into the same else branch. A real, confirmed defect vanished with no trace beyond a buried upholdCount: 0 / voteCount: 0.

A claim with zero votes is now its own outcome — inconclusive, distinct from both upheld and refuted, and deliberately NOT added to the refuted-keys set (so it stays eligible to be re-raised rather than permanently suppressed). One retry is attempted, forced onto the local model rather than the free fleet that just failed to produce a usable round; if it's still inconclusive after that, the loop escalates with reason: "refutation-inconclusive" and the unreviewed claims attached, rather than letting the arbiter decide on a partial picture. The arbiter never even runs in that case — the whole point is not to give it data that looks clean but isn't.

The arbiter's authority is enforced in code, not just requested in the prompt

• It may return "done": true only if the gate ran AND passed AND nothing survived Round C. If it tries to approve anyway — a red gate but an otherwise-confident model, which happens — the loop overrides it and escalates instead of trusting the model's own claim of what it checked.

• It may put something under mustFix only if it is one of the claims that actually survived Round C, cited with a file and line. It adjudicates; it does not get to invent new findings in its own round.

• Anything needing a judgement call — a design trade-off, an ambiguous requirement — goes under cannotDecide and escalates to the caller. This is the correct outcome for that kind of question, not a failure of the loop, and it's how you satisfy "the model decides when it's done" without asking a small model to make an architecture decision.

Escalation never means calling a stronger model

No Anthropic model is reachable from this server, at any price, under any role. Escalating means stopping and handing the caller everything needed to finish by hand: which claims survived, the gate's actual output, and the worktree + branch left in place (not deleted — the partial work is usually the most useful part of an escalated result).

Isolation: one git worktree per work package

Each loop branches a fresh worktree from baseRef so several work packages can run at once without their diffs colliding. A brand-new worktree has source but no build state — no node_modules, no .dart_tool, no target/ — which would make the gate fail for purely environmental reasons that look identical to real ones. .opencode-loop.json's worktree.shareDirs symlinks those directories in from the main checkout instead of reinstalling them per package; worktree.setupCommand is the escape hatch when a dependency tree genuinely cannot be shared this way.

Model choice: local by preference, free fleet on failure, never routing back into what just failed

The worker tries the configured local model first — predictable effort, doesn't touch the throttled free-tier budget. If that fails or times out (the scheduler's 8-minute wedge-detection heartbeat, same mechanism the queue already uses), the retry excludes the model that just failed and lets the router pick from the free fleet instead. This exclusion is not optional decoration: without it, the router is free to route the "fallback" straight back into the same dead backend it still nominally has capacity for, which is exactly what happened the first time this was tested against a genuinely unreachable local server — the fallback wedged for another 8 minutes against the same target before anyone noticed.

.opencode-loop.json — the gate is per repo, not per call

{
  "lintCommand": "npm run lint",
  "testCommand": "npm test",
  "typecheckCommand": "npx tsc --noEmit",
  "gateTimeoutMs": 600000,
  "worktree": {
    "shareDirs": ["node_modules", ".dart_tool", ".venv", "vendor", "target", "build"],
    "setupCommand": null
  }
}

Without this file, the loop still runs, but the arbiter can never return done — an ungated result is reported as unverified, not approved, because the whole point of Gate 0 is to stop the loop from taking a small model's word for it.

Tuning defaults

Waiting for a loop

Same sentinel contract as the queue — opencode_loop returns a loopId and a sentinel path immediately:

until [ -f ~/.local/share/opencode-mcp/done/<loopId> ]; do sleep 20; done

Then read the result with opencode_loop_status. Never poll it in a loop of your own.

Briefing another agent to run a work package through the loop

You have an MCP server called opencode with a work/review loop (opencode_loop) that implements one work package, checks it against a mechanical gate and two rounds of independent review, and only stops when both agree — or hands the decision back to you when they can't.

Before your first call in this repo, check whether .opencode-loop.json exists at the repo root. If it doesn't, create it with this repo's real lint/test commands (look at package.json scripts, or the equivalent for this stack) — without it, the loop can run but its arbiter can never approve anything, because nothing objective ever verified the result.

Call opencode_loop with repoDir, a short wpId, and spec — the full work-package text, written the way you'd brief a competent engineer. Both the worker and every reviewer see spec verbatim, so vagueness there shows up later as either scope drift or a conformance round that can't tell what "correct" means.

Wait on the sentinel it returns, in one background shell command — do not poll opencode_loop_status in a loop of your own:

until [ -f <sentinel path> ]; do sleep 20; done

Read the result with opencode_loop_status. Three outcomes:

• completed — the gate passed and nothing survived adversarial review. The change is in the loop's worktree, on branch opencode-loop/<wpId>-... — review the diff yourself before merging; the loop verified conformance and mechanical correctness, not that the approach was the right one.

• escalated — read escalation.reason. arbiter-cannot-decide means a real judgement call is waiting in cannotDecide — that's the loop working correctly, not failing. max-iterations means it never converged; the partial work and the last iteration's surviving claims are usually more useful than a clean restart. Either way, the worktree and branch are left in place — do not let anything delete them until you've looked.

• failed — something broke before it could even try (bad repoDir, git worktree setup failed). Check escalation.detail.

You decide what happens to the worktree. Merge it, cherry-pick from it, or hand it back for another opencode_loop call with a refined spec if the escalation was about scope rather than correctness. The loop never merges anything itself.

Proactive local-backend health checks (src/scheduler/health.js)

The pool's own circuit breaker (see above) reacts to a request that actually FAILED. Against a backend that's down, a request doesn't fail fast — it HANGS: opencode run connects, gets nothing back, and sits there until the scheduler's 8-minute wedge-detection heartbeat kills it. Every routing path that tries the local model — the router's normal free-vs-local scoring, and the loop's explicit "try local first, else fall back" attempts — paid that 480-second tax every single time, whether it was the very first thing tried against a server that had been down for hours or the fifth retry against one still loading its weights.

The daemon now polls each local backend's /health endpoint (vLLM's convention; falls back to /v1/models, which any OpenAI-compatible server must serve, for one that doesn't implement /health) every 20 seconds, independent of whether any job happens to be in flight. A confirmed-down backend sets that pool's externalHealthy: false, which canAdmit() checks FIRST, before the breaker or slot logic — a pool a health probe just confirmed is down never gets a request dispatched to it at all, so nothing ever reaches the 8-minute heartbeat over it. null (never checked yet, or this pool isn't a monitored local backend) is treated as "try it" — optimistic, not paranoid, since the common case is a healthy server that simply hasn't been probed at the exact instant something needed it.

This is the single choke point for BOTH routing paths: the router's #eligible() filter already calls pool.canAdmit() for free routing, and an explicit model pin (the loop's "try local first" calls) goes through the same canAdmit() check — so opencode_loop's worker/arbiter/degraded-retry attempts all skip straight to the free fleet the instant local is known down, with zero wasted wait, rather than each independently discovering the same outage the slow way.

Current health is visible in opencode_queue_status's pools[].externalHealthy and in the daemon's raw status response; transitions (not every 20s tick) are logged to scheduler.log.

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).

QA lenses (src/lenses.js)

Reviewers don't get a vague theme ("look for correctness bugs"), they get one narrow, mechanically checkable instruction. That distinction matters more than it sounds: asked for "correctness bugs", a weak local model returns a wall of plausible prose restating the diff; asked to "check the EXACT operator against what the comment says the boundary should be, and trace what happens when the value is exactly at the boundary", it does real work. Narrow lenses also make N parallel reviewers genuinely diverge instead of producing N near-duplicates.

Six core lenses run by default:

Six more are available via lenses: "all" or an explicit subset: null_empty, error_handling, concurrency, contract_mismatch, state_consistency, test_gaps.

Every lens ends with the same reporting contract — file, location, what the code does vs should do, a concrete failing scenario (specific inputs → specific wrong output), and a severity — plus an explicit NO FINDINGS sentinel so "found nothing" is distinguishable from "rambled inconclusively".

Replicas, not a flat count. replicas (default 2, hard minimum 2) gives every selected lens that many independent reviewers. This replaced spreading a flat participant count round-robin, where some lenses drew 3 reviewers and others 2 — so "2+ participants agreeing = CONFIRMED" silently meant different things depending on which lens you got. With uniform replicas, corroboration is measured against a known denominator. Total participants = lenses × replicas, clamped to MAX_PARTICIPANTS. The legacy count param still round-robins if you'd rather cap total spend than get even coverage.

Project context. Every reviewer's prompt is prefixed with a domain/ architecture file — AGENTS.md, CLAUDE.md, CONTRIBUTING.md, or README.md, auto-detected, or set explicitly via contextFile. A reviewer that doesn't know "distributions count as an expense in this ledger" reports confident nonsense; a paragraph of domain context removes a whole category of false positives.

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 are reconciled into ONE report that 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. The results are reconciled into [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, every reviewer gets the same bounded prefix plus the paths left out (they have read access and can open those themselves) — see "QA lenses" above for how reviewers are actually assigned and diversified; this replaced an older per-file partitioning scheme that broke once replicas meant reviewers sharing a lens must see identical content for their agreement to mean anything.

Hierarchical aggregation (tree reduction, groupSize)

"ONE aggregator" above is a simplification for small N. Both reconciliation steps (round 0, and each adversarial reaggregation) actually run through a tree of aggregator calls, each combining at most groupSize sources (default 4) — not one aggregator reading every participant's output at once.

This exists because a flat aggregator's prompt scales with participant count × however verbose each one felt like being. Observed 2026-08-22: 12 lenses × 2 replicas (24 participants, ~7k chars each) produced a 162,000-character aggregator prompt that outran a 5-minute wait entirely — the local model never got through it, and the whole review silently came back as an empty report. Two fixes landed together:

• A hard per-source cap (6,000 chars) on what reaches any single aggregator call — a participant that rambles past this is truncated, not allowed to starve the rest.

• The tree reduction itself: leaf-level groups of groupSize participants each get reconciled into a partial report IN PARALLEL (they're independent — this also cuts wall-clock time, not just risk), then those partial reports are merged in the same way, recursively, until one report remains. Merge-level prompts are told explicitly to add up corroboration counts across partials rather than trust each partial's count as final — a finding at 2-of-4 in one partial and 1-of-4 in another is 3-of-8 combined, which is CONFIRMED overall even though neither partial alone reached 2.

Lower groupSize if aggregation still times out or comes back empty at a high replicas/lens count; raise it to trade fewer, larger aggregator calls for less merge overhead. This also means opencode_sweep's per-segment reconciliation scales with lens/replica count more gracefully than a flat aggregator ever could.

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.

opencode_sweep — auditing a whole codebase

opencode_audit reviews a diff. opencode_sweep reviews an entire repository, which needs three things a diff review doesn't.

Segmentation. The repo is split into token-budgeted segments (default ~40k tokens), packed by path rather than by size so a directory stays together. That's deliberate: bin-packing by size would scatter related files across segments and destroy exactly the findings that span them — a caller and callee disagreeing about a contract, two symmetric paths where only one was updated. A single file over budget gets its own segment rather than being cut mid-function.

A segment is a starting point, not a cage. Reviewers get their sector's contents inlined, and are explicitly told to follow a flow into any other file in the repo when tracing it end-to-end is what the lens requires — they have read access to everything. Findings outside the assigned sector are reported and flagged as such.

A findings ledger that feeds forward. After each segment, the reconciled report emits a compact machine-readable block that's parsed in plain JS into a running ledger. Every later segment gets that ledger with the instruction: don't re-report these, but do look for other instances of the same bug class — a confirmed pattern usually repeats. Refuted findings carry forward too, so a false positive dismissed in segment 3 isn't re-litigated in segment 12. The ledger is capped at the most recent ~40 entries so it can't crowd out the prompt on a long run.

Always dry-run first. plan: true spawns nothing and returns the file list, segment breakdown, and a job estimate:

opencode_sweep({ dir: "/path/to/repo", plan: true, lenses: "all", replicas: 4 })

Check fileCount, segmentCount, estimatedJobs, and the skipped counts before committing to a run — the estimate is how you find out a sweep would take six hours before it takes six hours.

Then trial one segment before committing to all of them. Pass maxSegments: 1 with the exact same lenses/replicas/maxConcurrency you're about to run for real — this exercises the complete pipeline (full lens fan-out, tree-reduction aggregation, the adversarial round, ledger emission) at real scale, in a fraction of the wall-clock time. It's how you find out your maxConcurrency is wrong for this backend, or that a lens is producing garbage, before spending hours discovering it one segment at a time. Once a single segment behaves the way you expect, drop maxSegments and run the whole thing.

File selection is language-agnostic and yours to override. Defaults exclude vendor/build dirs, lockfiles, minified bundles, and generated-code patterns (*.g.*, *.pb.*, *.generated.*, *.freezed.*); files are additionally sniffed for @generated / "DO NOT EDIT" headers, which catches generated code in any language that globs would miss. Override with sourceExtensions, includeGlobs, and excludeGlobs.

It runs in the background. A real sweep runs for an hour or more — far past any MCP client's request timeout — so opencode_sweep returns a sweepId immediately and opencode_sweep_status polls it. Full state is checkpointed to ~/.local/share/opencode-mcp/sweeps/<id>.json and the markdown report at <id>.md is rewritten after every segment, so partial results are readable while it runs and survive the process dying. Segments run strictly sequentially — parallelising them would break the ledger's whole purpose.

Polling shows real progress, not just "running." The active segment's phase field updates live at every meaningful transition — participant N/M finished, aggregator-tree level 1 group 3/6 done, entering the adversarial round — not just at segment start/end. A segment sitting at status: running for 40 minutes with phase visibly advancing is a healthy sweep; one where phase hasn't changed across several polls is worth investigating (check whether the model backend itself is actually responding — a network-level hang looks identical to genuine work from the outside if you're not watching this field).

Cancel it if it's not going well. opencode_sweep_cancel stops a running sweep — before it existed the only way was killing the whole MCP server process, taking every other tool down with it for the rest of the session. It checks cooperatively (between segments, and inside the current segment's concurrency-limited dispatch), so it typically responds within one wave — bounded by maxConcurrency — rather than only at the next segment boundary. It's an in-process signal, same constraint as opencode_cancel_job: it can only stop a sweep that the server process handling this call is itself running.

Briefing another agent to run a sweep

A prompt you can hand to another Claude Code session, verbatim, to have it sweep an unfamiliar project. It deliberately makes the agent choose the file filters itself rather than prescribing them — only the agent looking at the repo knows what's generated, vendored, or irrelevant in it.

You have an MCP server called opencode that can run a whole-codebase QA audit using a swarm of read-only agents. Use it on this repository.

Step 1 — decide what to review. Look at the repo layout first (top-level dirs, the manifest/build file, any .gitignore). Then work out which files are actually worth reviewing: application source, not generated code, not vendored dependencies, not build output, not fixtures/snapshots, not committed assets. Whatever this project's stack generates or vendors, exclude it.

Step 2 — dry run. Call opencode_sweep with plan: true, lenses: "all", replicas: 4, and your chosen sourceExtensions / includeGlobs / excludeGlobs. It spawns nothing and returns the file list, the segment breakdown, and a job estimate. Read the skipped counts and the segment list: if something important was excluded, or something generated slipped through, fix the filters and re-plan. Do not skip this step.

Step 3 — confirm scale, then trial exactly one segment. Report the plan back to me — file count, segment count, estimated jobs — and say roughly how long the full run would take. Then call opencode_sweep again WITHOUT plan but WITH maxSegments: 1 and the exact same lenses/replicas you intend to use for real. This exercises the complete pipeline (fan-out, tree aggregation, the adversarial round, ledger emission) at real scale in a fraction of the time — it's how you catch a wrong maxConcurrency, a misbehaving lens, or a backend that can't actually keep up, before finding out three segments into a six-hour run. Poll opencode_sweep_status while it runs (see below) and confirm the trial segment reaches completed, not incomplete or failed, before proceeding.

Step 4 — tune maxConcurrency if the trial showed trouble. If the trial segment came back incomplete (reconciliation never finished) or included "Unexpected server error" responses, the model backend couldn't keep up with the request volume — lower maxConcurrency (default 4) and re-trial rather than raising waitMs, which doesn't address the actual cause. If it finished cleanly and you know the backend can genuinely serve more concurrent requests, you can raise maxConcurrency instead of leaving capacity idle.

Step 5 — run it for real. Call opencode_sweep again without plan or maxSegments, same lenses/replicas/maxConcurrency that worked in the trial. It returns a sweepId immediately and runs in the background; there is NO notification when it finishes. Poll opencode_sweep_status with that sweepId periodically — the active segment's phase field updates live (e.g. "Reviewing: 30/48 participant(s) finished"), so you can tell real progress from a stall without waiting for a segment to complete. The reportPath it returns points at a markdown report rewritten after every segment, so it's readable while the sweep is still going. If something looks wrong mid-run, opencode_sweep_cancel stops it — you don't have to let a bad run finish just because it started.

Step 6 — report back. When status is completed, read the report file and summarise: the confirmed findings grouped by severity, which are worth acting on now, and which look like false positives to you. Do NOT fix anything yet — verify each high-severity finding against the real code yourself first and tell me which ones you actually believe, because a swarm of small models produces some confident nonsense and the point of your pass is to catch it.

Notes: replicas: 4 means every one of the 12 lenses gets 4 independent reviewers per segment — that's the redundancy that makes the confidence ranking meaningful, and it's why the job estimate is large. depth: 1 (the default) adds one adversarial round per segment that tries to refute single-source findings.

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.