opencode-agents

OpenCode Agents — Complete Reference

📚 Official Docs: For the latest information, always refer to the official documentation: https://opencode.ai/docs/agents/

OpenCode supports a multi-agent architecture where specialized AI assistants handle different aspects of development. Agents come in two types — primary agents (direct user interaction, switchable via Tab) and subagents (invoked by other agents or via @mention/Task tool). There are also hidden agents (internal-use only, not user-selectable).

This guide covers every agent type, all built-in agents, every configuration option, the complete permission system, and how to create custom agents.

---

1. Agent Types

Primary Agents

Primary agents are the main assistants you interact with directly. They appear in the agent selector and can be cycled through using the Tab key (or your configured switch_agent keybind). Each primary agent has its own system prompt, tool permissions, temperature, and behavioral configuration.

OpenCode ships with two built-in primary agents: Build and Plan.

Primary agents are suitable for:

• Direct user conversation and coding
• Multi-step development tasks
• Planning and architecture analysis
• Read-only exploration

You can switch between primary agents mid-session by pressing Tab.

Subagents

Subagents are specialized assistants that primary agents can invoke for specific tasks. They run in isolated contexts and return results to the invoking agent. You can invoke them:

• Automatically — the primary agent decides when to delegate based on subagent descriptions
• Manually — by @mentioning them in your message (e.g., @explore find all auth functions)
• Programmatically — via the Task tool from another agent's configuration

OpenCode ships with three built-in subagents: General, Explore, and Scout.

Hidden Agents

Hidden agents are internal system agents not visible in the UI or @ autocomplete. They handle behind-the-scenes operations and run automatically when triggered by system events. You cannot select them directly, but they perform critical maintenance functions.