From 678e5cf45441b34fcc2ac7f344253985f77ca0e3 Mon Sep 17 00:00:00 2001 From: Ryan Vogel Date: Sun, 21 Dec 2025 19:46:20 -0500 Subject: [PATCH 1/3] docs: add First Hour guide for new users - Create new Guides section in docs navigation - Add comprehensive first-hour.mdx guide covering: - Installation and provider setup (promoting Zen) - Project initialization with /init - File references with @ - Plan-Build workflow explanation - Undo/redo functionality - Shell command integration - Image paste support (Ctrl+V) - MCP server setup (Context7, Exa) with config location guidance - Quick tips and cheat sheet - Structure guide as progressive disclosure (essentials first, details later) --- packages/web/astro.config.mjs | 4 + .../src/content/docs/guides/first-hour.mdx | 352 ++++++++++++++++++ 2 files changed, 356 insertions(+) create mode 100644 packages/web/src/content/docs/guides/first-hour.mdx diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs index 1e112b170..7d07b2d4d 100644 --- a/packages/web/astro.config.mjs +++ b/packages/web/astro.config.mjs @@ -57,6 +57,10 @@ export default defineConfig({ "enterprise", "troubleshooting", "1-0", + { + label: "Guides", + items: ["guides/first-hour"], + }, { label: "Usage", items: ["tui", "cli", "ide", "zen", "share", "github", "gitlab"], diff --git a/packages/web/src/content/docs/guides/first-hour.mdx b/packages/web/src/content/docs/guides/first-hour.mdx new file mode 100644 index 000000000..c16617e11 --- /dev/null +++ b/packages/web/src/content/docs/guides/first-hour.mdx @@ -0,0 +1,352 @@ +--- +title: First Hour +description: Go from install to productive in under an hour. +lastUpdated: 2025-12-21 +--- + +This guide walks you through your first hour with OpenCode. By the end, you'll understand the core workflow and be productive with your codebase. + +**The essentials**: + +- Install and run `/connect` to add an API key +- Run `/init` to scan your project, then start chatting +- Use **Tab** to switch between Plan and Build modes +- Use `@` to reference files +- Use `/undo` if something goes wrong + +That's it. Read on for the full walkthrough. + +--- + +## What you'll learn + +By the end of this guide you will: + +- Have OpenCode installed and configured +- Understand the Plan → Build workflow +- Know how to reference files and provide context +- Be able to undo mistakes and iterate on changes + +--- + +## Install + +Get OpenCode running in under a minute. + +```bash +curl -fsSL https://opencode.ai/install | bash +``` + +Or use your package manager. [See all install options](/docs/#install). + +--- + +## Connect a provider + +Launch OpenCode and connect to an LLM provider. + +```bash +opencode +``` + +Run the connect command and follow the prompts. + +```txt frame="none" +/connect +``` + +You can also run this from the command line without launching the TUI. + +```bash +opencode auth login +``` + +We recommend [OpenCode Zen](/docs/zen) - select **opencode** and sign up at [opencode.ai/auth](https://opencode.ai/auth). Zen gives you access to the best coding models from OpenAI, Anthropic, Google, and others through a single API key. We benchmark and curate these models specifically for coding agents, so you get optimal performance without the guesswork. + +If you already have API keys from Anthropic, OpenAI, or other providers, you can use those instead. + +--- + +## Initialize your project + +Navigate to a project and run OpenCode. + +```bash +cd ~/my-project +opencode +``` + +Run the init command to scan your codebase. + +```txt frame="none" +/init +``` + +This creates an `AGENTS.md` file that helps OpenCode understand your project structure, coding patterns, and conventions. Commit this file to Git so your team benefits too. + +:::tip +The `/init` command analyzes your entire codebase. For large projects, this may take a minute. +::: + +--- + +## Your first conversation + +Now let's actually use OpenCode. Start with something simple. + +```txt frame="none" +Give me a quick summary of this codebase. +``` + +OpenCode will read through your project and explain what it does. This is a good sanity check that everything is working. + +--- + +## Reference files with @ + +The `@` symbol is your best friend. It lets you reference specific files in your prompts. + +```txt frame="none" +What does @src/auth/login.ts do? +``` + +Start typing `@` and a fuzzy finder appears. Search for any file in your project. + +:::tip +Reference files when you want OpenCode to focus on specific code. This gives it precise context instead of searching the whole codebase. +::: + +You can reference multiple files in one prompt. + +```txt frame="none" +Compare @src/api/users.ts and @src/api/posts.ts - are they following the same patterns? +``` + +--- + +## The Plan-Build workflow + +This is the core of working with OpenCode. There are two modes: + +| Mode | Purpose | Makes changes? | +| --------- | ------------------------------------------- | -------------- | +| **Plan** | Analyze code, create plans, suggest changes | No | +| **Build** | Execute changes, write code, run commands | Yes | + +Press **Tab** to switch between them. You'll see the current mode in the bottom-right corner. + +--- + +### Start with Plan mode + +When tackling something new, start in Plan mode. Press **Tab** until you see "Plan" in the corner. + +```txt frame="none" +I want to add rate limiting to our API endpoints. How should we approach this? +``` + +OpenCode will analyze your codebase and suggest an implementation plan without making any changes. This lets you review the approach before committing to it. + +--- + +### Iterate on the plan + +Plans are meant to be refined. Give feedback and ask questions. + +```txt frame="none" +I like option 2, but can we use Redis instead of in-memory storage? +``` + +Keep iterating until you're happy with the approach. + +--- + +### Switch to Build mode + +Once the plan looks good, press **Tab** to switch to Build mode. + +```txt frame="none" +Sounds good. Go ahead and implement it. +``` + +OpenCode will now make actual changes to your files. You'll see each file edit as it happens. + +--- + +## Undo mistakes + +Made a change you don't like? No problem. + +```txt frame="none" +/undo +``` + +This reverts all file changes from the last message and removes it from the conversation. Your original prompt reappears so you can rephrase it. + +:::tip +Run `/undo` multiple times to undo multiple changes. Use `/redo` to restore undone changes. +::: + +This works because OpenCode uses Git under the hood. Your project needs to be a Git repository. + +--- + +## Run shell commands + +Prefix any message with `!` to run a shell command and add the output to the conversation. + +```txt frame="none" +!npm test +``` + +This is useful for showing OpenCode test failures, build errors, or any command output. + +```txt frame="none" +!npm test + +These tests are failing. Can you fix them? +``` + +--- + +## Share your conversation + +Found something useful? Share it with your team. + +```txt frame="none" +/share +``` + +This creates a link and copies it to your clipboard. Conversations are private by default - only people with the link can view them. + +--- + +## Quick tips + +A few things that will make you more productive: + +**Give context generously.** Tell OpenCode about your constraints, preferences, and requirements. It can't read your mind. + +```txt frame="none" +We use Tailwind for styling and prefer functional components with hooks. +Add a user profile card that shows name, avatar, and email. +``` + +**Talk like you're mentoring a junior developer.** Explain the "why" not just the "what". + +```txt frame="none" +We're seeing timeouts on the /search endpoint during peak traffic. +Users are reporting 30+ second load times. The database query looks fine +so I suspect it's the external API calls. Can you investigate? +``` + +**Use images for UI work.** Drag and drop screenshots or mockups directly into the terminal. You can also paste images from your clipboard with **Ctrl+V**. + +```txt frame="none" +[Image #1] Implement this design for our settings page. +``` + +--- + +## Add MCP servers + +MCP servers extend OpenCode with external tools. Two we recommend: + +- [**Context7**](https://context7.com) - Search library documentation. Great for current API references. +- [**Exa**](https://exa.ai) - Search the web and code repositories. Useful for recent solutions. + +These ground responses in real documentation instead of potentially outdated training data. + +--- + +### Config locations + +OpenCode config can live in two places: + +| Location | Path | Scope | +| -------- | ---------------------------------- | ----------------- | +| Global | `~/.config/opencode/opencode.json` | All projects | +| Project | `opencode.json` in project root | That project only | + +--- + +### Global config + +For tools you'll use everywhere, add them to your global config: + +```json title="~/.config/opencode/opencode.json" +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp" + }, + "exa": { + "type": "remote", + "url": "https://mcp.exa.ai/mcp" + } + } +} +``` + +--- + +### Project config + +For project-specific tools, add them to your project's `opencode.json`: + +```json title="opencode.json" +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "neon": { + "type": "remote", + "url": "https://mcp.neon.tech/sse", + "headers": { + "Authorization": "Bearer {env:NEON_API_KEY}" + } + } + } +} +``` + +--- + +### Use MCP tools + +Ask OpenCode to use them when you need current information. + +```txt frame="none" +How do I set up authentication in Next.js 16? use context7 +``` + +[Learn more about MCP servers](/docs/mcp-servers). + +--- + +## What's next + +You now know the fundamentals. Here's where to go deeper: + +- [Agents](/docs/agents) - Create specialized agents for specific tasks +- [Commands](/docs/commands) - Build custom commands for repetitive workflows +- [Rules](/docs/rules) - Customize OpenCode's behavior with AGENTS.md +- [Keybinds](/docs/keybinds) - Learn keyboard shortcuts for faster navigation +- [Themes](/docs/themes) - Customize the look and feel + +--- + +## Cheat sheet + +| Action | How | +| ------------------ | --------------------- | +| Switch modes | **Tab** | +| Reference file | `@filename` | +| Run shell command | `!command` | +| Undo changes | `/undo` | +| Redo changes | `/redo` | +| Start new session | `/new` | +| Share conversation | `/share` | +| See all commands | `/help` | +| Exit | `/exit` or `ctrl+x q` | From 7885011363f7df2fba4a26f82130119efae69650 Mon Sep 17 00:00:00 2001 From: Ryan Vogel Date: Sun, 21 Dec 2025 20:07:00 -0500 Subject: [PATCH 2/3] docs: add Subagents guide - Add comprehensive guide for working with subagents - Cover built-in subagents (@explore, @general) - Document manual invocation with @ mentions - Explain automatic delegation and session navigation - Full configuration reference with examples: - description, mode, model, temperature, top_p - prompt, tools, permission, maxSteps, color, disable - Include 5 practical example subagents: - Code reviewer, Test writer, Documentation writer - Security auditor, Git committer - Add best practices and cheat sheet - Update sidebar to include subagents guide --- packages/web/astro.config.mjs | 2 +- .../web/src/content/docs/guides/subagents.mdx | 578 ++++++++++++++++++ 2 files changed, 579 insertions(+), 1 deletion(-) create mode 100644 packages/web/src/content/docs/guides/subagents.mdx diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs index 7d07b2d4d..05a08d137 100644 --- a/packages/web/astro.config.mjs +++ b/packages/web/astro.config.mjs @@ -59,7 +59,7 @@ export default defineConfig({ "1-0", { label: "Guides", - items: ["guides/first-hour"], + items: ["guides/first-hour", "guides/subagents"], }, { label: "Usage", diff --git a/packages/web/src/content/docs/guides/subagents.mdx b/packages/web/src/content/docs/guides/subagents.mdx new file mode 100644 index 000000000..c40855b7f --- /dev/null +++ b/packages/web/src/content/docs/guides/subagents.mdx @@ -0,0 +1,578 @@ +--- +title: Subagents +description: Delegate tasks and work faster with specialized agents. +lastUpdated: 2025-12-21 +--- + +Subagents are specialized assistants that handle specific tasks. Use them to delegate work, run tasks in parallel, and keep your main conversation focused. + +**The essentials**: + +- Built-in: `@explore` (find files), `@general` (complex research) +- Invoke manually with `@agent-name` in your prompt +- Primary agents delegate automatically based on descriptions +- Create custom subagents in `~/.config/opencode/agent/` or `.opencode/agent/` + +--- + +## Built-in subagents + +OpenCode includes two subagents ready to use. + +| Agent | Best for | +| ------------ | ----------------------------------------------- | +| **@explore** | Finding files, understanding codebase structure | +| **@general** | Multi-step research, complex questions | + +--- + +### Explore + +A fast, read-only agent for navigating codebases. It can search files by pattern, grep for content, and read files - but cannot make changes. + +```txt frame="none" +@explore find all React components that use the useAuth hook +``` + +Specify thoroughness when needed: + +```txt frame="none" +@explore do a very thorough search for all API endpoint definitions +``` + +--- + +### General + +A general-purpose agent for research and multi-step tasks. Has full tool access except for todo management. + +```txt frame="none" +@general research how error handling works across the codebase and suggest improvements +``` + +--- + +## Invoke subagents + +There are two ways subagents get invoked. + +--- + +### Manual invocation + +Type `@` followed by the agent name in your prompt. + +```txt frame="none" +@explore find all files that import the Button component +``` + +Use this when you know which agent you want for a specific task. + +--- + +### Automatic delegation + +Primary agents (Build, Plan) automatically delegate to subagents based on their descriptions. When you ask the Build agent to explore the codebase, it may spawn an `@explore` subagent behind the scenes. + +This happens automatically - you'll see subagent activity in the session. + +--- + +### Navigate between sessions + +Subagents run in child sessions. Navigate between parent and child sessions with: + +- **`+Right`** - Cycle forward through sessions +- **`+Left`** - Cycle backward through sessions + +This lets you inspect what subagents are doing or check their detailed output. + +--- + +## Create custom subagents + +Define subagents as markdown files or in your `opencode.json`. + +--- + +### File locations + +| Location | Path | Scope | +| -------- | ------------------------------- | ----------------- | +| Global | `~/.config/opencode/agent/*.md` | All projects | +| Project | `.opencode/agent/*.md` | That project only | + +The filename becomes the agent name. `review.md` creates `@review`. + +--- + +### Markdown format + +Create a markdown file with YAML frontmatter for config and the body as the system prompt. + +```markdown title="~/.config/opencode/agent/review.md" +--- +description: Reviews code for quality issues and best practices +mode: subagent +tools: + write: false + edit: false +--- + +You are a senior code reviewer. Analyze code for: + +- Code quality and readability +- Potential bugs and edge cases +- Performance issues +- Security concerns + +Provide specific, actionable feedback. Do not make changes directly. +``` + +--- + +### JSON format + +Alternatively, configure agents in `opencode.json`: + +```json title="opencode.json" +{ + "$schema": "https://opencode.ai/config.json", + "agent": { + "review": { + "description": "Reviews code for quality issues and best practices", + "mode": "subagent", + "prompt": "You are a senior code reviewer...", + "tools": { + "write": false, + "edit": false + } + } + } +} +``` + +--- + +## Configuration reference + +All available options for configuring subagents. + +--- + +### description + +**Required for automatic invocation.** Tells primary agents when to use this subagent. + +```yaml +description: Reviews code for security vulnerabilities +``` + +Write clear descriptions - primary agents use this to decide when to delegate. + +--- + +### mode + +Controls how the agent can be used. + +```yaml +mode: subagent +``` + +| Value | Meaning | +| ---------- | ------------------------------------------------------------ | +| `subagent` | Only available as a subagent (invoked via `@` or delegation) | +| `primary` | Only available as a primary agent (Tab to switch) | +| `all` | Available as both (default) | + +--- + +### model + +Override the model for this agent. The format is `provider/model`. + +```yaml +# Direct provider +model: anthropic/claude-sonnet-4 + +# OpenCode Zen +model: opencode/claude-sonnet-4 +``` + +Find model IDs on [Models.dev](https://models.dev) or run `/models` in OpenCode. For Zen models, see the [Zen docs](/docs/zen#endpoints). + +Useful for using faster models for simple tasks or more capable models for complex ones. If not specified, subagents inherit the model from the primary agent that invoked them. + +--- + +### temperature + +Control randomness and creativity. Lower values are more focused and deterministic. + +```yaml +temperature: 0.1 +``` + +| Range | Best for | +| --------- | ----------------------------- | +| 0.0 - 0.2 | Code analysis, precise tasks | +| 0.3 - 0.5 | General development | +| 0.6 - 1.0 | Brainstorming, creative tasks | + +--- + +### top_p + +Nucleus sampling parameter. Alternative to temperature for controlling randomness. + +```yaml +top_p: 0.9 +``` + +--- + +### prompt + +The system prompt for the agent. In markdown files, this is the body content after the frontmatter. + +```yaml +prompt: "You are a technical writer. Focus on clarity and completeness." +``` + +Or in markdown format: + +```markdown title="~/.config/opencode/agent/docs.md" +--- +description: Writes documentation +mode: subagent +--- + +You are a technical writer. Focus on: + +- Clear explanations +- Practical examples +- Consistent formatting +``` + +--- + +### tools + +Enable or disable specific tools. + +```yaml +tools: + write: false + edit: false + bash: true + webfetch: true +``` + +Common patterns: + +```yaml +# Read-only agent +tools: + write: false + edit: false + +# No shell access +tools: + bash: false + +# Disable MCP tools by pattern +tools: + "mymcp_*": false +``` + +--- + +### permission + +Fine-grained control over tool permissions. Values: `allow`, `ask`, `deny`. + +```yaml +permission: + edit: deny + webfetch: allow + bash: + "git status": allow + "git diff*": allow + "git log*": allow + "*": ask +``` + +The `bash` field supports glob patterns. More specific patterns override `*`. + +--- + +### maxSteps + +Limit the number of agentic iterations before forcing a text response. + +```yaml +maxSteps: 10 +``` + +Useful for controlling costs or preventing runaway agents. + +--- + +### color + +Hex color for visual identification in the UI. + +```yaml +color: "#FF5733" +``` + +--- + +### disable + +Disable a built-in or previously defined agent. + +```yaml +disable: true +``` + +--- + +### Additional options + +Any other options are passed through to the model provider. + +```yaml +reasoningEffort: high +textVerbosity: low +``` + +Check your provider's documentation for available options. + +--- + +## Example subagents + +Ready-to-use examples for common workflows. + +--- + +### Code reviewer + +Reviews code without making changes. + +```markdown title="~/.config/opencode/agent/review.md" +--- +description: Reviews code for quality, bugs, and best practices +mode: subagent +temperature: 0.2 +tools: + write: false + edit: false +--- + +You are a senior code reviewer. For each piece of code: + +1. Check for bugs and edge cases +2. Evaluate code quality and readability +3. Look for performance issues +4. Identify security concerns +5. Suggest improvements + +Be specific and actionable. Reference line numbers when relevant. +``` + +--- + +### Test writer + +Writes tests for existing code. + +```markdown title="~/.config/opencode/agent/test-writer.md" +--- +description: Writes comprehensive tests for code +mode: subagent +temperature: 0.3 +--- + +You are a test engineer. When writing tests: + +- Cover happy paths and edge cases +- Test error conditions +- Use descriptive test names +- Follow existing test patterns in the codebase +- Aim for high coverage of critical paths + +Match the testing framework already used in the project. +``` + +--- + +### Documentation writer + +Creates and updates documentation. + +```markdown title="~/.config/opencode/agent/docs.md" +--- +description: Writes and maintains documentation +mode: subagent +tools: + bash: false +--- + +You are a technical writer. Create clear, comprehensive documentation. + +Guidelines: + +- Write for developers who are new to the codebase +- Include practical code examples +- Use consistent formatting +- Keep explanations concise but complete +- Update existing docs rather than duplicating +``` + +--- + +### Security auditor + +Focuses on security analysis. + +```markdown title="~/.config/opencode/agent/security.md" +--- +description: Audits code for security vulnerabilities +mode: subagent +temperature: 0.1 +tools: + write: false + edit: false +permission: + bash: + "grep*": allow + "rg*": allow + "find*": allow + "*": deny +--- + +You are a security expert. Analyze code for: + +- Input validation vulnerabilities +- Authentication and authorization flaws +- Data exposure risks +- Injection vulnerabilities (SQL, XSS, command) +- Insecure dependencies +- Configuration security issues + +Classify findings by severity: Critical, High, Medium, Low. +``` + +--- + +### Git committer + +Handles git operations. + +```markdown title="~/.config/opencode/agent/commit.md" +--- +description: Creates well-formatted git commits +mode: subagent +permission: + edit: deny + bash: + "git *": allow + "*": deny +--- + +You are a git expert. When creating commits: + +1. Review staged changes with git diff --staged +2. Write clear, conventional commit messages +3. Keep commits focused and atomic +4. Follow the repository's commit conventions + +Commit message format: + +- Start with type: feat, fix, docs, refactor, test, chore +- Keep subject line under 72 characters +- Use imperative mood ("add feature" not "added feature") +``` + +--- + +## Best practices + +Tips for effective subagent usage. + +--- + +### Write clear descriptions + +The `description` field determines when primary agents delegate automatically. Be specific. + +```yaml +# Good - specific about when to use +description: Reviews Python code for PEP 8 compliance and type hints + +# Bad - too vague +description: Reviews code +``` + +--- + +### Restrict tools appropriately + +Only enable tools the agent needs. Read-only agents shouldn't have write access. + +```yaml +# Security auditor - read only +tools: + write: false + edit: false + bash: false +``` + +--- + +### Use lower temperature for precise tasks + +Code review, security audits, and analysis benefit from deterministic responses. + +```yaml +temperature: 0.1 +``` + +--- + +### Be explicit about intent in prompts + +Tell the agent whether to research or make changes. + +```markdown +You are a code reviewer. Analyze code and provide feedback. +Do NOT make changes directly - only suggest improvements. +``` + +--- + +### Use maxSteps for cost control + +Limit iterations for agents that might run long. + +```yaml +maxSteps: 15 +``` + +--- + +## Cheat sheet + +| Action | How | +| -------------------------- | -------------------------------------- | +| Invoke subagent | `@agent-name your request` | +| Navigate to child session | `+Right` | +| Navigate to parent session | `+Left` | +| Create global agent | `~/.config/opencode/agent/name.md` | +| Create project agent | `.opencode/agent/name.md` | +| Disable agent | `disable: true` in config | +| Read-only agent | `tools: { write: false, edit: false }` | +| Limit iterations | `maxSteps: 10` | From 4a2beb48423c0a9d30035b32f98ce859e479deeb Mon Sep 17 00:00:00 2001 From: Ryan Vogel Date: Mon, 22 Dec 2025 05:33:47 -0500 Subject: [PATCH 3/3] docs: add Commands guide for automation workflows - Add comprehensive guide for custom commands - Cover template syntax: $ARGUMENTS, $1/$2, shell injection, file refs - Document all configuration options - Include 7 practical example commands: - Test runner, PR reviewer, Commit helper - Documentation generator, Dependency checker - Quick refactor, Type checker - Explain subtask mode and subagent integration - Add best practices and cheat sheet - Update sidebar to include commands guide --- packages/web/astro.config.mjs | 2 +- .../web/src/content/docs/guides/commands.mdx | 559 ++++++++++++++++++ 2 files changed, 560 insertions(+), 1 deletion(-) create mode 100644 packages/web/src/content/docs/guides/commands.mdx diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs index 9cc834938..535c07529 100644 --- a/packages/web/astro.config.mjs +++ b/packages/web/astro.config.mjs @@ -60,7 +60,7 @@ export default defineConfig({ "1-0", { label: "Guides", - items: ["guides/first-hour", "guides/subagents"], + items: ["guides/first-hour", "guides/subagents", "guides/commands"], }, { label: "Usage", diff --git a/packages/web/src/content/docs/guides/commands.mdx b/packages/web/src/content/docs/guides/commands.mdx new file mode 100644 index 000000000..9d854f708 --- /dev/null +++ b/packages/web/src/content/docs/guides/commands.mdx @@ -0,0 +1,559 @@ +--- +title: Commands +description: Automate repetitive workflows with custom commands. +lastUpdated: 2025-12-21 +--- + +Custom commands let you save prompts you run frequently. Instead of typing the same instructions repeatedly, create a command once and run it with `/command-name`. + +**The essentials**: + +- Create commands in `~/.config/opencode/command/` (global) or `.opencode/command/` (project) +- Use `$ARGUMENTS` for input, `$1`/`$2` for positional args +- Use `` !`command` `` to inject shell output +- Use `@file` to include file contents +- Set `subtask: true` to run in a child session + +--- + +## Quick example + +Create a file `.opencode/command/test.md`: + +```markdown title=".opencode/command/test.md" +--- +description: Run tests and fix failures +--- + +Run the test suite. If any tests fail, analyze the failures and fix them. +``` + +Now run it: + +```txt frame="none" +/test +``` + +That's it. The prompt in the file is sent to the LLM. + +--- + +## Create commands + +Commands can be defined as markdown files or in JSON config. + +--- + +### File locations + +| Location | Path | Scope | +| -------- | --------------------------------- | ----------------- | +| Global | `~/.config/opencode/command/*.md` | All projects | +| Project | `.opencode/command/*.md` | That project only | + +The filename becomes the command name. `review.md` creates `/review`. + +--- + +### Markdown format + +Create a markdown file with YAML frontmatter for options and the body as the prompt template. + +```markdown title=".opencode/command/lint.md" +--- +description: Lint and fix code issues +agent: build +--- + +Run the linter and fix any issues found. Show me what you changed. +``` + +--- + +### JSON format + +Alternatively, add commands to `opencode.json`: + +```json title="opencode.json" +{ + "$schema": "https://opencode.ai/config.json", + "command": { + "lint": { + "description": "Lint and fix code issues", + "template": "Run the linter and fix any issues found. Show me what you changed.", + "agent": "build" + } + } +} +``` + +--- + +## Template syntax + +Commands support special placeholders to make them dynamic. + +--- + +### $ARGUMENTS + +Captures everything after the command name. + +```markdown title=".opencode/command/explain.md" +--- +description: Explain code or concepts +--- + +Explain $ARGUMENTS in simple terms with examples. +``` + +Usage: + +```txt frame="none" +/explain how the auth middleware works +``` + +The `$ARGUMENTS` placeholder becomes `how the auth middleware works`. + +--- + +### Positional arguments + +Use `$1`, `$2`, `$3`, etc. for specific arguments. + +```markdown title=".opencode/command/rename.md" +--- +description: Rename a symbol across the codebase +--- + +Rename all occurrences of $1 to $2 across the codebase. +Update imports and references. +``` + +Usage: + +```txt frame="none" +/rename getUserData fetchUserProfile +``` + +- `$1` = `getUserData` +- `$2` = `fetchUserProfile` + +:::tip +The last positional argument captures all remaining text. So `/cmd a b c d` with `$1` and `$2` gives `$2` = `b c d`. +::: + +--- + +### Shell output + +Inject command output with `` !`command` ``. + +```markdown title=".opencode/command/review-diff.md" +--- +description: Review uncommitted changes +--- + +Here are the current uncommitted changes: + +!`git diff` + +Review these changes for bugs, style issues, and potential improvements. +``` + +The shell command runs and its output is inserted into the prompt. + +You can use multiple shell commands: + +```markdown title=".opencode/command/status.md" +--- +description: Project status overview +--- + +Git status: +!`git status --short` + +Recent commits: +!`git log --oneline -5` + +Test results: +!`npm test 2>&1 | tail -20` + +Give me a summary of the project status. +``` + +--- + +### File references + +Include file contents with `@filepath`. + +```markdown title=".opencode/command/review-file.md" +--- +description: Review a specific file +--- + +Review @$1 for: + +- Code quality +- Potential bugs +- Performance issues + +Suggest improvements. +``` + +Usage: + +```txt frame="none" +/review-file src/auth/login.ts +``` + +The file content is automatically included in the prompt. + +--- + +## Configuration options + +All available options for commands. + +| Option | Required | Description | +| ------------- | -------- | -------------------------------------------- | +| `template` | Yes | The prompt template (body in markdown files) | +| `description` | No | Shown in command list | +| `agent` | No | Which agent runs the command | +| `model` | No | Override the model | +| `subtask` | No | Run as child session | + +--- + +### description + +Brief text shown when listing commands. + +```yaml +description: Run tests and fix failures +``` + +--- + +### agent + +Specify which agent executes the command. + +```yaml +agent: plan +``` + +If the agent is a subagent (like `@explore`), the command automatically runs as a subtask. Use `subtask: false` to override this. + +--- + +### model + +Override the model for this command. Format is `provider/model`. + +```yaml +model: anthropic/claude-sonnet-4 +``` + +--- + +### subtask + +Force the command to run in a child session. + +```yaml +subtask: true +``` + +Benefits of subtask execution: + +- Keeps main conversation focused +- Doesn't consume primary context +- Can be navigated separately with `+Right/Left` + +Use this for commands that do extensive work you don't need in your main context. + +--- + +## Example commands + +Practical commands for common workflows. + +--- + +### Test runner + +Run tests and fix failures automatically. + +```markdown title=".opencode/command/test.md" +--- +description: Run tests and fix failures +--- + +Run the test suite: +!`npm test 2>&1` + +If any tests failed, analyze the failures and fix them. +If all tests pass, say so. +``` + +--- + +### PR reviewer + +Review changes before creating a PR. + +```markdown title=".opencode/command/pr-check.md" +--- +description: Review changes before PR +subtask: true +--- + +Review the changes on this branch: + +!`git log main..HEAD --oneline` + +!`git diff main...HEAD` + +Check for: + +1. Bugs or edge cases +2. Missing tests +3. Documentation needs +4. Code style issues + +Summarize what this PR does and flag any concerns. +``` + +--- + +### Commit helper + +Create well-formatted commits. + +```markdown title=".opencode/command/commit.md" +--- +description: Stage and commit changes +--- + +Here are the current changes: +!`git status --short` + +!`git diff` + +Stage the appropriate files and create a commit with a clear message. +Follow conventional commit format (feat:, fix:, docs:, etc.). +``` + +--- + +### Documentation generator + +Generate docs for a file. + +```markdown title=".opencode/command/docs.md" +--- +description: Generate documentation for a file +subtask: true +--- + +Generate documentation for @$1. + +Include: + +- Overview of what it does +- Public API/exports +- Usage examples +- Parameter descriptions + +Match the documentation style used elsewhere in this project. +``` + +Usage: + +```txt frame="none" +/docs src/utils/parser.ts +``` + +--- + +### Dependency checker + +Check for outdated or vulnerable dependencies. + +```markdown title=".opencode/command/deps.md" +--- +description: Check dependencies +subtask: true +--- + +Check the project dependencies: + +!`npm outdated 2>&1 || true` + +!`npm audit 2>&1 || true` + +Summarize: + +1. Significantly outdated packages +2. Security vulnerabilities +3. Recommended updates (prioritized by importance) +``` + +--- + +### Quick refactor + +Refactor code with specific instructions. + +```markdown title=".opencode/command/refactor.md" +--- +description: Refactor with instructions +--- + +Refactor @$1 with the following goal: $2 + +Preserve existing behavior. Show me the changes. +``` + +Usage: + +```txt frame="none" +/refactor src/api/users.ts extract the validation logic into a separate function +``` + +--- + +### Type checker + +Run type checking and fix errors. + +```markdown title=".opencode/command/types.md" +--- +description: Fix TypeScript errors +--- + +Run the type checker: +!`npx tsc --noEmit 2>&1` + +Fix any type errors found. Explain what was wrong and how you fixed it. +``` + +--- + +## Combine with subagents + +Commands and subagents work well together. + +--- + +### Run command as subagent + +Set `subtask: true` to run in a child session: + +```markdown title=".opencode/command/analyze.md" +--- +description: Deep code analysis +subtask: true +agent: explore +--- + +Do a thorough analysis of the codebase architecture. +Find patterns, potential issues, and areas for improvement. +``` + +This runs `@explore` in a child session, keeping your main context clean. + +--- + +### Invoke subagent in template + +Reference subagents directly in your template: + +```markdown title=".opencode/command/security.md" +--- +description: Security audit +--- + +@security-auditor Audit this codebase for security vulnerabilities. +Focus on authentication, authorization, and data validation. +``` + +This invokes your custom `@security-auditor` subagent. + +--- + +## Best practices + +--- + +### Keep commands focused + +Each command should do one thing well. + +```yaml +# Good - specific +description: Run unit tests with coverage + +# Bad - too broad +description: Test stuff +``` + +--- + +### Use subtask for heavy work + +Commands that do extensive exploration or analysis should use `subtask: true`: + +```yaml +subtask: true +``` + +This keeps your main conversation lean. + +--- + +### Include context in prompts + +Give the LLM enough context to succeed: + +```markdown +Here are the current test failures: +!`npm test 2>&1 | grep -A 5 "FAIL"` + +The relevant test file: +@src/**tests**/auth.test.ts + +Fix the failing tests. +``` + +--- + +### Use project-scoped commands + +Put project-specific commands in `.opencode/command/` so they're shared with your team: + +``` +.opencode/ + command/ + deploy-check.md # Pre-deployment checklist + db-migrate.md # Database migration helper + api-test.md # API endpoint testing +``` + +Commit these to git. + +--- + +## Cheat sheet + +| Syntax | Description | +| ----------------------- | -------------------------------- | +| `$ARGUMENTS` | All arguments after command name | +| `$1`, `$2`, `$3` | Positional arguments | +| `` !`cmd` `` | Inject shell command output | +| `@filepath` | Include file contents | +| `subtask: true` | Run in child session | +| `agent: name` | Use specific agent | +| `model: provider/model` | Override model |