YouTip

Agents are specialized AI assistants in OpenCode. Each agent can be configured with independent system prompts, models, tool access permissions, and behavioral constraints to handle specific types of tasks and workflows. You can switch agents at any time during a session, or directly invoke a specific agent using `@agent-name`.\n\n* * *\n\n## Agent Types\n\nAgents in OpenCode are divided into two types, which differ in their invocation methods and responsibilities:\n\n| Type | Description | Switching Method |\n| --- | --- | --- |\n| **Primary Agent** | The main assistant you interact with directly, handling the primary conversation flow. Tool access permissions are configured via `permission` | Press `Tab` to cycle, or use the configured `agent_cycle` shortcut |\n| **Subagent** | An assistant called by the primary agent to execute specialized tasks, running in an independent sub-session without affecting the main session context | Automatically called by the primary agent, or manually invoked using `@agent-name` in a message |\n\n* * *\n\n## Built-in Agents\n\nOpenCode includes 4 ready-to-use built-in agents and 3 automatically running system agents:\n\n### 1. Build (Primary Agent)\n\nThe default primary agent with all tools enabled, suitable for daily development work requiring full file operations and system command access. This is the agent you will use most frequently.\n\n### 2. Plan (Primary Agent)\n\nA restricted agent designed specifically for code analysis and planning. By default, the following operations will trigger an approval prompt (set to `ask`):\n\n* **file edits**: All write, patch, and edit operations\n* **bash**: All bash commands\n\nSwitch to the Plan agent when you want the LLM to analyze code, make suggestions, or create an execution plan, but don't want it to make any actual modifications to the codebase.\n\n### 3. General (Subagent)\n\nA general-purpose subagent with full tool access (except the todo tool) that can modify files. Suitable for researching complex problems and executing multi-step tasks, and can also run multiple independent work units in parallel.\n\n### 4. Explore (Subagent)\n\nA read-only subagent that cannot modify any files. Suitable for quickly finding files, searching code keywords, or answering questions about codebase structure. It is fast and produces no side effects.\n\n### 5. System Agents (Hidden)\n\nThe following three agents are automatically managed by OpenCode and **will not appear in the agent switching list**. They do not need to and cannot be manually selected:\n\n| Agent Name | Responsibility | Trigger Time |\n| --- | --- | --- |\n| **Compaction** | Compresses overly long contexts into smaller summaries to prevent exceeding the model's context limit | Runs automatically when context length reaches the threshold |\n| **Title** | Generates a short title for the session | Runs automatically after a new session starts |\n| **Summary** | Creates a summary for the session | Runs automatically when a session summary is needed |\n\n* * *\n\n## How to Use Agents\n\n### 1. Switching Primary Agents\n\nDuring a session, press `Tab` to cycle through all primary agents, or press `Shift+Tab` to cycle in reverse. You can also use `a` to open the agent list and select directly.\n\n### 2. Invoking Subagents\n\nThere are two ways to invoke a subagent:\n\n* **Automatic Invocation**: When the primary agent determines that a subagent is needed based on the nature of the task, it will automatically call and delegate the task to it\n* **Manual @ Invocation**: Use `@agent-name` in a message to directly specify which subagent should handle the task\n\n@general help me search for this function across the codebase\n### 3. Navigating Between Parent and Child Sessions\n\nWhen a subagent runs, it creates an independent sub-session. You can use shortcuts to navigate between the parent session and sub-sessions:\n\n| Shortcut | Action |\n| --- | --- |\n| `+→` (`session_child_cycle`) | Cycle forward: Parent session → Sub-session 1 → Sub-session 2 → … → Parent session |\n| `+←` (`session_child_cycle_reverse`) | Cycle backward: Parent session ← Sub-session 1 ← Sub-session 2 ← … ← Parent session |\n| `+↑` (`session_parent`) | Return directly to the parent session |\n\n* * *\n\n## Two Configuration Methods\n\nAgents can be defined using either JSON configuration or Markdown files. The effect is the same, so choose according to your needs:\n\n### Method 1: Configure in opencode.json\n\n## Example\n\n{\n\n"$schema":"https://opencode.ai/config.json",\n\n"agent":{\n\n"build":{// Override the built-in build agent configuration\n\n"mode":"primary",\n\n"model":"anthropic/claude-sonnet-4-20250514",\n\n"prompt":"{file:./prompts/build.txt}",// Load system prompt from file\n\n"tools":{\n\n"write":true,\n\n"edit":true,\n\n"bash":true\n\n}\n\n},\n\n"code-reviewer":{// Custom subagent\n\n"description":"Reviews code for best practices and potential issues",\n\n"mode":"subagent",\n\n"model":"anthropic/claude-sonnet-4-20250514",\n\n"prompt":"You are a code reviewer. Focus on security, performance, and maintainability.",\n\n"tools":{\n\n"write":false,\n\n"edit":false\n\n}\n\n}\n\n}\n\n}\n\n### Method 2: Markdown File\n\nCreate a `.md` file in the following paths. **The file name becomes the agent name** (e.g., `review.md` corresponds to the agent name `review`):\n\n* **Global:** `~/.config/opencode/agents/` (effective for all projects)\n* **Project-level:** `.opencode/agents/` (effective only for the current project)\n\n## Example\n\n# File path: ~/.config/opencode/agents/review.md\n\n---\n\n description: Reviews code for quality and best practices\n\n mode: subagent\n\n model: anthropic/claude-sonnet-4-20250514\n\n temperature: 0.1\n\n tools:\n\n write: false\n\n edit: false\n\n bash: false\n\n---\n\n You are in code review mode. Focus on:\n\n - Code quality and best practices\n\n - Potential bugs and edge cases\n\n - Performance implications\n\n - Security considerations\n\nProvide constructive feedback without making direct changes.\n\n* * *\n\n## Configuration Options Details\n\n### description\n\nA functional description of the agent, displayed in the agent list and the `@` autocomplete menu, helping users and the primary agent decide when to invoke this agent. For custom agents, this field is **required**:\n\n## Example\n\n{\n\n"agent":{\n\n"review":{\n\n"description":"Reviews code for best practices and potential issues"\n\n}\n\n}\n\n}\n\n### mode\n\nControls how the agent is used. It can be set to one of the following three values:\n\n| Value | Description |\n| --- | --- |\n| `"primary"` | Primary agent, appears in the Tab switching list, used for main conversations |\n| `"subagent"` | Subagent, not in the Tab switching list, called by the primary agent or manually via @ |\n| `"all"` | Used as both a primary agent and a subagent (default value when mode is not specified) |\n\n## Example\n\n{\n\n"agent":{\n\n"review":{\n\n"mode":"subagent"// Only used as a subagent, does not appear in the primary agent switching list\n\n}\n\n}\n\n}\n\n### model\n\nSpecifies a particular model for the agent, overriding the global default model. The format is `provider/model-id`. Suitable for using different models for different tasks, such as a faster small model for planning tasks and a more powerful large model for code generation:\n\n## Example\n\n{\n\n"agent":{\n\n"plan":{\n\n"model":"anthropic/claude-haiku-4-20250514"// Use the faster Haiku model for planning tasks\n\n},\n\n"build":{\n\n"model":"anthropic/claude-sonnet-4-20250514"// Use the more capable Sonnet model for development tasks\n\n}\n\n}\n\n}\n\n> If `model` is not specified, the primary agent will use the global default model, and the subagent will inherit the model used by the primary agent that called it. Run `opencode models` to view a list of all available models.\n\n### prompt (System Prompt)\n\nSpecifies a custom system prompt for the agent. You can write a string directly or load it from an external file using the `{file:./path}` syntax. The path is relative to the configuration file location:\n\n## Example\n\n{\n\n"agent":{\n\n"review":{\n\n"prompt":"{file:./prompts/code-review.txt}"\n\n// Read the prompt from prompts/code-review.txt in the same directory as opencode.json\n\n// Suitable for maintaining long prompt content in a separate text file\n\n}\n\n}\n\n}\n\n### temperature\n\nControls the randomness of the model's output. Lower values produce more deterministic outputs, suitable for tasks requiring precise results; higher values produce more diverse outputs, suitable for creative tasks:\n\n| Temperature Range | Output Characteristics | Applicable Scenarios |\n| --- | --- | --- |\n| 0.0 – 0.2 | Highly focused, strong determinism | Code analysis, planning, debugging, review |\n| 0.3 – 0.5 | Balanced,balanceaccuracy and flexibility | General development tasks, documentation writing |\n| 0.6 – 1.0 | More creative and diverse | Brainstorming, solution exploration, creative writing |\n\n## Example\n\n{\n\n"agent":{\n\n"analyze":{\n\n"temperature":0.1,// Analysis task: high determinism\n\n"prompt":"{file:./prompts/analysis.txt}"\n\n},\n\n"build":{\n\n"temperature":0.3// Development task: balanced\n\n},\n\n"brainstorm":{\n\n"temperature":0.7,// Brainstorming: more creative\n\n"prompt":"{file