Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lnardev/opencode-config-agent/llms.txt

Use this file to discover all available pages before exploring further.

The opencode.json file is the central configuration for OpenCode Config Agent. It lives at ~/.config/opencode/opencode.json and controls everything about how agents behave: which agents exist, what prompts they use, what tools they can invoke, which MCP servers are connected, what filesystem and shell permissions are enforced, and which plugins are loaded.

​
Top-level structure

The file is a single JSON object with four top-level keys: 
{
  "$schema": "https://opencode.ai/config.json",
  "agent": { ... },
  "mcp": { ... },
  "permission": { ... },
  "plugin": [ ... ]
}
​
$schema
string
Points to the OpenCode JSON schema for editor validation and autocompletion.
​
agent
object
A map of agent names to agent configuration objects. Each key becomes the agent’s identifier used in the agent picker and for delegation.
​
mcp
object
A map of MCP server names to connection configurations. See the MCP field section below and the MCP Servers reference for full details.
​
permission
object
Global permission rules controlling bash command execution and file read access. See the Permissions reference for full details.
​
plugin
array
An array of npm package names to load as OpenCode plugins.

​
agent field

Each entry under agent defines one agent available in OpenCode. Agents are addressed by their key name (e.g. "tony stark", "sdd-orchestrator").

​
Agent object fields

​
description
string
required
A short human-readable description shown in the agent picker when selecting which agent to use.
​
hidden
boolean
When true, the agent is hidden from the autocomplete picker and agent selection UI. Use this for subagents that are only meant to be called programmatically by orchestrators. Defaults to false.
​
mode
"primary" | "subagent"
required
Controls how the agent can be invoked.
  • primary — can be selected directly by the user from the agent picker or invoked in conversation.
  • subagent — intended only for delegation from another agent. Cannot be invoked directly by the user in normal flow.
​
prompt
string
required
The system prompt for the agent. Can be either inline text or a {file:path} reference. See Prompt reference syntax below.
​
tools
object
required
A map of tool names to booleans. Set a tool to true to enable it for this agent, false to disable. Common tools: bash, read, write, edit, delegate, delegation_list, delegation_read.
​
permission
object
Per-agent permission overrides that layer on top of the global permission block. Useful for restricting what a specific agent can delegate to. See Per-agent permissions.

​
Agents in this configuration

OpenCode Config Agent ships with two primary agents and ten hidden subagents:
AgentModeHiddenDescription
tony starkprimaryfalseSenior Architect mentor — helpful first, challenging when it matters
sdd-orchestratorprimaryfalseAgent Teams Orchestrator — coordinates sub-agents, never does work inline
sdd-initsubagenttrueBootstrap SDD context and project configuration
sdd-exploresubagenttrueInvestigate codebase and think through ideas
sdd-proposesubagenttrueCreate change proposals from explorations
sdd-designsubagenttrueCreate technical design from proposals
sdd-specsubagenttrueWrite detailed specifications from proposals
sdd-taskssubagenttrueBreak down specs and designs into implementation tasks
sdd-applysubagenttrueImplement code changes from task definitions
sdd-verifysubagenttrueValidate implementation against specs
sdd-archivesubagenttrueArchive completed change artifacts
sdd-onboardsubagenttrueGuide user through a complete SDD cycle using their real codebase
The two primary agents — tony stark and sdd-orchestrator — are the entry points you interact with directly. All sdd-* subagents are invoked automatically by the orchestrator as it progresses through the SDD workflow phases.

​
tony stark

Tony Stark is a senior architect mentor persona. Its prompt is loaded from ./AGENTS.md (relative to the opencode.json location), making it easy to customize the mentor’s personality and focus areas by editing that file. 
"tony stark": {
  "description": "Senior Architect mentor - helpful first, challenging when it matters",
  "mode": "primary",
  "prompt": "{file:./AGENTS.md}",
  "tools": {
    "edit": true,
    "write": true
  }
}

​
sdd-orchestrator

