Chapter: 9 — OpenCode’s Unique Contributions Book Title: Claude Code VS OpenCode: Architecture, Design and The Road Ahead Model: openai/gpt-5.4 Token Usage: ~2,750 tokens Generated: 2026-04-01

9.5 Plan Mode

OpenCode’s plan mode is a deceptively simple idea with profound implications for agent safety and workflow design. Rather than treating planning as a soft instruction inside a general-purpose agent, OpenCode gives planning its own agent identity, its own permission profile, and its own transition mechanism. The relevant files include packages/opencode/src/tool/plan.ts and the built-in agent definitions in packages/opencode/src/agent/agent.ts.

The key principle is straightforward: plan first, execute later. But OpenCode turns that principle into runtime structure. In agent.ts, the built-in plan agent is defined separately from the default build agent. Its description is explicit: “Plan mode. Disallows all edit tools.” The permission rules confirm this. Under the plan agent, edit is denied broadly, with narrow exceptions only for plan files stored under approved plan paths. This means planning is not merely encouraged; file modification is structurally constrained.

This is important because many agent systems rely on prompt wording alone to preserve a planning phase. The model is told to think before acting, or to propose a plan before editing files. That works sometimes, but it remains probabilistic. OpenCode instead adds an operational boundary. The planner can inspect, search, reason, and write the plan artifact itself, but it cannot casually drift into implementation. In effect, plan mode is a read-only exploration mode with a limited write target for planning output.

In computer science terms, this is a capability restriction. A capability is the set of actions a process is permitted to perform. By changing the capability set of the agent, OpenCode changes behavior more reliably than prompt-only instruction can. This is an important design lesson for AI systems: when behavior matters, prefer enforceable constraints over advisory text.

tool/plan.ts shows the transition side of the design. The PlanExitTool asks whether the user wants to switch from the completed plan to the build agent and begin implementation. If approved, OpenCode creates a synthetic user message targeting the build agent and instructing it to execute the approved plan. This is elegant for two reasons. First, it keeps plan and execution as separate phases in the session history. Second, it provides an explicit handoff from analysis to action.

That handoff is more valuable than it may seem. One of the persistent problems in coding agents is action leakage: the system begins researching, then makes a small change, then another, and soon the distinction between exploration and implementation disappears. That can lead to premature edits, shallow solutions, or user distrust. OpenCode’s plan mode creates a formal checkpoint. The planning phase concludes, the plan is reviewed or accepted, and only then does the execution-capable agent take over.

This is especially useful for larger engineering work: refactors, migrations, debugging with uncertain root causes, architecture changes, or any task where early edits are risky. A read-only planning agent can inspect the repository, compare options, map dependencies, and propose sequencing without the temptation to “just start patching.” The result is often better strategy and fewer reversible mistakes.

Compared with Claude Code, this is a noteworthy distinction. Claude Code certainly supports planning behavior, but OpenCode makes planning an explicit runtime mode with hard permission boundaries. Oh-My-OpenCode, in turn, expands orchestration and specialized agents, yet this foundational plan/build split originates in OpenCode itself. It is part of the host’s core design vocabulary.

Plan mode also reflects a broader principle in agent architecture: not every cognitive phase should have the same action privileges. Research, planning, execution, review, and summarization are different kinds of work. If they all share the same tool permissions, the system becomes simpler to implement but harder to control. OpenCode shows that even a minimal agent platform can benefit from phase-specific agents.

There is an educational angle here as well. Human engineers often work best with the same separation. We investigate first, design second, implement third, and review fourth. Experienced developers know that collapsing those phases can save time on trivial tasks but create chaos on serious ones. OpenCode encodes that mature workflow into software.

The larger lesson for future agent systems is clear. If planning truly matters, do not merely ask for it in prose. Give it a protected mode, a separate permission set, a dedicated artifact, and an explicit exit path. OpenCode’s plan mode is not flashy, but it may be one of the cleanest examples of how to turn good engineering process into enforceable agent behavior.