Agent Overview

Agents are specialized AI assistants with their own prompts, models, tool access permissions, and behavior profiles. The agent system lets you compose multiple assistants that collaborate on complex tasks, each optimized for a specific role. Instead of one monolithic assistant, you have a team of experts that can be called upon as needed.

Core Concepts

Agent Identity

Every agent has a distinct identity defined by:

• Prompt – The system prompt that controls the agent's behavior, expertise, and tone.
• Model – The underlying LLM that powers the agent. Different models have different strengths (speed, reasoning, creativity).
• Permissions – Which tools the agent can use and under what conditions.
• Mode – Whether the agent is a primary agent or a subagent.

Agent Types

There are two categories of agents.

Primary Agents

Primary agents are the main assistants you interact with directly. One primary agent is active at a time. You can cycle between them with the Tab key. Each primary agent maintains its own conversation context, so switching between them preserves each agent's working state.

Primary agents are designed for broad, continuous work. The active primary agent is your main point of contact for the session.

Subagents

Subagents are specialized assistants designed for focused, narrow tasks. They cannot be the active primary agent. Instead, they are invoked in two ways:

1. Primary agent delegation – The active primary agent decides a task is better handled by a specialist and delegates it using the task tool.
2. @mention invocation – You can directly invoke a subagent by typing @agent-name in the input. The subagent runs, completes its task, and returns results to the conversation.

Subagents are isolated from each other and from the primary agent. They cannot modify the primary agent's context, and their file modifications are tracked separately in the snapshot system.

Built-in Agents

Primary Agents

Agent	Description
Build	The default agent. All tools are enabled. Designed for full development work: writing code, running commands, managing files, executing tests, and debugging. This is the workhorse agent for daily development.
Plan	A restricted agent for analysis and planning. The edit and bash tools are set to ask by default, preventing accidental modifications. Use this agent to explore the codebase, design solutions, evaluate approaches, and produce detailed implementation plans before switching to Build for execution.

Hidden System Primary Agents

Agent	Description
Compaction	Handles context window compaction. When the conversation history grows large, this agent summarizes and prunes context to keep the model responsive and accurate. It runs automatically and does not appear in the agent list. Users do not interact with this agent directly.
Title	Generates session titles automatically based on conversation content. It runs once when a meaningful interaction pattern is detected. The generated title appears in the session history and tab bar.
Summary	Produces session summaries that capture key decisions, changes made, and unresolved items. Summaries are used for session continuity and can be referenced across sessions for context restoration.

Subagents

Agent	Description
General	A general-purpose subagent with full tool access (except todo). Handles multi-step tasks that the primary agent delegates. This is the default subagent when no specialization is needed. It can read, write, edit, run commands, and perform any action the primary agent can.
Explore	A fast, read-only subagent optimized for codebase exploration. It cannot modify files. Use it for understanding code structure, finding definitions, tracing call graphs, answering architectural questions, and inspecting configuration. The edit, write, and destructive bash commands are denied. Explore is designed to be quick: it has a lower step limit and a faster model by default.
Scout	A read-only subagent specialized in external research. It has access to webfetch and websearch tools. Use it for looking up documentation, researching dependency compatibility, checking API changes, investigating error messages, finding migration guides, and exploring open-source libraries. It cannot modify any files in the project.

Agent Switching and Navigation

Tab Cycling for Primary Agents

Press Tab to cycle through available primary agents. The agent indicator in the interface updates to show which agent is active. Each agent retains its own conversation context and tool permissions. The order cycles through all enabled primary agents in the order they are defined.

Session Navigation

The session tree lets you navigate the agent hierarchy using keyboard shortcuts:

Shortcut	Action
Leader + Down	Enter a child session (drill into a subagent's work to see its conversation)
Leader + Up	Return to the parent session
Leader + Right	Switch to the next sibling session
Leader + Left	Switch to the previous sibling session

The Leader key is configurable in your keybindings. The default is Ctrl+A.

Session Tree Visualization

Session: "Add user authentication" (Build - primary)
├── @explore find existing auth code (Explore - subagent)
│   └── Results: found auth middleware in src/middleware.ts
├── @general generate migration (General - subagent)
│   └── Created: src/db/migrations/024_add_users.sql
├── @scout research bcrypt best practices (Scout - subagent)
│   └── Results: current recommendations for password hashing
└── Implementation work (Build - primary, resumed)

You can drill into any subagent's session with Leader+Down to see its full conversation, then return to the parent with Leader+Up.

Agent Collaboration Patterns

Sequential Delegation

The primary agent delegates one task at a time, waiting for each subagent to complete before proceeding:

1. Build delegates to Explore to find relevant code.
2. Build reviews the results.
3. Build delegates to Scout to research a library API.
4. Build writes the implementation.

Parallel Delegation

The primary agent dispatches multiple subagents simultaneously for independent tasks:

1. Build delegates database migration to General.
2. Build delegates test file generation to a second General instance.
3. Both run in parallel.
4. Build integrates the results.

Nested Delegation

A subagent can delegate to another subagent if it has the appropriate task permissions:

1. Build delegates to Deploy-agent.
2. Deploy-agent delegates to Scout to verify the target environment's configuration.
3. Scout returns results to Deploy-agent.
4. Deploy-agent completes the deployment and reports back to Build.

Permission Isolation

Each agent operates with its own permission set. A subagent cannot escalate its permissions beyond what is configured, even if the primary agent has broader access.

Isolation Rules

• A subagent inherits the global permission defaults but can have its own overrides.
• A primary agent's permissions do not affect its subagents.
• A subagent cannot use a tool that its own configuration denies, regardless of what the primary agent allows.
• Task permissions control which subagents an agent can invoke, preventing unauthorized delegation.

Practical Examples

Scenario	Result
Build (edit: allow) invokes Code-Reviewer (edit: deny)	Code-Reviewer cannot edit files. Safe for code review.
Code-Reviewer (edit: deny) invokes General (edit: allow)	General can edit files. Task permission prevents this if configured.
Deploy-agent (bash: restricted) invokes Scout (bash: deny)	Scout cannot run shell commands. Consistently restricted.

Custom Agents

You can define custom agents beyond the built-in set. Custom agents are configured in opencode.json or as Markdown files in the agents directory.

Custom Primary Agent

{
  "agent": {
    "fullstack-dev": {
      "description": "Full-stack development with focus on TypeScript and React",
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.2,
      "prompt": "You are a senior full-stack engineer. Write production-ready code with TypeScript, React, and Node.js."
    }
  }
}

Custom Subagent

{
  "agent": {
    "security-auditor": {
      "description": "Audits code for security vulnerabilities",
      "mode": "subagent",
      "permission": {
        "edit": "deny",
        "write": "deny",
        "bash": "ask"
      },
      "prompt": "You are a security engineer. Focus on OWASP Top 10 vulnerabilities, input validation, and authentication."
    }
  }
}

See the Agent Configuration page for a complete reference of all configuration options.

Best Practices

Use the Right Agent for the Job

• Use Build for writing and modifying code.
• Use Plan before making significant changes to design the approach.
• Use Explore to understand unfamiliar code without risk of modification.
• Use Scout for research tasks that require external documentation.
• Use General for parallelizing independent subtasks.

Configure Permissions Thoughtfully

Restrict subagent permissions to the minimum needed for their role. A code review subagent should not have write access. A deployment subagent should only be able to run specific commands.

Monitor Subagent Usage

Subagent invocations consume model tokens and time. Delegating every small task to a subagent adds overhead. Reserve delegation for tasks that genuinely benefit from specialization or parallel execution.