HowToCodePage

Plan mode versus build mode

Use the read-only agent to get a plan you can argue with before any file changes, and switch to build only when the plan is right.

Two agents, two postures

OpenCode ships two primary agents. The build agent has the full tool set and will edit files and run commands. The plan agent is restricted to reading, searching and reasoning - it can look, but it cannot change anything. Switching between them is a single keystroke, and that keystroke is the cheapest safeguard in the whole tool.

# in the TUI
<Tab>            # toggle between the build and plan agents

# or pick explicitly
/agent/build
/agent/plan
Aspectplanbuild
Read files and searchYesYes
Edit or write filesNoYes
Run shell commandsLimitedYes
Typical useUnderstand, design, reviewImplement, fix, refactor
Cost of a mistakeA wrong paragraphA wrong commit
⚠️
The failure mode plan mode prevents is the confident rewrite. An agent that has read three files out of forty will cheerfully restructure the module it has not read. Making it produce a plan first forces the gap between what it knows and what it assumes into the open, where you can see it.

A plan-first workflow

  1. Switch to plan mode and state the outcome, not the implementation: what should be true when this is done.
  2. Ask for the plan as an explicit list of files with the reason each one changes.
  3. Challenge the plan. Correct the file list yourself - this is far cheaper than correcting edits.
  4. Ask what could break and which tests cover it. A plan with no blast-radius answer is incomplete.
  5. Switch to build mode and ask for step one only. Review, then continue step by step.
> [plan] Add rate limiting to the public API.

Expected shape of the answer:
1. The files it will touch and why
2. Where the counter lives and how it resets
3. What happens when Redis is unavailable
4. Which existing tests need updating
5. What it will NOT change

Then stop. Do not edit anything.

Point five matters more than it looks. Asking what will not change is the fastest way to catch a scope explosion, because an unconstrained agent will usually volunteer the extra refactor.

Tuning the agents

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "model": "anthropic/claude-opus-4-1",
      "temperature": 0.1,
      "tools": { "write": false, "edit": false, "bash": false }
    },
    "build": {
      "model": "anthropic/claude-sonnet-4-5"
    }
  }
}
  • Pin the plan agent's model explicitly if you want the strongest reasoning reserved for design.
  • Disabling write, edit and bash on the plan agent makes read-only a property of the configuration rather than a promise.
  • You can define additional agents with their own prompts and tool sets for recurring roles, such as documentation or test writing.
  • Set temperature low for planning - you want the same answer twice for the same question.
opencode run --agent plan "list the files that would need to change to add pagination"

FAQ

Do I have to use plan mode for small changes?
No. For a one-line fix in a file already in context, planning is pure overhead. The rule of thumb is to plan when the change spans more than one file or when you cannot name the files yourself - those are exactly the cases where the agent's assumptions are most likely to be wrong.
The plan looked good but the build went wrong. Why?
Usually the plan was approved without checking the file list, so the build inherited an incomplete understanding. Review each step's diff before letting the agent continue, and send it back to plan mode when a step reveals the design was wrong.

Project context and instruction files Sessions, snapshots and undo

Last refreshed 2026-09-18.