opencode Fusion

Overview

opencode Fusion is a configuration project, not an app. It implements the Devin Fusion sidekick pattern: a main agent that plans and reviews but cannot edit files, and a cheaper sidekick that executes every change.

The main agent’s file editing is denied at the permission layer. Its only way to change a file is to hand a spec to the sidekick. Frontier intelligence stays on the plan and the review; mechanical work stays cheap.

This page is the short version. The README is the canonical reference — full setup, provider examples, FAQ, and the complete troubleshooting list live there.

How it works

One cycle: main explores (via helpers), plans, hands the sidekick a spec, reviews the diff, loops until it passes, then delivers.

Pick main and sidekick from different model families when you can. The main agent’s review of every sidekick diff becomes cross-vendor for free.

Enforced vs. advised

The pattern’s guarantees live in two layers. Knowing which is which answers most “what if the model just ignores the instructions?” questions.

Enforced — the permission layer

OpenCode checks these on every tool call, regardless of what the model reads or intends. The main agent’s edit, grep, glob, and list are denied — denied tools are removed from the model’s tool schema entirely, so there is no edit tool for it to decline to use. Bash is deny-by-default with a short verify/git allowlist, and delegation is bounded by an explicit task allowlist. The executors cannot commit or push — git commit and git push are denied for the sidekick and design agents, the main agent needs per-command approval for both, and force/mirror/delete-ref pushes are denied outright. If the main agent “won’t delegate,” the result is visible inaction — never a silent bypass.

Advised — the prompt layer

Spec precision, diff-review rigor, cost discipline, and skill usage are instructions in the agent prompts. Skills load at the model’s discretion in OpenCode — nothing can force an agent to read or apply one — which is exactly why no guarantee depends on them; the skill in this repo is just the installer. Slacking here costs quality or tokens, never an unauthorized edit.

Auditable

The optional fusion-audit plugin logs the delegation tree and aggregates per-agent token usage per session, and OpenCode’s session DB records every agent’s actual tool calls — “did it really delegate?” and “where did the tokens go?” are checkable from recorded data.

Install OpenCode

Fusion lives in your global OpenCode config. No build step; nothing to clone into each project.

Recommended

1. Install the skill globally with one command (no clone required).
2. Say set up fusion — or run /fusion-setup. Skills are discovered on demand, so no restart is needed for this step.
3. Restart OpenCode when the skill finishes — the config it writes loads at startup.

npx skills add mihneaptu/opencode-fusion --skill fusion-setup -g -a opencode -y

Installs into your global OpenCode skills folder. Works on Windows, macOS, and Linux. Requires Node 20.12 or newer — on older Node the installer crashes with a styleText error (see Troubleshooting).

Offline / manual fallback

From a clone of this repo, copy .opencode/skills/fusion-setup into ~/.config/opencode/skills/ (Windows: %USERPROFILE%\.config\opencode\skills\), then run the setup flow as above — skills are discovered on demand, no restart needed.

After setup

The skill writes ~/.config/opencode/opencode.json, installs agent prompts under ~/.config/opencode/agent/, and asks you to restart. To change models later, say “reconfigure fusion” or edit the config directly.

Subscription profiles

On a subscription? Name it during setup — or run /fusion-setup opencode-go — and the skill starts from a bundled profile, a ready-made role-to-model mapping, instead of interviewing you per role. Authentication stays out-of-band via opencode auth login (or /connect): profiles carry no keys, and the skill never asks for one in chat.

Every pick stays overridable, and model lineups rotate — the README’s profiles section is canonical for the full role tables and caveats.

Verify

Open any project that has some lint errors and ask:

fix the lint errors in this project

• Main delegates via task; sidekick edits; main runs the project’s own lint or test command (for example npm run lint) itself to verify.
• Main must not edit files directly — edits and freeform shell are denied at the OpenCode permission layer.
• An occasional struck-through command with a permission error is expected — bash is deny-by-default, and the agent recovers by reading the file or delegating. A denied command is the guardrail working, not the setup failing.

Customize

Models live in ~/.config/opencode/opencode.json under agent.<role>.model; role behavior lives in the agent prompts under ~/.config/opencode/agent/. Edit either, then restart OpenCode — config loads at startup. Keep the sidekick cheaper and faster than main when you can.

The README covers the rest: swapping models per provider, adjusting the main agent’s bash allowlist (keep "*": "deny" first; run one command per call — a chained line is matched segment by segment and one denied segment denies the whole call), optional hardening keys, and uninstalling (say undo fusion; it restores your pre-Fusion config and removes only what it installed).

Troubleshooting

If you installed the optional /fusion-status command, run it first — it checks the usual suspects in one shot: live enforcement in the running session, the config on disk, and the installed agent files. It only reports; it changes nothing.

Install crashes with a styleText SyntaxError

Node is too old for the installer. Since skills@1.5.16, Vercel's CLI needs Node 20.12+ even though the package still claims Node 18 support (vercel-labs/skills#1672). Fix any of three ways: upgrade Node (18 is end-of-life), pin the last compatible installer with npx skills@1.5.15 add mihneaptu/opencode-fusion --skill fusion-setup -g -a opencode -y, or use the offline fallback in Install — the skill itself has no Node dependency.

Main agent edits files directly

Config was not loaded. Fully quit and restart OpenCode. Confirm edit: deny in the installed ~/.config/opencode/agent/build.md frontmatter.

More cases — sidekick never invoked, model 404/400, a blocked bash command, searches missing gitignored files — are in the README’s troubleshooting section.

Limitations

• No dynamic mid-session routing. Model per role is fixed at startup. Devin’s mid-task model swap needs a closed product runtime and is an explicit non-goal here.
• Config loads at startup. Any change to config or agent prompts needs a full restart.
• Loop protection is permission-based. Nested delegation is bounded by the task graph (sidekick may spawn only read-only searchers), not numeric depth caps.

FAQ

What happens when the sidekick can’t satisfy the spec?

The main agent escalates on a ladder: feedback naming the specific miss, then — after two misses — it authors the exact patch itself (file, line range, verbatim code) and hands it over to apply. A verbatim patch needs no judgment, so the loop cannot deadlock; you lose the cost saving on that one task only. If even the dictated patch fails verification, the plan is wrong, not the sidekick — the main agent revises the plan.

What if agents ignore the prompts or never load the skills?

You lose quality, not guarantees — see Enforced vs. advised. Delegation is not a behavior the main agent chooses: its edit and search tools are removed from its tool schema, so handing work to the sidekick is the only path to changing a file. The fusion-audit plugin and OpenCode’s session DB record what every agent actually did.

How is this different from superpowers or other orchestration?

Different layer. Skill libraries like superpowers teach agents how to work — process knowledge the model can still ignore. Fusion configures what agents can do at the permission layer, and adds per-role model routing for cost with cross-vendor review as a side effect. No framework, no code — just configuration on a normal session. The two compose: superpowers supports OpenCode, so its skills can run inside a Fusion setup.