The SDD orchestrator is a coordinator agent. It holds the SDD workflow logic inline in its prompt field and delegates all real work to the sdd-* subagents. It has the full delegation toolset enabled and a permission override that restricts it to only delegating to agents matching sdd-*. 
"sdd-orchestrator": {
  "description": "Agent Teams Orchestrator - coordinates sub-agents, never does work inline",
  "mode": "primary",
  "permission": {
    "task": {
      "*": "deny",
      "sdd-*": "allow"
    }
  },
  "prompt": "...",
  "tools": {
    "bash": true,
    "delegate": true,
    "delegation_list": true,
    "delegation_read": true,
    "edit": true,
    "read": true,
    "write": true
  }
}
Do not edit the sdd-orchestrator’s inline prompt field directly in your local copy — it is managed by this repository and may be overwritten on updates. To extend orchestrator behavior with project-specific standards, use the skills system instead.

​
Prompt reference syntax

Agent prompts support a {file:path} syntax that loads prompt content from an external file at runtime. This keeps large prompt files out of the JSON and allows you to edit them in your preferred editor. 
"prompt": "{file:./AGENTS.md}"

"prompt": "{file:/Users/you/.config/opencode/prompts/sdd/sdd-apply.md}"
​
{file:./relative/path}
string
A path relative to the directory containing opencode.json. For a config at ~/.config/opencode/opencode.json, ./AGENTS.md resolves to ~/.config/opencode/AGENTS.md.
​
{file:/absolute/path}
string
An absolute path anywhere on the filesystem. The SDD subagents use absolute paths pointing to their individual prompt files under ~/.config/opencode/prompts/sdd/.
Use relative paths for prompts you want to keep co-located with your config (like tony stark’s AGENTS.md). Use absolute paths for prompts that live in a dedicated prompts library and are shared across multiple configs.

​
mcp field

The mcp block registers Model Context Protocol servers that agents can call as tools. Each key is the server’s name as it appears in tool calls. 
"mcp": {
  "context7": {
    "enabled": true,
    "type": "remote",
    "url": "https://mcp.context7.com/mcp"
  },
  "engram": {
    "command": ["/opt/homebrew/bin/engram", "mcp", "--tools=agent"],
    "type": "local"
  },
  "chrome-devtools": {
    "command": ["npx", "-y", "chrome-devtools-mcp@latest"],
    "type": "local"
  }
}
​
type
"remote" | "local"
required
  • remote — connects to an MCP server over HTTP/SSE at the given url.
  • local — spawns a local process via command and communicates over stdio.
​
url
string
Required when type is "remote". The HTTP endpoint of the MCP server.
​
command
string[]
Required when type is "local". The command and arguments to spawn the MCP server process.
​
enabled
boolean
When false, the server is registered but not started. Defaults to true.
The three MCP servers bundled in this config are:

context7

Remote MCP server providing up-to-date library documentation. Used by agents when they need current API references.

engram

Local persistent memory server. Used by the SDD orchestrator and subagents to store and retrieve artifacts across sessions.

chrome-devtools

Local MCP server bridging the Chrome DevTools Protocol. Useful for frontend debugging workflows.

​
plugin field

Plugins extend OpenCode’s core functionality. They are loaded from node_modules in the config directory. 
"plugin": ["opencode-anthropic-login-via-cli@latest"]
This configuration includes one plugin:

opencode-anthropic-login-via-cli

Enables authentication with Anthropic via the CLI, so you can log in to your Anthropic account directly from the terminal rather than managing API keys manually.

​
Installing plugins

After adding a plugin to the plugin array, you must install it: 
cd ~/.config/opencode
npm install
The package.json in the config directory tracks plugin versions. To pin a specific version, replace @latest with the version tag: 
"plugin": ["opencode-anthropic-login-via-cli@1.2.3"]
TUI plugins (like opencode-subagent-statusline) are configured separately in tui.json — they do not go in the plugin array in opencode.json. See the TUI configuration reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us