Agent Configuration

tip

You can define agents via opencode.json or as standalone Markdown files in the agents directory.

Configuration Methods

JSON Format (opencode.json)

Define agents inline in your project's opencode.json:

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices, security, and performance",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "{file:./prompts/code-review.txt}",
      "temperature": 0.1,
      "steps": 10,
      "permission": {
        "edit": "deny",
        "write": "deny"
      },
      "color": "#ff6b6b",
      "hidden": false
    },
    "deploy-agent": {
      "description": "Handles deployment to staging and production",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a deployment engineer. Follow the runbook exactly.",
      "temperature": 0.0,
      "steps": 30,
      "permission": {
        "bash": {
          "*": "deny",
          "npm run build": "allow",
          "npm run deploy:*": "allow",
          "aws *": "ask"
        }
      },
      "color": "#4ecdc4"
    },
    "architect": {
      "description": "System design and architecture analysis",
      "mode": "primary",
      "model": "anthropic/claude-opus-4-5",
      "prompt": "{file:./prompts/architect.txt}",
      "temperature": 0.3,
      "steps": 20,
      "permission": {
        "edit": "deny",
        "bash": {
          "*": "ask",
          "ls *": "allow",
          "cat *": "allow",
          "grep *": "allow"
        }
      },
      "color": "#845ef7"
    }
  }
}

Markdown File Format

Place agents in the agents directory (either .opencode/agents/ for project-scoped or ~/.config/opencode/agents/ for global). Each file defines one agent.

Example .opencode/agents/code-reviewer.md:

---
description: Reviews code for best practices, security, and performance
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
steps: 10
permission:
  edit: deny
  write: deny
color: "#ff6b6b"
---

You are a senior code reviewer. Focus on:

1. **Security** - OWASP Top 10 vulnerabilities, input validation, authentication, authorization, data exposure
2. **Performance** - Unnecessary computations, memory leaks, N+1 queries, missing caching
3. **Maintainability** - Duplicate code, overly complex logic, missing abstractions, testability
4. **Correctness** - Edge cases, error handling, race conditions, state management

Provide actionable feedback with specific code examples. Prioritize issues by severity.

File Discovery

Configuration Options Reference

description (required)

A short description of the agent's purpose. This description is used in the agent list UI and helps other agents understand when to delegate to this agent.

{
  "description": "Audits dependency licenses for compliance"
}

mode

Controls whether the agent appears as a primary agent, a subagent, or both:

Value	Behavior
`"primary"`	Agent appears in the Tab cycle of primary agents. Cannot be invoked via @mention.
`"subagent"`	Agent cannot be a primary agent. Invoked via @mention or by other agents.
`"all"`	Agent can serve as both a primary agent and a subagent.

{
  "mode": "primary"
}

model

Override the model used by this agent. If not specified, the agent uses the default model from the main configuration.

{
  "model": "anthropic/claude-sonnet-4-5"
}

Supported model providers and identifiers depend on your opencode deployment configuration.

prompt

The system prompt for the agent. This can be an inline string or a file reference.

Inline Prompt

{
  "prompt": "You are a database administrator. Optimize queries and manage schema migrations."
}

File Reference

{
  "prompt": "{file:./prompts/dba.txt}"
}

File references use the {file:./path/to/file.txt} syntax. The path is relative to the project root. File references are loaded at session start. If the file does not exist, an error is logged and the agent uses a default prompt.

Multiple prompt files can be combined by referencing them in the instructions field of the main configuration, but for agent-specific prompts, a single file reference is the recommended approach.

temperature

Controls the randomness of the model's output. Range: 0.0 to 1.0.

Value	Effect
`0.0`	Deterministic output, best for code generation and factual tasks.
`0.3`	Slight variation, good for architecture and planning.
`0.7`	Creative, good for brainstorming and exploration.
`1.0`	Maximum creativity, may produce unpredictable results.

{
  "temperature": 0.1
}

steps

Maximum number of tool-calling iterations the agent can perform before returning control. A single step is one LLM invocation plus any tool calls it makes.

{
  "steps": 15
}

Higher values allow the agent to complete complex multi-step tasks.
Lower values force the agent to be concise or delegate to subagents.
The default is typically 10-20 depending on the agent type.

disable

Set to true to disable the agent without removing its configuration:

{
  "disable": true
}

permission

Tool permission overrides for this agent. These rules combine with (and take precedence over) global permissions.

{
  "permission": {
    "edit": "deny",
    "write": "deny",
    "bash": {
      "*": "ask",
      "npm run test": "allow",
      "npm run lint": "allow"
    },
    "webfetch": "allow"
  }
}

See the Permissions documentation for a complete reference.

task permission

note

Task permissions control which subagents an agent can invoke, adding a layer of access control.

hidden

When true, the agent is hidden from the agent list UI. It can still be invoked programmatically by other agents or via @mention if you know its name.

{
  "hidden": true
}

color

A hex color or theme color name for the agent's UI badge and messages:

{
  "color": "#ff6b6b"
}

Available theme colors: "primary", "secondary", "success", "warning", "danger", "info".

top_p

Nucleus sampling parameter. Range: 0.0 to 1.0. Alternative to temperature for controlling output diversity.

{
  "top_p": 0.9
}

Creating Agents Interactively

The opencode agent create command walks you through agent creation interactively:

opencode agent create

The prompts:

Agent name – A unique identifier (kebab-case recommended).
Description – What the agent does.
Mode – Primary, subagent, or both.
Model – Optional model override.
Temperature – Optional creativity setting.
Max steps – Optional iteration limit.
Permissions – Optional tool restrictions.
Color – Optional UI color.

The command writes the agent configuration to .opencode/agents/<name>.md.