Skip to main content
Modes are now configured through the agent option in the opencode config. The mode option is now deprecated. Learn more about agents.
Modes in OpenCode allow you to customize the behavior, tools, and prompts for different use cases. OpenCode 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 Modes

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 (except for files located at .opencode/plans/*.md to detail the plan itself)
  • 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 Modes

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

​
Configuration

You can customize the built-in modes or create your own through configuration. Modes can be configured in two ways:

​
JSON Configuration

Configure modes in your opencode.json config file:
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mode": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

​
Markdown Configuration

You can also define modes using markdown files. Place them in:
  • Global: ~/.config/opencode/modes/
  • Project: .opencode/modes/
~/.config/opencode/modes/review.md
---
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.
The markdown file name becomes the mode name (e.g., review.md creates a review mode).

​
Configuration Options

​
Model

Override the default model for this mode. Useful for using different models optimized for different tasks.
opencode.json
{
  "mode": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

​
Temperature

Control the randomness and creativity of the AI’s responses. Lower values make responses more focused and deterministic, while higher values increase creativity and variability.
opencode.json
{
  "mode": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}
Temperature values typically range from 0.0 to 1.0:
  • 0.0-0.2: Very focused and deterministic responses, ideal for code analysis and planning
  • 0.3-0.5: Balanced responses with some creativity, good for general development tasks
  • 0.6-1.0: More creative and varied responses, useful for brainstorming and exploration
If no temperature is specified, OpenCode uses model-specific defaults (typically 0 for most models, 0.55 for Qwen models).

​
Prompt

Specify a custom system prompt file for this mode.
opencode.json
{
  "mode": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}
The path is relative to where the config file is located. This works for both the global OpenCode config and the project-specific config.

​
Tools

Control which tools are available in this mode.
opencode.json
{
  "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 that can be controlled through the mode config:
ToolDescription
bashExecute shell commands
editModify existing files
writeCreate new files
readRead file contents
grepSearch file contents
globFind files by pattern
listList directory contents
patchApply patches to files
todowriteManage todo lists
todoreadRead todo lists
webfetchFetch web content

​
Custom Modes

You can create your own custom modes by adding them to the configuration.

​
Using JSON Configuration

opencode.json
{
  "$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
      }
    }
  }
}

​
Using Markdown Files

Create mode files in .opencode/modes/ for project-specific modes or ~/.config/opencode/modes/ for global modes:
.opencode/modes/debug.md
---
temperature: 0.1
tools:
  bash: true
  read: true
  grep: true
  write: false
  edit: false
---

You are in debug mode. Your primary goal is to help investigate and diagnose issues.

Focus on:

- Understanding the problem through careful analysis
- Using bash commands to inspect system state
- Reading relevant files and logs
- Searching for patterns and anomalies
- Providing clear explanations of findings

Do not make any changes to files. Only investigate and report.

​
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

​
Migration to Agents

The mode configuration is deprecated in favor of the more flexible agent configuration. Please refer to the agents documentation for the current approach.
To migrate from modes to agents, change your configuration from:
Before (modes)
{
  "mode": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}
To:
After (agents)
{
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}