Merge agent and mode into one (#1689)

The concept of mode has been deprecated, there is now only the agent field in the config.

An agent can be cycled through as your primary agent with <tab> or you can spawn a subagent by @ mentioning it. if you include a description of when to use it, the primary agent will try to automatically use it

Full docs here: https://opencode.ai/docs/agents/

3 files changed, 300 insertions, 370 deletions

diff --git a/packages/web/src/content/docs/docs/agents.mdx b/packages/web/src/content/docs/docs/agents.mdx
index 6760abaa0..950f910fd 100644
--- a/packages/web/src/content/docs/docs/agents.mdx
+++ b/packages/web/src/content/docs/docs/agents.mdx
@@ -5,6 +5,52 @@ description: Configure and use specialized agents in opencode.
 
 Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access.
 
+:::tip
+Use the plan agent to analyze code and review suggestions without making any code changes.
+:::
+
+You can switch between agents during a session or configure them in your config file.
+
+---
+
+## Agent Types
+
+opencode has two types of agents:
+
+### Primary Agents
+
+Primary agents are the main assistants you interact with directly. You can cycle through them using the **Tab** key (or your configured `switch_agent` keybind). These agents handle your main conversation and can access all configured tools.
+
+**Built-in Primary Agents:**
+
+- **Build** - The default agent with all tools enabled. Standard for development work where you need full access to file operations and system commands.
+- **Plan** - A restricted agent for planning and analysis. Has `write`, `edit`, `patch`, and `bash` tools disabled by default. Useful for analyzing code and suggesting changes without making modifications.
+
+### Subagents
+
+Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by **@ mentioning** them in your messages (e.g., `@general help me search for this function`).
+
+**Built-in Subagents:**
+
+- **General** - General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use when searching for keywords or files and you're not confident you'll find the right match in the first few tries.
+
+---
+
+## Using Agents
+
+### Switching Primary Agents
+
+Use the **Tab** key to cycle through available primary agents during a session. You can also use your configured `switch_agent` keybind.
+
+### Invoking Subagents
+
+- **Automatic**: Primary agents will automatically use subagents for specialized tasks based on their descriptions
+- **Manual**: @ mention a subagent in your message: `@general search for authentication code`
+
+See also: [Formatters](/docs/formatters) for information about code formatting configuration.
+
+---
+
 ## Creating Agents
 
 You can create new agents using the `opencode agent create` command. This interactive command will:
@@ -21,39 +67,46 @@ opencode agent create
 
 The command will guide you through the process and automatically generate a well-structured agent based on your requirements.
 
-## Built-in Agents
-
-opencode comes with a built-in `general` agent:
-
-- **general** - General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. Use this when searching for keywords or files and you're not confident you'll find the right match in the first few tries.
-
 ## Configuration
 
-Agents can be configured in your `opencode.json` config file or as markdown files.
+You can customize the built-in agents or create your own through configuration. Agents can be configured in two ways:
 
 ### JSON Configuration
 
+Configure agents in your `opencode.json` config file:
+
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
   "agent": {
+    "build": {
+      "mode": "primary",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "{file:./prompts/build.txt}",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      }
+    },
+    "plan": {
+      "mode": "primary",
+      "model": "anthropic/claude-haiku-4-20250514",
+      "tools": {
+        "write": false,
+        "edit": false,
+        "bash": false
+      }
+    },
     "code-reviewer": {
       "description": "Reviews code for best practices and potential issues",
+      "mode": "subagent",
       "model": "anthropic/claude-sonnet-4-20250514",
       "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
       "tools": {
         "write": false,
         "edit": false
       }
-    },
-    "test-writer": {
-      "description": "Specialized agent for writing comprehensive tests",
-      "prompt": "You are a test writing specialist. Write thorough, maintainable tests.",
-      "tools": {
-        "bash": true,
-        "read": true,
-        "write": true
-      }
     }
   }
 }
@@ -66,25 +119,113 @@ You can also define agents using markdown files. Place them in:
 - Global: `~/.config/opencode/agent/`
 - Project: `.opencode/agent/`
 
-```markdown title="~/.config/opencode/agent/code-reviewer.md"
+```markdown title="~/.config/opencode/agent/review.md"
 ---
-description: Reviews code for best practices and potential issues
+description: Reviews code for quality and best practices
+mode: subagent
 model: anthropic/claude-sonnet-4-20250514
+temperature: 0.1
 tools:
   write: false
   edit: false
+  bash: false
 ---
 
-You are a code reviewer with expertise in security, performance, and maintainability.
+You are in code review mode. Focus on:
 
-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 agent name (e.g., `review.md` creates a `review` agent).
+
+Let's look at these configuration options in detail.
+
+---
+
+### Model
+
+Use the `model` config to override the default model for this agent. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "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.
 
