> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anomalyco/opencode/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Commands
> Create custom workflow commands for your team
## Overview
Custom commands let you define reusable workflows that encapsulate your team's best practices, coding standards, and common tasks. They transform complex multi-step processes into simple commands.
## Creating Commands
Define commands in `opencode.json`:
```json theme={null}
{
"command": {
"review": {
"description": "Review code changes",
"template": "Review all uncommitted changes for potential issues, suggest improvements, and check against our coding standards."
},
"test": {
"description": "Generate tests for $1",
"template": "Create comprehensive unit tests for $1. Use the testing framework configured in the project. Cover edge cases and error handling."
}
}
}
```
Then use them:
```
/review
/test src/auth.ts
```
## Command Structure
### Basic Command
Minimal command definition:
```json theme={null}
{
"command": {
"docs": {
"description": "Generate documentation",
"template": "Create comprehensive documentation for the current file."
}
}
}
```
### With Arguments
Commands can accept arguments:
```json theme={null}
{
"command": {
"refactor": {
"description": "Refactor $1 using $2 pattern",
"template": "Refactor $1 to use the $2 design pattern. Maintain all existing functionality and add tests."
}
}
}
```
Usage:
```
/refactor src/users/service.ts singleton
```
### With Specific Agent
Assign commands to specialized agents:
```json theme={null}
{
"command": {
"security-audit": {
"description": "Audit code for security issues",
"template": "Review the code for security vulnerabilities including SQL injection, XSS, authentication bypasses, and insecure dependencies.",
"agent": "security-expert"
}
}
}
```
### With Specific Model
Use a specific model for a command:
```json theme={null}
{
"command": {
"explain": {
"description": "Explain $1 in simple terms",
"template": "Explain $1 in simple, beginner-friendly terms. Use analogies and examples.",
"model": "anthropic/claude-4.5-sonnet"
}
}
}
```
### As Subtask
Execute command as a subtask (uses Task tool):
```json theme={null}
{
"command": {
"optimize": {
"description": "Optimize performance of $1",
"template": "Analyze $1 for performance bottlenecks. Profile the code, identify slow operations, and implement optimizations.",
"subtask": true
}
}
}
```
Subtasks:
* Run in isolated context
* Can use specialized agents
* Results are summarized back to main agent
* Useful for complex, independent tasks
## Template Syntax
### Positional Arguments
Use `$1`, `$2`, `$3`, etc. for individual arguments:
```json theme={null}
{
"template": "Update $1 to use $2 instead of $3"
}
```
Usage:
```
/command file.ts async/await callbacks
```
Expands to:
```
Update file.ts to use async/await instead of callbacks
```
### All Arguments
Use `$ARGUMENTS` for all arguments as a single string:
```json theme={null}
{
"template": "Research and explain: $ARGUMENTS"
}
```
Usage:
```
/command how do React hooks work internally?
```
Expands to:
```
Research and explain: how do React hooks work internally?
```
### Escaping
To use literal `$` in templates:
```json theme={null}
{
"template": "Set environment variable \$API_KEY to $1"
}
```
### Multi-line Templates
Use arrays for multi-line templates:
```json theme={null}
{
"command": {
"feature": {
"description": "Implement new feature $1",
"template": [
"Implement the feature: $1",
"",
"Follow these steps:",
"1. Create necessary files and structure",
"2. Implement core functionality",
"3. Add error handling",
"4. Write tests",
"5. Update documentation"
]
}
}
}
```
Arrays are joined with newlines.
## Real-World Examples
### Development Workflow
```json theme={null}
{
"command": {
"pr": {
"description": "Create pull request",
"template": "Create a pull request for the current branch. Write a clear title and description summarizing changes. Use conventional commit format. Run tests before creating PR."
},
"commit": {
"description": "Create conventional commit",
"template": "Review staged changes and create a conventional commit message. Format: type(scope): description. Types: feat, fix, docs, refactor, test, chore."
},
"changelog": {
"description": "Update CHANGELOG.md",
"template": "Update CHANGELOG.md with recent changes. Group by Added, Changed, Fixed, Removed. Follow Keep a Changelog format."
}
}
}
```
### Testing Commands
```json theme={null}
{
"command": {
"test-file": {
"description": "Generate tests for $1",
"template": "Create comprehensive unit tests for $1. Use Jest/Vitest. Cover: happy path, edge cases, error conditions, boundary values. Aim for >90% coverage.",
"agent": "test-expert"
},
"e2e": {
"description": "Create E2E test for $1",
"template": "Create end-to-end test for $1 using Playwright/Cypress. Test the complete user flow including: navigation, interactions, assertions, error states."
},
"fix-tests": {
"description": "Fix failing tests",
"template": "Run the test suite. For each failing test, analyze the failure, determine root cause, and fix the issue. Ensure fix doesn't break other tests."
}
}
}
```
### Code Quality
```json theme={null}
{
"command": {
"lint": {
"description": "Fix linting issues",
"template": "Run linter and fix all auto-fixable issues. For issues requiring manual fixes, make appropriate changes following project conventions."
},
"types": {
"description": "Fix TypeScript errors in $1",
"template": "Fix all TypeScript errors in $1. Add proper types, fix inference issues, resolve imports. Avoid using 'any' unless absolutely necessary."
},
"cleanup": {
"description": "Clean up code in $1",
"template": "Clean up $1: remove unused code, fix formatting, improve naming, add comments, extract magic numbers, simplify complex logic."
}
}
}
```
### Documentation
```json theme={null}
{
"command": {
"readme": {
"description": "Update README",
"template": "Update README.md with current project info. Include: overview, installation, usage, examples, API reference, contributing guidelines. Use clear headings and formatting.",
"agent": "technical-writer"
},
"api-docs": {
"description": "Document API in $1",
"template": "Generate API documentation for $1. Document all public functions/classes with JSDoc/TSDoc: description, parameters, return types, examples, edge cases."
},
"inline": {
"description": "Add inline docs to $1",
"template": "Add inline documentation to $1. Comment complex logic, explain non-obvious code, document assumptions. Keep comments concise and valuable."
}
}
}
```
### Refactoring
```json theme={null}
{
"command": {
"extract": {
"description": "Extract $1 from $2",
"template": "Extract $1 from $2 into a separate, reusable module. Create proper exports, maintain same interface, update all imports, add tests."
},
"modernize": {
"description": "Modernize $1",
"template": "Modernize $1 to use current best practices: async/await, arrow functions, destructuring, optional chaining, nullish coalescing. Maintain functionality."
},
"dry": {
"description": "Apply DRY principle to $1",
"template": "Refactor $1 to eliminate code duplication. Extract common logic into reusable functions, use composition, maintain readability."
}
}
}
```
### Database
```json theme={null}
{
"command": {
"migration": {
"description": "Create migration for $1",
"template": "Create a database migration for $1. Include: schema changes, indexes, foreign keys, data transformations. Add both up and down migrations."
},
"seed": {
"description": "Create seed data for $1",
"template": "Create realistic seed data for $1. Include various scenarios, edge cases, relationships. Use faker for generated data."
},
"query": {
"description": "Optimize query in $1",
"template": "Analyze and optimize the database query in $1. Add indexes, rewrite for efficiency, use proper joins, explain the improvements.",
"subtask": true
}
}
}
```
## Command Discovery
Users can discover commands through:
### Autocomplete
Type `/` to see all available commands:
```
/
init - Create/update AGENTS.md
review - Review code changes
test - Generate tests for $1
docs - Generate documentation
...
```
### Command Help
Commands show their descriptions in autocomplete with argument hints:
```
/refactor $1 $2 - Refactor $1 using $2 pattern
/test $1 - Generate tests for $1
```
### List Commands Programmatically
Via API:
```bash theme={null}
curl http://localhost:4096/api/command
```
## Sharing Commands
### Team Commands
Commit `opencode.json` to share commands with your team:
```bash theme={null}
git add opencode.json
git commit -m "Add custom workflow commands"
git push
```
Team members get the commands automatically.
### Global Commands
Add personal commands globally:
```json theme={null}
// ~/.config/opencode/opencode.json
{
"command": {
"note": {
"description": "Add note to $1",
"template": "Add a detailed comment note to $1 explaining: $ARGUMENTS"
}
}
}
```
Global commands work in all projects.
### Priority
When the same command name exists in multiple places:
1. **Project** - `.opencode/opencode.json` (highest priority)
2. **Project root** - `opencode.json`
3. **Global** - `~/.config/opencode/opencode.json`
4. **Built-in** - `/init`, `/review` (lowest priority)
## Command Libraries
Create reusable command libraries:
```json theme={null}
// commands/testing.json
{
"command": {
"test-file": { ... },
"test-suite": { ... },
"coverage": { ... }
}
}
```
Import in your `opencode.json`:
```json theme={null}
{
"extends": ["./commands/testing.json", "./commands/docs.json"]
}
```
## Best Practices
Write detailed templates that clearly describe expectations
Assign specialized agents to appropriate commands
Include examples in templates to guide the agent
Use concise descriptions that explain when to use the command
## Related Topics
Full command configuration reference
Create specialized agents
Learn about built-in commands
Add commands from MCP servers