Skip to content

CowboyLogic/ai-dev / skills/client-config-opencode

client-config-opencode

Verified

Manage OpenCode configuration files (V2 native format by default, V1 supported) including MCP servers, providers, models, agents, commands, permissions, policies, skills, plugins, CLI/TUI settings, keybinds, and themes. Use this skill whenever the user wants to view, edit, add, migrate, or understand any opencode setting in opencode.json(c), cli.json, or tui.json. Trigger on: "configure opencode", "add provider", "set model", "add MCP server", "create agent", "configure permissions", "change theme", "add keybind", "show opencode config", "add custom command", "migrate opencode config to V2", or "opencode cli.json".

FileKindSize
CHANGELOG.mdmarkdown18.6 KB
README.mdmarkdown3.9 KB
SKILL.mdskill md8.8 KB
evals/evals.jsonconfig6.7 KB
references/agents.mdmarkdown5.4 KB
references/config-schema.mdmarkdown14.1 KB
references/mcp.mdmarkdown5.1 KB
references/permissions.mdmarkdown5.2 KB
references/providers.mdmarkdown10.8 KB
references/tui.mdmarkdown12.7 KB
references/v2/agents.mdmarkdown5.1 KB
references/v2/cli.mdmarkdown11.1 KB
references/v2/config-schema.mdmarkdown31.8 KB
references/v2/mcp.mdmarkdown10.3 KB
references/v2/migration.mdmarkdown8.9 KB
references/v2/permissions.mdmarkdown16.1 KB
references/v2/plugins.mdmarkdown8.6 KB
references/v2/providers.mdmarkdown21.4 KB
scripts/show-config.pyscript14.2 KB
scripts/update-references.pyscript3.9 KB
sources.jsonconfig7.1 KB

references/v2/agents.md

View on GitHub
# V2 Agents Reference

Source: <https://opencode.ai/v2/docs/agents/> (2.2.5). Permission rules: [permissions.md](permissions.md).

## Built-in agents

| Agent | Mode | Purpose |
|-------|------|---------|
| `build` | `primary` | Default coding agent; tools and access outside the workspace are allowed, `.env` reads ask (external dirs asked in the 2.0.29 docs) |
| `plan` | `primary` | Explores and plans; no edits to normal project files (may write OpenCode plan files) |
| `general` | `subagent` | Research and multi-step work; cannot launch more subagents |
| `explore` | `subagent` | Searches and reads code or web sources without editing |
| `compaction`, `title`, `summary` | hidden | Maintenance; not selectable |

V2 has **no built-in `scout` agent** (V1 had one). Override a built-in by defining the same ID.

## Locations

```text
~/.config/opencode/agents/<name>.md      # global
.opencode/agents/<name>.md               # project (discovered from cwd up to the project root)
```

Nested paths become part of the ID: `.opencode/agents/team/reviewer.md` → `team/reviewer`.
V2 still discovers the V1 directories `agent/`, `mode/`, and `modes/` (files under `mode(s)/` are primary agents);
`agents/` is preferred.

## Markdown format

Frontmatter accepts the same fields as an `agents` entry; the body becomes `system`.

```markdown
---
description: Reviews changes for correctness and regressions
mode: subagent
model: anthropic/claude-sonnet-4-5#high
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Review the current changes. List findings in severity order with file and line references.
```

## JSON format

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "reviewer": {
      "description": "Reviews current changes",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5#high",
      "system": "Report findings in severity order.",
      "steps": 8,
      "color": "#ff6b6b",
      "request": { "headers": { "x-agent": "reviewer" }, "body": { "temperature": 0.1 } },
      "permissions": [{ "action": "edit", "resource": "*", "effect": "deny" }],
    },
  },
}
```

## Fields

| Field | Description |
|-------|-------------|
| `description` | Shown to the model choosing a subagent — add it to every subagent |
| `mode` | `primary` (**default for a new custom agent**), `subagent`, or `all` |
| `model` | `provider/model[#variant]`, or `{ "providerID", "model", "variant" }`. A subagent without a model inherits the parent session's |
| `system` | System prompt; non-empty replaces the provider base prompt. In Markdown, use the body instead |
| `permissions` | Ordered rule array, appended after global rules |
| `steps` | Positive max model steps; on the last step tools are removed and the model summarizes |
| `hidden` | Hide from listings and the subagent catalog (visibility only, not security) |
| `color` | Six-digit hex, e.g. `"#ff6b6b"` |
| `disabled` | Remove a built-in or custom agent |
| `request` | `headers` and JSON `body` overlays (temperature, top_p, provider options). **Preserved but not yet sent** with model requests in V2 — set active request settings on the provider, model, or a model variant instead |

> [!WARNING]
> V1 agent frontmatter is deprecated. Each agent file is read as one format: a file that uses any of `permissions`,
> `request`, `system`, or `disabled` is read as V2, and V1 fields in it (`name`, `tools`, `permission`, `temperature`,
> and so on) are ignored with a warning in the log; other files that use V1 fields are read as V1 (2.2.x docs). Convert
> frontmatter all at once rather than mixing the two formats.
>
> Do not use V1 agent fields in new V2 agents: `prompt`, `permission`, `tools`, `disable`, `maxSteps`,
> `temperature`, `top_p`, `variant`, `options`, or `name`. Nested agent entries are not format-inferred — keep
> each entry entirely V1 or entirely V2.

The V2 doc documents color as a six-digit hex only; V1's theme color names (`primary`, `accent`, …) are not
mentioned for V2.

## Default agent and small model

```jsonc
{
  "default_agent": "writer",
  "agents": {
    "writer": { "mode": "primary" },
    "title": { "model": "anthropic/claude-haiku-4-5" },
  },
}
```

The default must exist, be visible, and be primary-capable; otherwise OpenCode uses `build`, then the first visible
primary agent. V1 `small_model` maps to `agents.title.model`.

## Merging

Definitions merge in configuration order: later scalars replace earlier ones, `request` maps merge by key, and
`permissions` rules append.

## Subagent control

The parent's `subagent` rules decide which agents it may launch; the child uses its own permissions.
Default nesting depth is one; raise it with `experimental.subagent_depth` (top-level `subagent_depth` is ignored in V2).

```jsonc
{
  "agents": {
    "orchestrator": {
      "permissions": [
        { "action": "subagent", "resource": "*", "effect": "deny" },
        { "action": "subagent", "resource": "reviewer", "effect": "allow" },
      ],
    },
  },
}
```

## TUI

`/agents` or `<leader>a` lists agents; `shift+tab` cycles (`agent.cycle`). Check what loaded with
`opencode debug agents`.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall