> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anomalyco/opencode/llms.txt
> Use this file to discover all available pages before exploring further.

# Modes

> Different modes for different use cases (deprecated).

<Note>
  Modes are now configured through the `agent` option in the opencode config. The `mode` option is now deprecated. [Learn more about agents](/agents).
</Note>

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:

```json title="opencode.json" theme={null}
{
  "$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/`

```markdown title="~/.config/opencode/modes/review.md" theme={null}
---
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.

```json title="opencode.json" theme={null}
{
  "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.

```json title="opencode.json" theme={null}
{
  "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.

```json title="opencode.json" theme={null}
{
  "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.

```json title="opencode.json" theme={null}
{
  "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:

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

### Using JSON Configuration

```json title="opencode.json" theme={null}
{
  "$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:

```markdown title=".opencode/modes/debug.md" theme={null}
---
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

<Info>
  The `mode` configuration is deprecated in favor of the more flexible `agent` configuration. Please refer to the [agents documentation](/agents) for the current approach.
</Info>

To migrate from modes to agents, change your configuration from:

```json title="Before (modes)" theme={null}
{
  "mode": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}
```

To:

```json title="After (agents)" theme={null}
{
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}
```