opencode-agents

Define specialized agents with precise tool access and permissions.

Agent Fundamentals

Location

Scope	Path
Project	.opencode/agent/<name>.md
Global	~/.config/opencode/agent/<name>.md

Agents MAY also be defined in opencode.json:

{
  "agent": {
    "my-agent": {
      "description": "Brief description",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}

Frontmatter Schema

Field	Type	Default	Description
description	string	REQUIRED	Trigger description (see below)
mode	string	"all"	primary, subagent, or all
model	string	inherited	Model override (e.g., anthropic/claude-opus-4-5)
temperature	number	1.0	0.0-2.0, lower = deterministic
maxSteps	number	100	Maximum tool calls per turn
disable	boolean	false	Disable without deleting
tools	object	all enabled	Tool-specific enable/disable
permission	object	all allowed	Permission restrictions

Agent Modes

Mode	Visible in Menu	Task Tool Target	Use Case
primary	Yes	No	User-facing, main agents
subagent	No	Yes	Orchestrated by other agents
all	Yes	Yes	Versatile, both contexts

Description Guidelines

Mode	Description Style
primary	3 words max (shown in TUI menu)
subagent	MUST include trigger examples for task tool routing
all	Both: short label + trigger examples

Subagent description example:

description: |-
  Security vulnerability scanner. Use for code audits, dependency checks, and security reviews.
  
  Examples:
  - user: "Review this code for security issues" → scan for vulnerabilities
  - user: "Check for hardcoded secrets" → search for credentials

Permission System

CRITICAL: By default, agents have ALL tools and permissions. Only add permission blocks to RESTRICT access.

Permission Structure

permission:
  edit: "deny"           # deny all file edits
  bash: 
    "*": "ask"           # ask before any bash
    "npm test": "allow"  # but allow npm test
    "rm -rf *": "deny"   # never allow rm -rf
  webfetch: "allow"      # allow web fetching
  skill:
    "*": "deny"          # deny all skills by default
    "security-*": "allow" # allow security-prefixed skills

Permission Levels

Level	Behavior
allow	Execute without confirmation
ask	Prompt user before executing
deny	Block entirely

Bash Pattern Matching

Patterns are matched in order of specificity:

1. Exact match: "npm test": "allow"
2. Prefix match: "npm *": "ask"
3. Wildcard: "*": "deny"

permission:
  bash:
    "*": "deny"              # Default deny
    "git *": "allow"         # Allow git commands
    "npm *": "allow"         # Allow npm commands
    "rm *": "ask"            # Ask for rm
    "rm -rf *": "deny"       # MUST NOT allow rm -rf

Tools Configuration

Enable or disable specific tools:

tools:
  question: "enabled"    # Force enable question tool
  webfetch: "disabled"   # Disable web fetching
  task: "disabled"       # Prevent delegation

Key Tools

Tool	Purpose
question	Interactive Q&A with user (clarification)
delegate	Async background task delegation
task	Sync subagent delegation
todowrite	Task list management
todoread	Read current task list
skill	Load specialized skills

Agent Archetypes

Analyzer (Read-Only)

---
description: Code analysis expert
mode: subagent
temperature: 0.1
permission:
  edit: "deny"
  bash:
    "*": "deny"
    "git log *": "allow"
    "git diff *": "allow"
---

Builder (Full Access)

---
description: Implementation specialist
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.4
---
# No permission block = full access

Researcher (Web + Read)

---
description: Documentation researcher
mode: subagent
temperature: 0.2
permission:
  edit: "deny"
  bash:
    "*": "deny"
---

Specialist (Skill-Based)

---
description: |-
  Security vulnerability scanner. Use for audits and reviews.
mode: subagent
temperature: 0.2
permission:
  edit: "deny"
  bash:
    "*": "deny"
  skill:
    "*": "deny"
    "security-*": "allow"
---

System Prompt Structure

The markdown body becomes the agent's system prompt:

---
description: My agent
mode: primary
---

# Role

You are a [specific role] specializing in [domain].

## Objective

[Clear mission statement]

## Instructions

- MUST [required behavior]
- SHOULD [recommended behavior]
- MAY [optional behavior]
- MUST NOT [prohibited behavior]

## Workflow

1. [First step]
2. [Second step]
3. [Third step]

## Output Format

[Expected output structure]

Validation

After creating an agent:

opencode run "test"

Then test by routing to it:

• If primary: Select from agent menu
• If subagent: Use task tool to invoke