Opencode Agents

Define specialized agents with precise tool access and permissions.

Agent Fundamentals

Location

Agents MAY also be defined in opencode.json:

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

Frontmatter Schema

Agent Modes

Description Guidelines

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

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

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