Skip to main content

​
Overview

The agent command helps you create and manage custom agents with specialized system prompts and tool configurations. Agents can be:
  • Primary agents: Act as the main assistant
  • Subagents: Specialized agents invoked by other agents
  • All-purpose: Can function in both roles

​
Usage

opencode agent [command]

​
Subcommands

create

Generate a new custom agent

list

Show all available agents

​
create

Create a new agent with custom configuration.

​
Usage

opencode agent create

​
Interactive Flow

The command guides you through creating an agent:
  1. Choose location: Global or project-specific
  2. Describe purpose: What the agent should do
  3. Generate configuration: LLM creates system prompt
  4. Select tools: Choose which tools to enable
  5. Set mode: Primary, subagent, or both

​
Example Session

opencode agent create

◆ Location
│ ● Current project (/path/to/project)
│   Global (~/.config/opencode)
└

◆ Description
│ A TypeScript expert that helps write type-safe code
└

◇ Agent typescript-expert generated

◆ Select tools to enable (Space to toggle)
│ ◼ bash
│ ◼ read
│ ◼ write
│ ◼ edit
│ ◼ list
│ ◼ glob
│ ◼ grep
│ ◼ webfetch
│ ◻ task
│ ◻ todowrite
│ ◻ todoread
└

◆ Agent mode
│ ● All
│   Primary
│   Subagent
└

✓ Agent created: .opencode/agent/typescript-expert.md
✓ Done

​
Options

​
--path
string
Directory path to generate the agent file
​
--description
string
What the agent should do
​
--mode
string
Agent mode: all, primary, or subagent
​
--tools
string
Comma-separated list of tools to enable. Empty string disables all tools.
​
--model
string
Model to use for agent generation (format: provider/model). Short form: -m

​
Non-Interactive Mode

Provide all options to create an agent without prompts: 
opencode agent create \
  --path .opencode \
  --description "TypeScript expert for type-safe code" \
  --mode all \
  --tools "bash,read,write,edit,glob,grep" \
  --model anthropic/claude-4.5-sonnet
The command outputs the created file path: 
.opencode/agent/typescript-expert.md

​
list

Show all available agents.

​
Usage

opencode agent list

​
Example Output

default (all)
  {"enabled":true,"tools":["bash","read","write",...]}
  
typescript-expert (primary)
  {"enabled":true,"tools":["bash","read","write","edit","glob","grep"]}
  
security-auditor (subagent)
  {"enabled":true,"tools":["read","grep","bash"]}
Shows:
  • Agent name and mode
  • Permission/tool configuration
  • Whether agent is enabled

​
Agent Structure

Agents are Markdown files with YAML frontmatter: 
---
description: When to use this agent
mode: all
tools:
  bash: true
  read: true
  write: true
  task: false
  todowrite: false
---

You are a TypeScript expert specializing in type-safe code...

## Guidelines

- Always use explicit types
- Prefer interfaces over types
- Use strict mode

​
Frontmatter Fields

​
description
string
required
Brief description of when to use this agent. Shown to other agents when selecting subagents.
​
mode
string
default:"all"
Agent mode:
  • all: Can be primary or subagent
  • primary: Only usable as main agent
  • subagent: Only for task delegation
​
tools
object
Tool configuration. Omitted tools default to enabled. Set to false to disable:
tools:
  bash: false
  task: false

​
Available Tools

  • bash: Execute shell commands
  • read: Read file contents
  • write: Create new files
  • edit: Modify existing files
  • list: List directory contents
  • glob: Find files by pattern
  • grep: Search file contents
  • webfetch: Fetch web pages
  • task: Delegate to subagents
  • todowrite: Manage task lists
  • todoread: Read task lists

​
Agent Locations

​
Project Agents

Stored in .opencode/agent/ in your project: 
my-project/
├── .opencode/
│   └── agent/
│       ├── typescript-expert.md
│       └── api-designer.md
Available only in this project.

