Skip to content

019-docs-modes.md

Latest commit

 

History

History
326 lines (245 loc) · 7.64 KB

019-docs-modes.md

File metadata and controls

326 lines (245 loc) · 7.64 KB
Raw
title Modes
url https://opencode.ai/docs/modes
source sitemap
fetched_at 2026-04-17 06:39:20 -0300
rendered_js false
word_count 626
summary This document explains how to utilize, switch between, and customize opencode modes to suit various development workflows. It details the configuration of built-in modes like build and plan, as well as the creation of custom modes via JSON or Markdown files.
tags
opencode
configuration
workflow-customization
ai-modes
developer-tools
category guide

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, 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

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

See also: Formatters for information about code formatting configuration.

Configure

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:

{
"$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/
---
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).

Let’s look at these configuration options in detail.

Model

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"
}
}
}

Temperature

Control the randomness and creativity of the AI’s responses with the temperature config. Lower values make responses more focused and deterministic, while higher values increase creativity and variability.

{
"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
{
"mode": {
"analyze": {
"temperature": 0.1,
"prompt": "{file:./prompts/analysis.txt}"
},
"build": {
"temperature": 0.3
},
"brainstorm": {
"temperature": 0.7,
"prompt": "{file:./prompts/creative.txt}"
}
}
}

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 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.

ToolDescriptionbashExecute shell commandseditModify existing fileswriteCreate new filesreadRead file contentsgrepSearch file contentsglobFind files by patternpatchApply patches to filestodowriteManage todo listswebfetchFetch web content

Custom modes

You can create your own custom modes by adding them to the configuration. Here are examples using both approaches:

Using JSON configuration

{
"$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:

---
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.
---
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
tools:
edit: true
read: true
grep: true
glob: true
---
You are in refactoring mode. Focus on improving code quality without changing functionality.
Priorities:
- Improve code readability and maintainability
- Apply consistent naming conventions
- Reduce code duplication
- Optimize performance where appropriate
- Ensure all tests continue to pass

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.