Commands

Custom commands turn a named prompt template into a reusable command.

Configure with Markdown

OpenCode discovers .md command files in commands/ directories:

~/.config/opencode/commands/       # Global
.opencode/commands/                # Project

Files may be nested; for example, .opencode/commands/team/review.md defines the command team/review. Files with other extensions, including .mdx, are not discovered.

---
description: Review code for correctness and missing tests
agent: plan
model: anthropic/claude-sonnet-4-5#high
---

Review $ARGUMENTS. Report bugs first, then missing tests.

The file body, with surrounding whitespace removed, is the command template. JSON and Markdown commands share one registry. Project definitions take precedence over global definitions, and a later definition can override a built-in or earlier command with the same name. Changes are reloaded automatically.

Configure with JSON

Add commands under the commands key in any OpenCode JSON or JSONC configuration file. Each entry’s key is the command name and template is required.

{
  "$schema": "https://opencode.ai/config.json",
  "commands": {
    "review": {
      "description": "Review code for correctness and missing tests",
      "template": "Review $ARGUMENTS. Report bugs first, then missing tests.",
      "agent": "plan",
      "model": "anthropic/claude-sonnet-4-5#high",
    },
  },
}

Fields

The optional fields can be used in JSON or YAML frontmatter. Do not put template in frontmatter because the Markdown body always supplies it.

Arguments

Use $ARGUMENTS for the complete argument string:

---
description: Create a component
---

Create a typed React component named $ARGUMENTS.

Use $1, $2, and higher numbers for parsed positional arguments. Single and double quotes group text containing spaces and are removed during parsing.

---
description: Check one area with a specific focus
---

Check $1. Focus on $2.

The highest-numbered positional placeholder present in the template consumes that argument and all remaining arguments. For example, if a template contains only $1, then $1 receives the full parsed argument list. Missing positions become empty strings.

If a template contains neither positional placeholders nor $ARGUMENTS, OpenCode appends non-empty arguments to the template after a blank line.

Shell interpolation

Wrap a shell command in ! followed by backticks to insert its output before the prompt is submitted:

---
description: Review the current diff
---

Review this diff:

!`git diff --stat && git diff`

OpenCode runs each interpolation with the configured shell in the active project location and inserts its combined output into the template. Argument interpolation happens first, so avoid placing untrusted arguments inside shell interpolations.

No other template interpolation is performed. In particular, an @path written into a stored template remains ordinary prompt text; V2 does not automatically attach that file.

Agent, model, and execution

Commands evaluate their arguments and shell blocks before submitting a durable user prompt. Commands run in the current session unless background delegation is enabled as described below.

For current-session commands, agent overrides the active agent when the command is invoked and becomes the session’s active agent. If model is set, it overrides the model. Otherwise, a model configured on the command’s agent takes precedence over the model active at invocation.

Background subagents

Set subagent: true to run a command in a background child session. The parent keeps its agent and model, stays available for other work, and receives the child’s result or failure when it finishes.

---
description: Review changes in the background
agent: general
subagent: true
---

Review $ARGUMENTS for bugs and missing tests.

• true forces child execution, including for an agent with mode: primary.
• false forces execution in the current session.
• When omitted, a command targeting an agent with mode: subagent runs in the background.
• The child uses the command’s model override, then the selected agent’s model, then the parent’s model.
• Legacy subtask is still accepted in JSON and Markdown. If both fields are present, subagent takes precedence.