OpenCode Plan/Build Mode: Making AI Show You the Plan Before Touching Your Code

Have you ever asked an agent to "just fix this one function," only to discover later that it had quietly changed unrelated files too? I've been there. The moment I found that a perfectly working auth logic had been subtly altered right before a deployment — that's when I became pretty sensitive about the "execution scope" of AI agents.

This isn't just a personal problem. As AI coding tools become mainstream, one of the most common complaints is "it changed things I didn't want changed." The core issue is that there's no way to know in advance what the agent is about to do. It dives straight into execution without a plan, and you only realize something went wrong after it's already modified 20 files in the wrong direction.

OpenCode addresses this problem with a design that clearly separates Plan mode and Build mode, forcing the AI to show its intent before touching any code. For developers comfortable in the terminal who have already used AI coding tools, you'll immediately understand how much of a difference these two modes make on complex tasks. With over 85% of all developers using AI tools regularly and approximately 46% of newly written code being AI-generated (Stack Overflow Developer Survey 2025), the question of "how can we safely trust AI" is becoming increasingly important.

Core Concepts

Plan Mode: The Architect Thinking Phase

Plan mode is a read-only analysis phase. In this mode, OpenCode explores files, understands the codebase, and presents a step-by-step implementation plan — but it does not actually write files or execute commands. Internally, this works by disabling the tool calls corresponding to file writes and shell execution. Rather than restricting the AI's behavior at the system prompt level, the actual list of available tools changes. So if you say "delete this file" in Plan mode, OpenCode is physically incapable of doing it.

Think of it like a design meeting where you're only drawing on a whiteboard — hands off the keyboard, using only your head. I've developed a habit of always entering Plan mode first to check "which files will be affected" before adding a complex feature, and it's quite useful for immediately correcting course when an unexpected file shows up on the list.

The essence of Plan mode: A read-only phase where tools for writing, deleting files, and executing commands are disabled. The AI takes on an "architect" role, exploring the codebase and proposing an implementation strategy first.

You can toggle between Plan mode and Build mode with a single Tab key. When you request a complex feature in Plan mode, OpenCode analyzes the current code structure and first shows you the list of affected files and the order of changes. At this point, you can give feedback like "this part isn't what I wanted," adjust the plan, or request an entirely different approach — all while not a single line of code has been changed yet.

Build Mode: The Senior Engineer Execution Phase

Build mode is the default mode. It's the "senior engineer" role with full access to all tools — reading/writing/deleting files, running shell commands, and more. After thoroughly reviewing the plan in Plan mode, you press Tab again to switch to Build mode, and OpenCode implements the discussed plan into actual code.

OpenCode can be installed via npm or pnpm, per the official GitHub repository.

# pnpm environment
pnpm add -g opencode-ai
 
# npm environment
npm install -g opencode-ai
 
# Run from your project directory
cd my-project
opencode
 
# Once the terminal UI launches, press Tab to switch between Plan/Build mode (default is Build mode)

The Deliberate Pause Between Intent and Execution

The core value between the two modes is the deliberate pause. It's not simply "plan then execute" — it's a structure that forces the AI to explicitly express what it intends to do first.

Honestly, at first I thought, "why bother splitting it into two steps?" I figured it should just implement things directly. But when dealing with complex features, this matters quite a bit. When the AI says upfront "I'll change things in order A → B → C," the developer can verify whether that plan matches their intent. Without a plan, if it just starts executing, you only realize something was wrong after it's already modified dozens of files in the wrong direction.

OpenCode is also a vendor-neutral tool not tied to any specific LLM provider. You can connect to over 75 providers — including OpenAI GPT, Google Gemini, and Ollama (for local execution) — through Models.dev. Notably, in January 2026, Anthropic took action to restrict direct use of Claude models within OpenCode, citing that OpenCode was accessing the models in a way that conflicted with API usage policies. The project now officially guides users on connecting Claude via proxy providers like OpenRouter as a workaround.

Practical Applications

Example 1: Adding a Complex Feature — Implementing OAuth2 Social Login

This is a situation you frequently encounter in real work. Adding social login to an existing auth system involves middleware, DB schema, and session handling all tangled together, and it's often hard to know where to start.

# Enter Plan mode (Tab key)
> I want to add GitHub OAuth2 social login to the current JWT-based auth system.
  I'd like to use passport.js — analyze how to integrate it without conflicting with the existing middleware.

Here's roughly what OpenCode responds with in Plan mode:

✦ Analysis of current auth middleware structure complete
✦ Affected files:
    - src/middleware/auth.ts       (add passport strategy)
    - src/routes/auth.ts          (new OAuth callback route)
    - prisma/schema.prisma        (add provider column to User table)
    - .env                        (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET required)
✦ Implementation order:
    1. Install passport-github2 package
    2. DB schema migration
    3. Configure passport strategy
    4. Implement callback route
    5. Connect with existing JWT middleware