-- Security vulnerabilities
-- Performance bottlenecks
-- Code maintainability
-- Best practices adherence
+```json title="opencode.json"
+{
+  "agent": {
+    "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
+
+```json title="opencode.json"
+{
+  "agent": {
+    "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 agent with the `prompt` config. The prompt file should contain instructions specific to the agent's purpose.
+
+```json title="opencode.json"
+{
+  "agent": {
+    "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.
+
+---
+
 ## Agent Properties
 
 ### Required
@@ -96,39 +237,66 @@ Focus on:
 - **model** - Specific model to use (defaults to your configured model)
 - **prompt** - Custom system prompt for the agent
 - **tools** - Object specifying which tools the agent can access (true/false for each tool)
+- **temperature** - Control response randomness (0.0-1.0)
+- **mode** - Agent type: `"primary"` (can be cycled with Tab), `"subagent"` (invoked by @ mention), or `"all"` (both)
 - **disable** - Set to true to disable the agent
 
-## Tool Access
+### Tools
 
-By default, agents inherit the same tool access as the main assistant. You can restrict or enable specific tools:
+Control which tools are available in this agent with the `tools` config. You can enable or disable specific tools by setting them to `true` or `false`.
 
 ```json
 {
   "agent": {
-    "readonly-agent": {
-      "description": "Read-only agent for analysis",
+    "readonly": {
       "tools": {
         "write": false,
         "edit": false,
-        "bash": false
+        "bash": false,
+        "read": true,
+        "grep": true,
+        "glob": true
       }
     }
   }
 }
 ```
 
-Common tools you might want to control:
+If no tools are specified, all tools are enabled by default.
 
-- `write` - Create new files
-- `edit` - Modify existing files
-- `bash` - Execute shell commands
-- `read` - Read files
-- `glob` - Search for files
-- `grep` - Search file contents
+---
 
-## Using Agents
+#### Available tools
+
+Here are all the tools can be controlled through the agent 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       |
+
+---
+
+## Tool Access
+
+By default, agents inherit the same tool access as the main assistant. You can restrict or enable specific tools as shown in the Tools section above.
+
+## Agent Modes
 
-Agents are automatically available through the Task tool when configured. The main assistant will use them for specialized tasks based on their descriptions.
+The `mode` property determines how an agent can be used:
+
+- **`"primary"`** - Can be cycled through with Tab key as your main assistant
+- **`"subagent"`** - Can be invoked by @ mentioning or automatically by primary agents
+- **`"all"`** - Can be used both as primary and subagent (default for custom agents)
 
 ## Best Practices
 
@@ -138,6 +306,97 @@ Agents are automatically available through the Task tool when configured. The ma
 4. **Consistent naming** - Use descriptive, consistent names for your agents
 5. **Project-specific agents** - Use `.opencode/agent/` for project-specific workflows
 
+## Custom Agents
+
+You can create your own custom agents by adding them to the configuration. Here are examples using both approaches:
+
+### Using JSON configuration
+
+```json title="opencode.json" {4-14}
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "docs": {
+      "prompt": "{file:./prompts/documentation.txt}",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": false,
+        "read": true,
+        "grep": true,
+        "glob": true
+      }
+    }
+  }
+}
+```
+
+### Using markdown files
+
+Create agent files in `.opencode/agent/` for project-specific agents or `~/.config/opencode/agent/` for global agents:
+
+```markdown title=".opencode/agent/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.
+```
+
+```markdown title="~/.config/opencode/agent/refactor.md"
+---
+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 agents.
+
+- **Build agent**: Full development work with all tools enabled
+- **Plan agent**: Analysis and planning without making changes
+- **Review agent**: Code review with read-only access plus documentation tools
+- **Debug agent**: Focused on investigation with bash and read tools enabled
+- **Docs agent**: Documentation writing with file operations but no system commands
+
+You might also find different models are good for different use cases.
+
+---
+
 ## Examples
 
 ### Documentation Agent
@@ -145,6 +404,7 @@ Agents are automatically available through the Task tool when configured. The ma
 ```markdown title="~/.config/opencode/agent/docs-writer.md"
 ---
 description: Writes and maintains project documentation
+mode: subagent
 tools:
   bash: false
 ---
@@ -164,6 +424,7 @@ Focus on:
 ```markdown title="~/.config/opencode/agent/security-auditor.md"
 ---
 description: Performs security audits and identifies vulnerabilities
+mode: subagent
 tools:
   write: false
   edit: false
diff --git a/packages/web/src/content/docs/docs/keybinds.mdx b/packages/web/src/content/docs/docs/keybinds.mdx
index 076b428f0..6bb573bce 100644
--- a/packages/web/src/content/docs/docs/keybinds.mdx
+++ b/packages/web/src/content/docs/docs/keybinds.mdx
@@ -11,7 +11,7 @@ opencode has a list of keybinds that you can customize through the opencode conf
   "keybinds": {
     "leader": "ctrl+x",
     "app_help": "<leader>h",
-    "switch_mode": "tab",
+    "switch_agent": "tab",
 
     "editor_open": "<leader>e",
 
diff --git a/packages/web/src/content/docs/docs/modes.mdx b/packages/web/src/content/docs/docs/modes.mdx
deleted file mode 100644
index 133fe7bdd..000000000
--- a/packages/web/src/content/docs/docs/modes.mdx
+++ /dev/null
@@ -1,331 +0,0 @@
----
-title: Modes
-description: 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.
-
-:::tip
-Use the plan mode to analyze code and review suggestions without making any code
-changes.
-:::
-
-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.
-
-See also: [Formatters](/docs/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:
-
-```json title="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/mode/`
-- Project: `.opencode/mode/`
-
-```markdown title="~/.config/opencode/mode/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).
-
-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.
-
-```json title="opencode.json"
-{
-  "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.
-
-```json title="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
-
-```json title="opencode.json"
-{
-  "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.
-
-```json title="opencode.json"
-{
-  "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`.
-
-```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 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. Here are examples using both approaches:
-
-### Using JSON configuration
-
-```json title="opencode.json" {4-14}
-{
-  "$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/mode/` for project-specific modes or `~/.config/opencode/mode/` for global modes:
-
-```markdown title=".opencode/mode/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.
-```
-
-```markdown title="~/.config/opencode/mode/refactor.md"
----
-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.