Custom Agents

A custom agent can be defined easily with a Markdown file. And OpenCode watches for changes in its config directories, so if you update an agent's settings, it will normally reload without a restart.

Put the file in one of these locations:

• .opencode/agents/ for a project-specific agent
• ~/.config/opencode/agents/ for a global agent

For example, a file at .opencode/agents/review.md creates a review agent in the current project:

---
description: Reviews code for bugs, regressions, and risky changes
mode: primary
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

You are a code review agent. Focus on:

- Finding bugs and edge cases
- Explaining tradeoffs clearly
- Suggesting changes without making direct edits
- Code quality and best practices
- Performance implications
- Security concerns

There are two parts to the file:

• The frontmatter at the top configures the agent.
• The Markdown body below that is the agent's system prompt.

The frontmatter fields in this example are:

• description: tells OpenCode and the model when this agent should be used
• mode: whether it's a primary, subagent, or all agent (we'll talk about subagents soon)
• permissions: controls what the agent can do and which resources it can act on