At this point, you can make adjustments like "swap the order of steps 3 and 4" or "I'll handle the DB schema myself, just do the rest." Not a single file has been changed yet.

Once you're happy with the plan, press Tab to switch to Build mode and start the implementation.

# After reviewing the plan, press Tab to switch to Build mode
> Proceed as planned. Include the DB schema changes too.
 
# Actual file modifications begin in Build mode
# The terminal shows which files are being changed and how at each step

Example 2: Analyzing Legacy Code and Forming a Refactoring Strategy

Plan mode particularly shines when refactoring a legacy codebase. Since you can explore vast amounts of code without actually touching it, it's perfect for understanding "what this code affects and to what extent."

# In Plan mode
> Analyze the entire src/services/ directory,
  identify any service files with God Object patterns,
  and suggest a separation strategy.

✦ UserService.ts — 2,847 lines, 14 dependencies (separation recommended)
✦ Proposed separation:
    - UserAuthService       (8 auth-related methods)
    - UserProfileService    (12 profile-related methods)
    - UserNotificationService (6 notification-related methods)
✦ Estimated affected files: 23
✦ Recommended order: Auth → Profile → Notifications (reverse dependency order)

OpenCode reads and analyzes the code but does not modify it. You can review each service's dependency graph, separation criteria, and estimated workload before entering Build mode. In Plan mode, you can also drag and drop design diagrams or UI screenshots for visual mockup-based discussions like "I want to separate it into this component structure — how should I approach it from the current code?"

Example 3: Multi-Session Parallel Development

Multi-session support, available since v1.3.0, is useful when developing frontend and backend simultaneously. If one session changes the backend API response structure while another session develops the frontend consuming that response, the overlapping scope of changes can create conflicts. By starting both sessions in Plan mode first to check "the list of files I'll be touching" and verifying there are no overlapping files before switching to Build mode, you can catch these conflicts preemptively.

# Terminal window 1: Backend API work
cd my-project
opencode
# → Confirm API change scope in Plan mode first, then switch to Build
 
# Terminal window 2: Frontend component work
cd my-project
opencode
# → Confirm frontend change scope in Plan mode
# → If no file overlap with the backend session, switch to Build

For multi-session CLI options such as session naming, it is recommended to check the official documentation for the latest syntax.

Pros and Cons Analysis

Advantages

LSP (Language Server Protocol) is a standard protocol that provides language-specific code analysis features in an editor-independent way. MCP (Model Context Protocol) is a protocol that standardizes how AI models interact with external data sources and tools. OpenCode's support for both means it can analyze code with language context and leverage DBs or external APIs as context.

Drawbacks and Caveats

The Most Common Mistakes in Practice

1. Jumping straight into complex tasks in Build mode: A single-line fix is fine, but starting a multi-file feature addition or refactoring without Plan mode makes cleanup difficult later. If you're unsure about the scope, it's recommended to go through Plan mode first.

2. Switching to Build without actually reviewing the Plan mode output: The value of Plan mode isn't just that it shows a plan — it's that you can give feedback on that plan. It's important to actually read the "list of affected files" and check whether any unexpected files are included.

3. Insisting on the same LLM provider for all tasks: The model optimal for code generation may differ from the one optimal for code analysis. A good approach is to divide responsibilities — using a cost-effective local model (Ollama) for Plan mode analysis, and a more powerful model for actual implementation in Build mode.

Closing Thoughts

The trustworthiness of an AI agent depends less on "how well it writes code" and more on "whether it shows what it intends to do before executing." OpenCode's Plan/Build mode separation is a design that structurally embodies this principle, and its effect becomes more pronounced the more complex the task.

Three steps you can start with right now:

1. Install with pnpm add -g opencode-ai (or npm install -g opencode-ai), then run opencode from your current project directory. Starting with an Ollama local model lets you have your first experience without any API costs.

2. When the terminal UI opens, don't jump straight into Build mode — press Tab to enter Plan mode and ask "analyze the structure of this project and tell me the 3 areas most in need of improvement." No files will be changed at all, so you can explore freely.

3. Pick one of the suggestions from Plan mode, review the plan, then press Tab to switch to Build mode and experience the full flow through to actual implementation. Once you try it yourself, you'll clearly understand what it feels like to make the AI speak first.

References

Official Documentation

• OpenCode Official Docs - Modes
• Modes | opencode (dev docs)
• OpenCode GitHub Repository
• OpenCode: A model-neutral AI coding assistant - Red Hat Developer

Community References

• Plan Mode vs Build Mode for Reliable AI Coding - Educative
• OpenCode vs Claude Code vs Cursor: Complete Comparison 2026 - NxCode
• OpenCode Deep Dive: Provider-Agnostic AI CLI in 2026 - sanj.dev
• OpenCode 사용법 가이드 - Kanaries (한국어)
• OpenCode 플랜→빌드 워크플로우 완전 가이드 (한국어)
• Opencode Core Modes - Plan and Build Explained