“Agent” is one of the most overloaded words in AI right now. It means something different depending on who’s using it. In OpenCode, it has a specific meaning: an agent is a specialized assistant configured for a particular task or workflow — with its own instructions, tools, and permissions.
OpenCode ships with two built-in agents: Plan and Build.
The Plan agent
Plan is a read-only conversational agent. It can read your files and discuss your project, but it won’t make any changes. No files written, no commands run, nothing modified.
You already set "default_agent": "plan" in your global config back in the Configuration lesson, so every new session starts here. That’s intentional — you think first, then act.
That said, Plan mode is an instruction to the model, not a hard sandbox. Occasionally the agent may still make API calls or run commands that have side effects, so it’s not a guaranteed protection against unintended changes.
Use Plan when you want to:
- Think through an approach before committing to it
- Explore options and trade-offs
- Ask questions and do research
- Arrive at a clear plan before touching anything
Plan is still the right place to think things through — just don’t treat it as an ironclad guarantee that nothing will change.
The Build agent
Build is the implementation agent. It has full access — it can read files, write files, run shell commands, and make changes. Once you’ve thought things through in Plan and know what you want to do, switch to Build to carry it out.
How to switch
In OpenCode Desktop: use the dropdown below the prompt input to switch between Plan and Build.
In the TUI: press Tab to alternate between Plan and Build.
The recommended workflow
Since Plan is your default, every session already starts safe. For quick, straightforward tasks you can switch straight to Build. But for anything complex or unfamiliar, staying in Plan first is a good habit. It gives you a chance to think out loud with the agent, catch problems early, and arrive at Build with a clear direction.
A useful pattern:
- Start in Plan. Describe what you want to accomplish. (You’re already here.)
- Explore together. Ask questions, consider options, refine the approach.
- Switch to Build. Tell it to implement what you planned.
Custom agents
Beyond Plan and Build, you can define your own agents in opencode.jsonc — with custom instructions, specific tools enabled or disabled, a preferred model, and more. Custom agents are useful for recurring workflows like code review, writing, or working with a specific part of your codebase.
For the full reference, see the agents documentation.