Agent Configuration

Agents are configured in opencode.json under the agent key, or as standalone Markdown files in the agents directory. Both approaches support the same set of options.

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.

The YAML frontmatter contains the agent configuration. The body below the frontmatter is the prompt text.

File Discovery

The agents directory is searched in this order:

.opencode/agents/ in the project root (project-scoped agents).
~/.config/opencode/agents/ in the user's home directory (global agents).

If both directories contain an agent with the same name, the project-scoped version takes precedence.

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
}

Disabled agents do not appear in the agent list, cannot be invoked, and are not available for delegation.

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

Controls which subagents this agent is allowed to invoke. If not set, all subagents are available.

{
  "task_permission": {
    "*": "allow",
    "deploy-agent": "deny"
  }
}

This prevents an agent from delegating to agents that are outside its responsibility scope. For example, a code review agent should not invoke a deployment agent.

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
}

Only applies to subagents. Primary agents cannot be hidden.

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
}

In most cases, adjust temperature instead of top_p. Only set top_p if you understand the interaction between the two parameters.

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.