​
Global Agents

Stored in ~/.config/opencode/agent/: 
~/.config/opencode/
└── agent/
    ├── security-auditor.md
    └── documentation-writer.md
Available in all projects.

​
Priority

Project agents override global agents with the same name.

​
Using Agents

​
Primary Agent

Select agent when starting OpenCode: 
opencode --agent typescript-expert
Or in configuration: 
{
  "agent": "typescript-expert"
}
Switch agents mid-session: 
/agent security-auditor

​
Subagent Delegation

Agents can invoke specialized subagents: 
User: "Audit the authentication code for security issues"

Assistant uses Task tool:
  subagent_type: security-auditor
  description: Review auth.ts for security vulnerabilities
The main agent:
  1. Identifies the need for specialized help
  2. Selects appropriate subagent based on descriptions
  3. Delegates the subtask
  4. Receives results and continues

​
Agent Generation

When you create an agent, OpenCode uses an LLM to generate:
  • Identifier: Filename-safe name (e.g., typescript-expert)
  • Description: When to use this agent
  • System prompt: Detailed instructions and guidelines

​
Generation Model

By default, uses your configured default model. Override with --model: 
opencode agent create --model anthropic/claude-4.5-sonnet

​
Generation Quality

For best results:
  • Be specific in your description
  • Mention key technologies or domains
  • Include constraints or preferences
  • Reference coding standards if applicable
Example descriptions: 
# ✓ Good
"React expert specializing in hooks, performance optimization, and accessibility"

# ✗ Too vague
"Help with React"

​
Example Agents

​
Security Auditor

---
description: Security expert for finding vulnerabilities and suggesting fixes
mode: subagent
tools:
  read: true
  grep: true
  bash: true
  write: false
  edit: false
---

You are a security expert specializing in code audits...

## Focus Areas

- Authentication and authorization
- Input validation and sanitization
- SQL injection and XSS prevention
- Secure API design

​
Documentation Writer

---
description: Technical writer for creating clear, comprehensive documentation
mode: all
tools:
  read: true
  write: true
  edit: true
  glob: true
---

You are a technical writer who creates clear documentation...

## Style Guide

- Use active voice
- Write in second person
- Include code examples
- Structure with clear headings

​
Test Specialist

---
description: Testing expert for writing unit and integration tests
mode: subagent
tools:
  read: true
  write: true
  bash: true
---

You specialize in writing comprehensive tests...

## Testing Principles

- Test behavior, not implementation
- Arrange-Act-Assert pattern
- Meaningful test names
- Mock external dependencies

​
Best Practices

Focused agents

Create specialized agents for specific domains rather than generalists

Clear descriptions

Write descriptions that help other agents know when to delegate

Minimal tools

Only enable tools the agent needs to reduce confusion

Consistent style

Follow the same structure across your agent files

​
Troubleshooting

​
Agent Not Found

Problem: agent "name" not found Solutions:
  • Run opencode agent list to see available agents
  • Check filename matches agent name
  • Verify file is in correct location (.opencode/agent/ or ~/.config/opencode/agent/)
  • Ensure file has .md extension

​
Generation Failed

Problem: LLM fails to generate agent Solutions:
  • Check you’re authenticated: opencode auth list
  • Try a different model with --model
  • Make description more specific
  • Check internet connectivity

​
Subagent Mode Error

Problem: agent "name" is a subagent, not a primary agent Solutions:
  • Use a different agent marked as primary or all
  • Change the agent’s mode to all in its frontmatter
  • Run opencode agent list to see agent modes

​
File Already Exists

Problem: Agent file already exists Solutions:
  • Delete or rename the existing agent file
  • Use a different description that generates a unique identifier
  • Manually create with a custom filename

Agents Concept

Learn about how agents work

Tools

Understand available tools

Permissions

Configure agent permissions

Configuration

Set default agent in config