mirror of
https://github.com/wesammustafa/opencode-primer.git
synced 2026-11-20 12:23:15 +00:00
- quickstart.md: 5-minute path from curl to first commit - zen.md: model gateway with full lineup, pricing, BYOK, patterns - tui.md: keybinds, leader chords, themes, customization, sessions - agents.md: custom agents and subagents, full frontmatter, permission map - commands.md: custom slash commands, placeholders, patterns, override rules - skills.md: discoverable workflows, SKILL.md format, description-as-trigger - plugins.md: lifecycle hooks, full event catalog, four real patterns - mcp.md: local/remote MCP, OAuth (DCR), token budget, featured servers, with mermaid N×M → N+M diagram - migration.md: Claude Code, Cursor, Copilot, Aider — with "what X does better" subsections so the comparisons aren't one-sided - workflows.md: seven real recipes (TDD, bug investigation, multi-agent review, cross-repo research, migrations, CI, visual iteration) — CI example shows GitHub Actions + GitLab CI to avoid platform bias Every model slug, permission key, config key, env var, and CLI flag verified against the JSON schema or the live docs site.
229 lines
6.8 KiB
Markdown
229 lines
6.8 KiB
Markdown
# Agents — Custom Agents & Subagents
|
|
|
|
> Custom agents let you bake a role, model choice, and permission profile into a markdown file. They show up in the Tab cycle (primary) or as `@mentions` (subagent).
|
|
|
|
## The agent zoo
|
|
|
|
Five OpenCode-built-in agents you should know:
|
|
|
|
| Name | Mode | Tools | Reach for it when… |
|
|
|---|---|---|---|
|
|
| `build` | primary (default) | All | Default daily-driver — implementation, refactors |
|
|
| `plan` | primary | `edit` & `bash` set to `"ask"` | Read-only-ish analysis — exploration, design |
|
|
| `general` | subagent | All minus `todowrite` | Big sub-tasks you want isolated from main context |
|
|
| `explore` | subagent | `read`, `grep`, `glob`, `list` | "Where is X?" code search |
|
|
| `scout` | subagent | `webfetch`, `websearch`, + read tools | External docs and dependency research |
|
|
|
|
Hit **Tab** to cycle primaries. Use `@<name>` in your prompt to invoke a subagent.
|
|
|
|
## Custom agents — file format
|
|
|
|
Two locations, same format:
|
|
|
|
| Scope | Path |
|
|
|---|---|
|
|
| Project | `.opencode/agents/<name>.md` |
|
|
| Global | `~/.config/opencode/agents/<name>.md` |
|
|
|
|
```markdown
|
|
---
|
|
description: Senior frontend engineer — Tailwind + React + TypeScript expert
|
|
mode: all
|
|
model: anthropic/claude-sonnet-4-5
|
|
temperature: 0.2
|
|
permission:
|
|
edit: allow
|
|
bash:
|
|
"*": "ask"
|
|
"pnpm test*": "allow"
|
|
"pnpm lint*": "allow"
|
|
"git status*": "allow"
|
|
webfetch: deny
|
|
tools:
|
|
websearch: false
|
|
---
|
|
|
|
You are a senior frontend engineer. Specifics:
|
|
- Use Tailwind for styling. Reach for CSS modules only when Tailwind can't express it.
|
|
- Components are TypeScript with named exports and explicit Props types.
|
|
- Tests use Vitest + @testing-library/react.
|
|
- Match existing patterns in `src/components/Button/` for new components.
|
|
```
|
|
|
|
### Frontmatter keys
|
|
|
|
Verified against the [config JSON schema's `AgentConfig`](https://opencode.ai/config.json):
|
|
|
|
| Key | Type | Purpose |
|
|
|---|---|---|
|
|
| `description` | string | Shown in `/agents` and surfaced to the LLM |
|
|
| `mode` | `primary` \| `subagent` \| `all` | How the agent can be invoked |
|
|
| `model` | `provider/model-id` | Per-agent model override |
|
|
| `temperature` · `top_p` | number | Sampling controls |
|
|
| `permission` | object | Per-tool `allow`/`ask`/`deny` (see below) |
|
|
| `tools` | object | Boolean per tool — `{"websearch": false}` |
|
|
| `prompt` *(JSON form only)* | string | System prompt; alternative to markdown body |
|
|
| `maxSteps` | number | Hard cap on agent steps in one invocation |
|
|
| `steps` | array | Scripted step sequence (advanced) |
|
|
| `disable` | boolean | Disable an agent entirely |
|
|
| `hidden` | boolean | Hide from the UI but keep available |
|
|
| `color` | string | UI accent color |
|
|
| `variant` · `options` | string · object | Model variant + per-provider options |
|
|
|
|
Only `description` and `mode` are required.
|
|
|
|
### Filename → agent name
|
|
|
|
The filename (minus `.md`) becomes the agent name. `security-auditor.md` → `@security-auditor`.
|
|
|
|
Naming rules: lowercase, alphanumeric, hyphens. No spaces, no underscores.
|
|
|
|
## Mode reference
|
|
|
|
| `mode` | Where it appears | Use when |
|
|
|---|---|---|
|
|
| `primary` | Tab cycle alongside `build`/`plan` | A persistent role you'll inhabit for hours |
|
|
| `subagent` | `@<name>` mentions, `task` tool | A focused helper for a specific sub-task |
|
|
| `all` | Both | You want flexibility (most custom agents) |
|
|
|
|
## Permission model
|
|
|
|
Permission keys (verified against `PermissionConfig` in the [config JSON schema](https://opencode.ai/config.json)):
|
|
|
|
| Key | Tools / behavior gated |
|
|
|---|---|
|
|
| `read` | `read` tool |
|
|
| `edit` | `write`, `edit`, `apply_patch` |
|
|
| `bash` | shell — supports glob-pattern overrides |
|
|
| `glob` · `grep` · `list` | search and listing |
|
|
| `task` | spawning subagents |
|
|
| `todowrite` | the in-session todo list |
|
|
| `question` | the `question` tool |
|
|
| `external_directory` | files outside the project root |
|
|
| `repo_clone` · `repo_overview` | repo-level operations |
|
|
| `webfetch` · `websearch` | network access |
|
|
| `lsp` | language server tools |
|
|
| `skill` | agent skill loading |
|
|
| `doom_loop` | runaway-loop safeguards |
|
|
|
|
Three values everywhere: `"allow"` (no prompt) · `"ask"` (prompt user) · `"deny"` (block).
|
|
|
|
### Glob-pattern bash
|
|
|
|
The `bash` key can be a single value or a glob-map. **Order matters**: most specific patterns first.
|
|
|
|
```json
|
|
{
|
|
"permission": {
|
|
"bash": {
|
|
"rm -rf*": "deny",
|
|
"git push --force*": "deny",
|
|
"git status*": "allow",
|
|
"git diff*": "allow",
|
|
"pnpm test*": "allow",
|
|
"*": "ask"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Use this to keep an agent productive (no constant prompting for safe reads) while still gating destructive commands.
|
|
|
|
## Choosing a model per agent
|
|
|
|
```json
|
|
{
|
|
"agent": {
|
|
"explore": { "model": "opencode/qwen3.6-plus" },
|
|
"scout": { "model": "opencode/qwen3.6-plus" },
|
|
"plan": { "model": "opencode/claude-opus-4-7" },
|
|
"build": { "model": "opencode/claude-sonnet-4-6" },
|
|
"deep-thinker": { "model": "openai/gpt-5", "reasoningEffort": "high" }
|
|
}
|
|
}
|
|
```
|
|
|
|
If unspecified:
|
|
- Primary agents inherit the global `model`.
|
|
- Subagents inherit the model from whatever agent invoked them.
|
|
|
|
## Tools per agent
|
|
|
|
The `tools` map enables/disables individual tools by name, including MCP tools (use glob patterns):
|
|
|
|
```json
|
|
{
|
|
"agent": {
|
|
"doc-writer": {
|
|
"tools": {
|
|
"bash": false,
|
|
"edit": true,
|
|
"websearch": false,
|
|
"github_*": false
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Note: `tools` is independent from `permission`. A tool can be enabled but still require `"ask"` per the permission map.
|
|
|
|
## Patterns
|
|
|
|
### Read-only reviewer
|
|
|
|
A subagent that reviews diffs but never writes. See [`specialized-agents/system-prompts/code-reviewer-prompt.md`](../specialized-agents/system-prompts/code-reviewer-prompt.md) for the full prompt.
|
|
|
|
```markdown
|
|
---
|
|
description: Reviews code without modifying files
|
|
mode: subagent
|
|
permission:
|
|
edit: deny
|
|
bash:
|
|
"*": "ask"
|
|
"git diff*": "allow"
|
|
---
|
|
```
|
|
|
|
### Specialist primary
|
|
|
|
A daily-driver agent with a baked-in role. Different model, different prompt, different defaults.
|
|
|
|
```markdown
|
|
---
|
|
description: Backend engineer — TypeScript, Postgres, REST
|
|
mode: primary
|
|
model: anthropic/claude-sonnet-4-5
|
|
permission:
|
|
bash:
|
|
"*": "ask"
|
|
"pnpm test*": "allow"
|
|
"pnpm typecheck*": "allow"
|
|
"psql*": "deny"
|
|
---
|
|
|
|
You're a backend engineer working on this monorepo's API…
|
|
```
|
|
|
|
### Cheap research subagent
|
|
|
|
Read-only, cheap model — `@scout`-replacement scoped to a specific knowledge area.
|
|
|
|
```markdown
|
|
---
|
|
description: Looks up React Router v7 patterns and idioms
|
|
mode: subagent
|
|
model: opencode/qwen3.6-plus
|
|
permission:
|
|
edit: deny
|
|
bash: deny
|
|
---
|
|
```
|
|
|
|
## Drop-in specialists
|
|
|
|
This repo ships 10 production-ready prompts in [`specialized-agents/`](../specialized-agents/). Copy any of them to `.opencode/agents/<name>.md` to use as a starting point.
|
|
|
|
> 📚 Full agent reference: [opencode.ai/docs/agents](https://opencode.ai/docs/agents).
|