Merge 4a2beb4842 into 83397ebde2

packages/web/astro.config.mjs

@@ -58,6 +58,10 @@ export default defineConfig({
         "enterprise",
         "troubleshooting",
         "1-0",
+        {
+          label: "Guides",
+          items: ["guides/first-hour", "guides/subagents", "guides/commands"],
+        },
         {
           label: "Usage",
           items: ["tui", "cli", "ide", "zen", "share", "github", "gitlab"],

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 `<Leader>+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                   |

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` |

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:
+
+- **`<Leader>+Right`** - Cycle forward through sessions
+- **`<Leader>+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  | `<Leader>+Right`                       |
+| Navigate to parent session | `<Leader>+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`                         |