OpenCode — Agents
- File format
- Markdown
- Discovery path
-
.opencode/agents - Global install path
-
~/.config/opencode/agents - Syllago install method
- Symlink, Direct copy
- Symlink support
- Yes
- Native frontmatter fields
-
name,description,tools,model,steps,color,temperature
Features
How each feature converts to syllago's canonical format. See format conversion for what these statuses mean.
Fields
Native frontmatter or config fields this provider exposes. The first column is the provider's own field name; the canonical key column links to syllago's cross-provider equivalent.
| Provider field | Conversion | Canonical key | Summary |
|---|---|---|---|
mode | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | Frontmatter mode field selects whether the agent is a root primary agent, a subagent invoked by another agent, or both. Defaults to all if not specified. Built-in primary agents: Build (all tools) and Plan (restricted). Built-in subagents: General (full tools) and Explore (read-only). |
model | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | model_selection | Frontmatter model field selects a specific model using provider/model-id format, overriding the session default. Primary agents use the globally configured model if not specified; subagents use the invoking primary agent's model if not specified. |
permission | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | Frontmatter permission map configures ask/allow/deny behavior per tool, replacing the deprecated tools allow/deny map. Named keys gate logical tool groups; fine-grained keys accept glob/pattern→action objects. Permission keys: read, edit, bash, glob, grep, list, task, external_directory, todowrite, webfetch, websearch, lsp, skill, question, doom_loop. |
steps | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | Frontmatter steps field caps the number of agentic iterations before the agent is forced to respond with text only and summarize its work. Replaces the deprecated maxSteps field. |
temperature | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | Per-agent sampling temperature via frontmatter temperature field. Range 0.0–1.0. If not specified, OpenCode uses model-specific defaults (typically 0 for most models, 0.55 for Qwen models). |
top_p | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | — | Per-agent nucleus sampling top_p value (0.0–1.0) via frontmatter. Alternative to temperature for controlling response diversity. |
color | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Optional color hint for UI display of the agent. Accepts a hex color string (#RRGGBB) or a theme color name (primary, secondary, accent, success, warning, error, info). |
disable | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Boolean disable field (default: false) disables the agent entirely. Useful for turning off built-in agents without removing their config. |
hidden | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Boolean hidden flag (default: false) excludes a subagent from the @ autocomplete menu while still allowing programmatic invocation via the Task tool. Only applies to mode: subagent agents. |
options | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Any unrecognized fields in the agent config are promoted into an options map and passed through to the model provider. This allows provider-specific parameters (e.g., OpenAI reasoningEffort, textVerbosity) without schema changes. |
permission.task | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | permission.task controls which subagents an agent can invoke via the Task tool using glob patterns. When set to deny, the subagent is removed from the Task tool description entirely. Rules are evaluated in order; last matching rule wins. Users can always @-mention subagents directly regardless of task permissions. |
variant | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | — | Optional variant field specifies the default model variant for this agent. Applies only when using the agent's configured model. |
Other features
Behaviors, conventions, and capabilities that aren't tied to a single named field — things like path-based activation, discovery rules, and lifecycle behavior.
| Feature | Conversion | Summary |
|---|---|---|
agent_scopes | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Two scopes: project (.opencode/agents/ or .opencode/agent/) and user-global (~/.config/opencode/agents/). Both scopes are loaded and coexist. |
definition_format | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Markdown files with YAML frontmatter loaded from .opencode/agents/*.md (project) and ~/.config/opencode/agents/*.md (global). The loader glob accepts both agent/ and agents/ directory names and recurses. Frontmatter declares description, mode, model, temperature, top_p, steps, permission, color, hidden, disable, variant, and prompt; the markdown body becomes the system prompt. Agents can also be defined inline in opencode.json under the agent key. |
invocation_patterns | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Primary agents are cycled via the Tab key or the switch_agent keybind. Subagents are invoked automatically by primary agents for specialized tasks based on their description, or manually by @-mentioning the subagent name in a message. Agent name derives from the filename (configEntryNameFromPath). |
subagent_spawning | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | Agents with mode: subagent (or mode: all) can be invoked from other agents via the Task tool; delegation is driven by the callee's description field. Task permissions (permission.task) on the orchestrating agent control which subagents it is allowed to invoke. |
tool_restrictions | Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more → | The permission frontmatter map configures ask/allow/deny per tool using named permission keys (read, edit, bash, glob, grep, list, task, external_directory, todowrite, webfetch, websearch, lsp, skill, question, doom_loop) or wildcard glob patterns against tool names. Keys that support fine-grained control (read, edit, glob, grep, list, bash, task, external_directory, lsp, skill) accept either a shorthand action string or an object of glob/pattern → action. |
| Interactive agent creation command | Conversion type: No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more → | The opencode agent create command interactively creates a new agent markdown file, prompting for scope (global or project), description, and permissions. |
Sources
| Source |
|---|
| https://opencode.ai/docs/agents/ |
| https://raw.githubusercontent.com/sst/opencode/dev/packages/opencode/src/config/agent.ts |