OpenCode Plan vs Build Mode

Use Plan to understand a change before carrying it out; use Build when you are ready to implement and verify it. What older tutorials call “modes” is now configured through OpenCode’s primary agents. This page keeps the existing URL so saved links still work.

The behavior below was checked against the official agents reference on October 2, 2026. OpenCode Tutorial is an independent guide.

Plan vs Build: which should you use?

Task	Starting point	Useful result
Understand an unfamiliar repository	Plan	Relevant files and a description of the current behavior
Compare implementation choices	Plan	A proposed approach with tradeoffs and affected files
Implement an agreed change	Build	A code diff and validation results
Investigate a failing test	Plan, then Build	A diagnosis, a targeted fix and a passing test
Review a completed change	Plan	Findings and questions about the diff

Build is the default primary agent and has all tools enabled. Plan restricts actions: the official defaults ask for approval before file edits and bash commands. Project or global permissions can change those defaults, so inspect your configuration if behavior differs from this table.

Plan should not be treated as an unconditional guarantee that no command or edit can run. If you need that behavior, configure explicit restrictions.

How to switch between Plan and Build

In the terminal interface, press Tab to cycle between primary agents and check the agent name shown in the interface. A customized keyboard configuration may use a different switch_agent binding; see keybindings.

Switching agents does not execute a proposed plan by itself. Give Build an explicit implementation request after you have reviewed the proposal.

A practical workflow

For example, suppose a settings page loses changes after refresh. Start in Plan with a focused request:

bash

Trace how the settings page saves preferences. Identify why a saved value
could disappear after refresh. List the files involved and propose a fix.
Do not implement it yet.

Review whether the diagnosis explains the observed failure. A useful plan identifies where state is stored, how it is read on startup, and which test would reproduce the bug. A long list of generic best practices is less helpful than those concrete answers.

Switch to Build and request the agreed change:

bash

Implement the proposed persistence fix. Keep the change limited to the
settings flow. Run the relevant existing tests and explain the resulting diff.

Before accepting the result, reproduce the original issue, inspect the diff and verify that the tests cover the failure. The agent’s statement that it is finished is not a substitute for those checks.

Configure stricter Plan permissions

Merge this into your existing opencode.json when you want Plan to deny both edits and shell commands:

bash

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

This is an explicit override, not the built-in default. It also prevents Plan from running shell-based inspection and tests. If you want to decide case by case instead, use "ask" for the relevant permission. See permissions for the full configuration model.

Migrate an older mode configuration

Older examples on this site used a top-level mode configuration and .opencode/modes/. Current instructions use:

agent in opencode.json for agent configuration.
.opencode/agents/ for project Markdown agent definitions.
~/.config/opencode/agents/ for global Markdown agent definitions.
switch_agent for the switch keybinding.

Back up your old configuration and migrate its intent rather than copying unsupported keys into a new file. The agents guide covers primary and custom agents; check the official reference when using a newer release.

Common questions

Does Plan write files?

Its default edit permission asks first. To prohibit edits, set agent.plan.permission.edit to "deny". Check project overrides as well as global configuration.

Why can Build still ask for permission?

Tool availability and permissions are separate considerations. Project policies or your own configuration can require approval for specific actions even while using Build.

Which mode fixes an LSP problem?

Switching to Build does not automatically enable language servers. Follow OpenCode LSP setup and troubleshooting to check configuration and server prerequisites.

If the application is not installed yet, start with the installation guide.