Playbooks · Coding tasks
Have one agent write the code and a second agent check it in the background
Written October 30, 2026
For a solo developer with one coding task in OpenCode 2.0: a builder agent writes the code, and a reviewer agent, on a different model, reads it in the background and never edits it. Code that ships unchecked can reach users with a defect nobody caught, and a reviewer on the same model mostly repeats the builder's mistakes.
What the pair is
OpenCode 2.0 runs subagents and shell commands in the background while you keep working, and Ctrl+B moves a running foreground task to the background. A subagent is a separate agent the main agent starts to handle one independent piece of work, which then reports back a short summary. Background subagents can use a different model from the main agent, which is what makes this pairing possible: the builder and the reviewer do not share a model's blind spots. The docs list background subagent tasks as an experimental feature, enabled with OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS, and Code Mode — a JavaScript interpreter the docs describe for chaining tool calls in one script — as a separate experimental feature, enabled with OPENCODE_EXPERIMENTAL_CODE_MODE. The stated aim of background work is overlapping work: a long test run or review continues while you keep prompting. That is a design aim, not a measured result, and this page claims no time saving.
Two rules make the pair worth running. First, the reviewer uses a different model from the builder. Second, the reviewer never edits. A reviewer that edits is a second builder, and a reviewer on the same model is the builder reading its own work twice.
Before you start
Work on a branch or a copy, not on your main line. Pick one task with a visible result — a small feature plus a test that passes — and write down what "done" means before either agent starts: the files it may touch, the test that must pass, and the one behaviour the task must not break.
Steps
- Move to OpenCode 2.0 if you are still on 1.x. The docs describe upgrading from the latest 1.x release with:
opencode upgrade --major
- Create the reviewer as a subagent that cannot edit. The docs describe creating an agent with:
opencode agent create --mode subagent --model provider/model --permissions read,glob,grep --description "Review code for defects; report findings; do not edit files."
provider/modelwith a model from a different provider than the builder's. Permissions you leave out are denied, so leavingeditandbashout of the list is what keeps the reviewer read-only. Runopencode agent listand confirm the reviewer appears with the model and permissions you set. - Give the builder the task, and send it to the background. Start the builder on the task from step "Before you start". If a foreground task turns out to be slow, Ctrl+B moves it to the background instead of cancelling it. While it runs, keep working on something else — do not watch the builder and do not edit its files mid-run.
- Plant one defect before the review. After the builder finishes, introduce one known defect yourself — a wrong boundary condition, a missing check, a swapped argument — and note it in a file outside the project folder, for example in your home folder, where the reviewer cannot read it. The reviewer was only allowed read, glob and grep inside the project, and anything you leave out of its permissions is denied, so a note left inside the project is visible to it. This is the test of the review: a reviewer that cannot find a defect you planted is not a safety net yet.
- Send the diff to the reviewer, not the whole project. Ask the reviewer to read the builder's changed files and report findings ordered by severity, each with a file and line, why it matters, and a concrete fix. The reviewer reports; it does not apply fixes.
- Record the outcome, then resolve conflicts yourself. Write down four things: whether the builder finished, whether the reviewer finished, where the two disagreed, and whether the reviewer caught the planted defect. Where builder and reviewer disagree, you decide — the reviewer is advice, not a second vote that outranks you. Apply the fixes you accept, re-run the test, and remove the planted defect only after the reviewer has had its chance at it.
What can go wrong
- Reviewer on the same model as the builder. Same-model review mostly repeats the builder's reasoning, including its mistakes. Different models disagree more often, and disagreement is where review earns its place.
- Reviewer with edit permission. A reviewer that can edit will fix things silently, and silent fixes hide what the builder got wrong. Keep edit denied and let fixes go through you.
- Reviewing the whole project instead of the diff. A full-project review returns generic findings and buries the changed code. Scope the review to the builder's diff and the test.
- A background task nobody collects. Background work finishes quietly. If no step collects the result, the review never happens and the builder's code ships without review. The record in step 6 is the collection step — do not skip it.
- A planted defect that is too easy or too hard. A typo proves nothing; a defect only an expert in the codebase would spot proves nothing either. Plant the kind of defect you actually worry about shipping.
Limits
- This pairing catches defects in one task's diff. It does not review architecture, and it does not replace running the test suite.
- Background subagents are experimental in the docs, so their behaviour can change between releases. Re-read the docs after an upgrade before assuming the same setup still works.
- The pair adds a second model's cost to every task. That cost is only worth it on work where a missed defect costs more than the review.
Related playbooks
- Measure what Claude Code's background-agent summaries cost you, and decide what to turn off
- OpenCode 2.3.0: subagents move to the background
- Use your own Anthropic API key with an agent: what it costs, and the billing trap to check first
- Check where your coding agents store API keys on your own machine
Sources
- https://opencode.ai/docs/cli/
- https://explainx.ai/blog/opencode-2-0-code-mode-background-agents-shared-server-sdk-upgrade-guide-2026
- https://aitoolsreview.co.uk/insights/opencode-2-0-shared-service
Back to: Coding playbooks hub · Also: Migrate OpenCode 1.x to 2.0