Skip to content
AgentAtlas

OpenCode custom commands: .opencode/commands, $ARGUMENTS, shell output and subtasks

How do I create a custom /command in OpenCode?

Add a Markdown file to .opencode/commands/ in your project or ~/.config/opencode/commands/ for every project. The file name becomes the command: test.md runs as /test. The body is the prompt template, and frontmatter can set description, agent, model and subtask. Use $ARGUMENTS (or $1, $2) for what you type after the command, !`cmd` to insert shell output and @path to include a file. You can also define commands under "command" in your OpenCode config.

Compare: custom slash commands in every AI coding agent →

Where OpenCode reads commands

  • Per project: .opencode/commands/NAME.md.
  • Global: ~/.config/opencode/commands/NAME.md.
  • In config: the "command" option of your OpenCode config, where each entry needs a template.
  • A custom command with the same name as a built-in one, such as /init, /undo, /redo or /help, overrides it.

A Markdown command

.opencode/commands/test.md

---
description: Run tests with coverage
agent: build
---
Run the full test suite with coverage for $ARGUMENTS.

Recent commits:
!`git log --oneline -10`

Focus on failing tests and suggest fixes.

Run it with /test or /test src/auth. The file name sets the command name; the frontmatter is optional.

Options

  • template: the prompt sent to the model. Required in JSON config; in a Markdown file the body is the template.
  • description: shown in the TUI when you type the command.
  • agent: which agent runs the command. If it is a subagent, the command runs as a subagent invocation by default.
  • subtask: true forces a subagent invocation so the command stays out of your primary context; false turns the default subagent behavior off.
  • model: overrides the default model for this command, for example anthropic/claude-3-5-sonnet-20241022.

Arguments, shell output and files

  • $ARGUMENTS is replaced with everything you type after the command name.
  • $1, $2, $3 and so on give you individual arguments.
  • !`command` inserts the output of a shell command. Commands run in the project root.
  • @path includes the content of a file, for example @src/components/Button.tsx.

Define a command in config

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.",
      "description": "Create a new component",
      "agent": "build",
      "subtask": false
    }
  }
}

Sources

More OpenCode guides

Reviewed Oct 20, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →