Plan Mode vs. Build Mode

Plan mode: see the reasoning before you commit

In plan mode, OpenCode does not modify your codebase immediately. Instead, it reasons aloud: here's what the task requires, here are the files that need to change, here's a summary of the changes I'm about to make. The agent outputs this plan to you and waits for approval.

Only after you review the plan and explicitly say "okay, go ahead" does OpenCode enter a build phase where it actually modifies files, runs tests, and iterates. If you disagree with the plan ("no, don't touch the database schema yet, just the API layer"), you can reject it, refine the task description, and ask for a new plan.

Plan mode trades speed for transparency and control. The agent does more thinking upfront (reasoning about what to do before doing it), so you get to see the strategy before it's executed. You're not watching file-by-file changes in real time; you're looking at a high-level summary. If the plan is wrong, you catch it before any files are modified.

Build mode: direct modification with checkpoint safety

In build mode, OpenCode moves directly to implementation. It modifies files, runs tests, and iterates—much faster than plan mode because there's no "summarize and wait for approval" step. As soon as it has a plan (implicit, not written out), it starts acting.

Build mode is still iterative: if a change breaks tests, OpenCode observes the failure, adapts, and retries. But the iterations happen in the build phase, not in a separate planning phase. You see the result, not necessarily every intermediate step.

Build mode trades transparency for speed. The agent doesn't spend cycles writing out its reasoning; it just acts. This is better when you trust the agent's judgment, you want to move fast, or you're working on a task so straightforward that the plan is obvious. It's also better when the agent is iterating frequently (changing multiple files, running tests multiple times)—outputting a new plan after each test run would be tedious.

When to use plan mode

• Risky changes. If the task touches critical infrastructure, authentication, or data-persistence logic, use plan mode. You want to see the strategy before files are modified. Example: "refactor the payment processing pipeline."
• Large refactors. If the task might affect multiple systems or a lot of code, plan mode gives you a chance to say "no, that's too aggressive" before OpenCode starts. Example: "migrate from MySQL to PostgreSQL."
• New developers. If you're still learning how OpenCode works or learning the codebase it's modifying, plan mode gives you visibility into what the agent considers important. It's a teaching tool.
• Cross-team changes. If the code being modified is owned by another team or requires sign-off, the plan output is useful as documentation. It answers "what was the agent planning to do?"

When to use build mode

• Well-scoped, low-risk tasks. If the task is straightforward and isolated ("add a new utility function," "fix a typo in docs," "update dependencies"), build mode is faster and fine.
• Iteration-heavy work. If you expect the agent to fail the first time and iterate (change, test, adapt, retry), build mode avoids plan-plan-plan overhead. The agent acts and adapts without writing plans in between.
• Tight feedback loops. If you're running the agent many times a day in CI/CD or as part of a bot, and you've already validated that it works well, build mode is the faster path.
• Cost-conscious runs. Plan mode involves extra model calls (one to reason about the plan, then more to execute it). If you're optimizing for cost, build mode is cheaper.

A concrete example: feature addition in plan mode

Task: "Add a 'mute notifications' toggle to the user settings endpoint."

Plan mode output:

I've analyzed the codebase. Here's my plan:

1. Database schema: Add a `notifications_muted` boolean column to the users table.
2. API route: Add a PATCH endpoint at `/users/:id/settings` that updates this field.
3. Tests: Add two test cases—one for enabling, one for disabling the toggle.

Files that will be changed:
- migrations/add_notifications_muted.sql (new)
- src/routes/users.ts (modify)
- tests/users.test.ts (modify)

Ready to proceed?

You see this plan. You notice: wait, we already have a settings endpoint at /settings/preferences. The agent should use that, not create a new endpoint. You provide that feedback, and OpenCode generates a new plan that routes through the existing endpoint instead.

Only after you approve does OpenCode start modifying files.

A concrete example: the same task in build mode

Build mode execution:

OpenCode reasons internally (not printing it) and starts:

1. Modifies the database migration file
2. Modifies the API route handler
3. Runs the test suite

The test suite fails because... (some reason). OpenCode observes the error, adapts its route logic, and retries. Eventually tests pass.

You see:

✓ Task completed
- 3 files modified
- All tests passing

No intermediate reasoning output, no wait for approval. But if you disagree with what it did, you only find out after the fact, by reviewing the diffs.

The hidden cost of plan mode: model calls

Plan mode uses more API calls (and thus more tokens, more latency, more cost). The agent calls the model once to generate a plan, then again to implement it, then potentially more times if you iterate on the plan. Build mode is just implement-test-adapt, typically fewer model calls per task.

For a provider where you're paying per token, this adds up. But for many teams, the safety value of plan mode outweighs the extra cost, especially on high-stakes changes.

Common mistake

Using plan mode for everything because you want to be "safe." Plan mode isn't automatically safer—it's safer if you actually review and understand the plans, and it introduces friction that can slow down productive workflows. Use plan mode where it genuinely adds value (big refactors, team sign-offs, learning), and use build mode for the tasks where it's overkill. Choosing the right mode is like choosing the right code review rigor—match it to the actual stakes, not a universal "be maximally cautious" rule.