Agent Configuration

Overview

• Primary agents - Main assistants you interact with directly (switchable via Tab key)
• Subagents - Specialized assistants invoked by primary agents or via @ mention

Core Concepts

Agent Types

• Main conversation partners
• Switch between them using Tab key or configured keybind
• Examples: Build (full access), Plan (restricted for analysis)

• Invoked automatically by primary agents for specialized tasks
• Can be manually invoked with @ mention (e.g.,

  @general help me search

  )
• Examples: General (multi-step tasks), Explore (codebase exploration)

Built-in Agents

• Default agent with all tools enabled
• Full file operations and system commands
• Standard development work

• Restricted agent for planning and analysis
• File edits and bash commands set to

  ask

  by default
• Analyzes and suggests without modifying code

• General-purpose for complex questions and multi-step tasks
• Full tool access except todo
• Execute multiple units of work in parallel

• Fast, read-only codebase exploration
• Cannot modify files
• Find patterns, search keywords, answer codebase questions

Switching and Invoking Agents

• Press Tab key during a session
• Cycles through available primary agents

• Automatically by primary agents based on descriptions
• Manually via @ mention:

  @explore find the authentication logic

• Leader+Right: Cycle forward (parent → child1 → child2 → parent)
• Leader+Left: Cycle backward

Configuration Methods

JSON Configuration

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown Configuration

• Global:

  ~/.config/opencode/agents/

• Project:

  .opencode/agents/

~/.config/opencode/agents/review.md

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

Essential Configuration Options

Description (Required)

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Mode

• primary

  - Main agent, switchable via Tab

• subagent

  - Invoked by other agents or @ mention

• all

  - Both (default if not specified)

Model

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

provider/model-id

Temperature

• 0.0-0.2: Focused, deterministic (code analysis)
• 0.3-0.5: Balanced (general development)
• 0.6-1.0: Creative (brainstorming)

Tools

{
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false,
        "mymcp_*": false  // Wildcard to disable MCP server tools
      }
    }
  }
}

Permissions

• allow

  - Execute without approval

• ask

  - Prompt for approval

• deny

  - Disable the tool

{
  "agent": {
    "build": {
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git push": "ask"
        },
        "webfetch": "deny"
      }
    }
  }
}

Prompt

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Max Steps

{
  "agent": {
    "quick-thinker": {
      "steps": 5
    }
  }
}

Additional Options

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    }
  }
}

MUST FOLLOW

color

model

temperature

opencode.json

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "your-agent-name": {
      "model": "github-copilot/claude-sonnet-4.6",
      "temperature": 0.3,
      "color": "#ff6b6b"
    }
  }
}

model

temperature

color

.opencode/agents/<name>.md

description

mode

tools

permission

steps

hidden

Creating Custom Agents

Interactive Creation

opencode agent create

1. Asks where to save (global or project)
2. Requests agent description
3. Generates system prompt and identifier
4. Lets you select tool access
5. Creates markdown file with configuration

Manual Creation Steps

1. Identify the use case - What specific task or workflow?
2. Choose configuration method - JSON in

   opencode.json

   or markdown file
3. Set required fields:

   • description

     - When to use this agent

   • mode

     - Primary or subagent
4. Configure tools and permissions - What can the agent access?
5. Add custom prompt (optional) - Specialized instructions
6. Test the agent - Try it on real tasks and iterate

Common Patterns

Read-Only Analysis Agent

{
  "agent": {
    "analyzer": {
      "description": "Analyzes code without making changes",
      "mode": "subagent",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

Documentation Writer

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Security Auditor

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---

You are a security expert. Focus on identifying potential security issues.

Look for:
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

Faster Model for Planning

{
  "agent": {
    "quick-plan": {
      "description": "Fast planning with cheaper model",
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "temperature": 0.1,
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Quick Reference

Switch Agents

• Tab key - Cycle through primary agents
• @ mention - Invoke subagent (e.g.,

  @explore find auth code

  )

Navigate Sessions

• Leader+Right - Next child session
• Leader+Left - Previous child session

Configuration Locations

• Global JSON:

  ~/.config/opencode/opencode.json

• Project JSON:

  .opencode/opencode.json

• Global agents:

  ~/.config/opencode/agents/

• Project agents:

  .opencode/agents/

Permission Levels

• allow

  - No approval needed

• ask

  - Prompt user

• deny

  - Disabled

Temperature Ranges

• 0.0-0.2: Focused (analysis, planning)
• 0.3-0.5: Balanced (general dev)
• 0.6-1.0: Creative (brainstorming)

Additional Resources

Reference Files

• references/primary-agents.md

  - In-depth primary agent configuration

• references/subagents.md

  - Subagent setup and invocation strategies

• references/permissions.md

  - Complete permission system details

Example Files

examples/

• custom-agents.md

  - Real-world custom agent configurations