> agents & rules
An agent is a configured persona: a system prompt, a model, and a set of tool permissions. opencode ships Build (full access) and Plan (read-only analysis) as primary agents you switch with Tab, plus subagents like @general and @explore that run focused work in isolated context. Rules files — AGENTS.md and the instructions config — are the standing project knowledge every agent reads.
// agents & rules
4 commands// faq
What's the difference between the Build and Plan agents?
Build is the default and has every tool enabled — it edits files and runs commands. Plan sets edits and bash to ask, so it investigates and proposes without changing anything until you approve. Use Plan to explore an unfamiliar codebase or review a diff, and Tab to switch between them mid-session.
What is a subagent and how do I call one?
A subagent runs a focused task in its own separate context so it does not fill up your main conversation, then returns a summary. Invoke one by typing @ and its name — @general for multi-step research, @explore or @scout for read-only investigation — or let the primary agent delegate automatically. Custom subagents are called the same way.
Where do I put custom agents and rules?
Custom agents are Markdown files with YAML frontmatter in ~/.config/opencode/agents/ (global) or .opencode/agents/ (per-project) — note the plural directory. Rules go in AGENTS.md at the repo root, a global ~/.config/opencode/AGENTS.md, or any files listed in the instructions config key.
Does opencode read my existing CLAUDE.md?
Yes. If a project has no AGENTS.md, opencode falls back to CLAUDE.md, and it also reads a global ~/.claude/CLAUDE.md. Precedence is nearest-first, with AGENTS.md taking priority over CLAUDE.md. Turn the Claude Code compatibility off entirely with OPENCODE_DISABLE_CLAUDE_CODE=1.