Modes

Different modes for different use cases.

Modes in opencode allow you to customize the behavior, tools, and prompts for different use cases.

It comes with two built-in modes: build and plan. You can customize these or configure your own through the opencode config.

You can switch between modes during a session or configure them in your config file.

Built-in

opencode comes with two built-in modes.

Build

Build is the default mode with all tools enabled. This is the standard mode for development work where you need full access to file operations and system commands.

Plan

A restricted mode designed for planning and analysis. In plan mode, the following tools are disabled by default:

write - Cannot create new files
edit - Cannot modify existing files
patch - Cannot apply patches
bash - Cannot execute shell commands

This mode is useful when you want the AI to analyze code, suggest changes, or create plans without making any actual modifications to your codebase.

Switching

You can switch between modes during a session using the Tab key. Or your configured switch_mode keybind.

Use the model config to override the default model for this mode. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation.

{
  "mode": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

Prompt

Specify a custom system prompt file for this mode with the prompt config. The prompt file should contain instructions specific to the mode’s purpose.

{
  "mode": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

This path is relative to where the config file is located. So this works for both the global opencode config and the project specific config.

Tools

Control which tools are available in this mode with the tools config. You can enable or disable specific tools by setting them to true or false.

{
  "mode": {
    "readonly": {
      "tools": {
        "write": false,
        "edit": false,
        "bash": false,
        "read": true,
        "grep": true,
        "glob": true
      }
    }
  }
}

If no tools are specified, all tools are enabled by default.

Available tools

Here are all the tools can be controlled through the mode config.

Tool	Description
`bash`	Execute shell commands
`edit`	Modify existing files
`write`	Create new files
`read`	Read file contents
`grep`	Search file contents
`glob`	Find files by pattern
`list`	List directory contents
`patch`	Apply patches to files
`todowrite`	Manage todo lists
`todoread`	Read todo lists
`webfetch`	Fetch web content

Custom modes

You can create your own custom modes by adding them to the mode configuration. For example, a documentation mode that focuses on reading and analysis.

{
  "$schema": "https://opencode.ai/config.json",
  "mode": {
    "docs": {
      "prompt": "{file:./prompts/documentation.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": false,
        "read": true,
        "grep": true,
        "glob": true
      }
    }
  }
}

Use cases

Here are some common use cases for different modes.

Build mode: Full development work with all tools enabled
Plan mode: Analysis and planning without making changes
Review mode: Code review with read-only access plus documentation tools
Debug mode: Focused on investigation with bash and read tools enabled
Docs mode: Documentation writing with file operations but no system commands

You might also find different models are good for different use cases.