feat(core): add command registry (#30624)
This commit is contained in:
Dax
GitHub
parent
70bb710715
commit
1ff19103a2
150 changed files with 4642 additions and 2546 deletions
|
|
@ -4,8 +4,10 @@ import { Context, Deferred, Effect, Layer } from "effect"
|
|||
import { Auth } from "../auth"
|
||||
import { AgentV2 } from "../agent"
|
||||
import { Catalog } from "../catalog"
|
||||
import { CommandV2 } from "../command"
|
||||
import { Config } from "../config"
|
||||
import { ConfigAgentPlugin } from "../config/plugin/agent"
|
||||
import { ConfigCommandPlugin } from "../config/plugin/command"
|
||||
import { ConfigSkillPlugin } from "../config/plugin/skill"
|
||||
import { EventV2 } from "../event"
|
||||
import { FSUtil } from "../fs-util"
|
||||
|
|
@ -16,6 +18,8 @@ import { Npm } from "../npm"
|
|||
import { PluginV2 } from "../plugin"
|
||||
import { AccountPlugin } from "./account"
|
||||
import { AgentPlugin } from "./agent"
|
||||
import { CommandPlugin } from "./command"
|
||||
import { SkillPlugin } from "./skill"
|
||||
import { ConfigProviderPlugin } from "../config/plugin/provider"
|
||||
import { EnvPlugin } from "./env"
|
||||
import { ModelsDevPlugin } from "./models-dev"
|
||||
|
|
@ -26,6 +30,7 @@ type Plugin = {
|
|||
id: PluginV2.ID
|
||||
effect: PluginV2.Effect<
|
||||
| Catalog.Service
|
||||
| CommandV2.Service
|
||||
| Auth.Service
|
||||
| AgentV2.Service
|
||||
| Npm.Service
|
||||
|
|
@ -50,6 +55,7 @@ export const layer = Layer.effect(
|
|||
Service,
|
||||
Effect.gen(function* () {
|
||||
const catalog = yield* Catalog.Service
|
||||
const commands = yield* CommandV2.Service
|
||||
const plugin = yield* PluginV2.Service
|
||||
const accounts = yield* Auth.Service
|
||||
const agents = yield* AgentV2.Service
|
||||
|
|
@ -68,6 +74,7 @@ export const layer = Layer.effect(
|
|||
id: input.id,
|
||||
effect: input.effect.pipe(
|
||||
Effect.provideService(Catalog.Service, catalog),
|
||||
Effect.provideService(CommandV2.Service, commands),
|
||||
Effect.provideService(Auth.Service, accounts),
|
||||
Effect.provideService(AgentV2.Service, agents),
|
||||
Effect.provideService(Config.Service, config),
|
||||
|
|
@ -87,12 +94,15 @@ export const layer = Layer.effect(
|
|||
yield* add(EnvPlugin)
|
||||
yield* add(AccountPlugin)
|
||||
yield* add(AgentPlugin.Plugin)
|
||||
yield* add(CommandPlugin.Plugin)
|
||||
yield* add(SkillPlugin.Plugin)
|
||||
for (const item of ProviderPlugins) {
|
||||
yield* add(item)
|
||||
}
|
||||
yield* add(ModelsDevPlugin)
|
||||
yield* add(ConfigProviderPlugin.Plugin)
|
||||
yield* add(ConfigAgentPlugin.Plugin)
|
||||
yield* add(ConfigCommandPlugin.Plugin)
|
||||
yield* add(ConfigSkillPlugin.Plugin)
|
||||
}).pipe(Effect.withSpan("PluginBoot.boot"))
|
||||
|
||||
|
|
@ -110,6 +120,7 @@ export const layer = Layer.effect(
|
|||
|
||||
export const locationLayer = layer.pipe(
|
||||
Layer.provideMerge(Catalog.locationLayer),
|
||||
Layer.provideMerge(CommandV2.locationLayer),
|
||||
Layer.provideMerge(Config.locationLayer),
|
||||
Layer.provideMerge(AgentV2.locationLayer),
|
||||
Layer.provideMerge(SkillV2.locationLayer),
|
||||
|
|
|
|||
29
packages/core/src/plugin/command.ts
Normal file
29
packages/core/src/plugin/command.ts
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
export * as CommandPlugin from "./command"
|
||||
|
||||
import { Effect } from "effect"
|
||||
import { CommandV2 } from "../command"
|
||||
import { Location } from "../location"
|
||||
import { PluginV2 } from "../plugin"
|
||||
import PROMPT_INITIALIZE from "./command/initialize.txt"
|
||||
import PROMPT_REVIEW from "./command/review.txt"
|
||||
|
||||
export const Plugin = PluginV2.define({
|
||||
id: PluginV2.ID.make("command"),
|
||||
effect: Effect.gen(function* () {
|
||||
const command = yield* CommandV2.Service
|
||||
const location = yield* Location.Service
|
||||
const transform = yield* command.transform()
|
||||
|
||||
yield* transform((editor) => {
|
||||
editor.update("init", (command) => {
|
||||
command.template = PROMPT_INITIALIZE.replace("${path}", location.project.directory)
|
||||
command.description = "guided AGENTS.md setup"
|
||||
})
|
||||
editor.update("review", (command) => {
|
||||
command.template = PROMPT_REVIEW.replace("${path}", location.project.directory)
|
||||
command.description = "review changes [commit|branch|pr], defaults to uncommitted"
|
||||
command.subtask = true
|
||||
})
|
||||
})
|
||||
}),
|
||||
})
|
||||
65
packages/core/src/plugin/command/initialize.txt
Normal file
65
packages/core/src/plugin/command/initialize.txt
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
Create or update `AGENTS.md` for this repository.
|
||||
|
||||
The goal is a compact instruction file that helps future OpenCode sessions avoid mistakes and ramp up quickly. Every line should answer: "Would an agent likely miss this without help?" If not, leave it out.
|
||||
|
||||
User-provided focus or constraints (honor these):
|
||||
$ARGUMENTS
|
||||
|
||||
## How to investigate
|
||||
|
||||
Read the highest-value sources first:
|
||||
- `README*`, root manifests, workspace config, lockfiles
|
||||
- build, test, lint, formatter, typecheck, and codegen config
|
||||
- CI workflows and pre-commit / task runner config
|
||||
- existing instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
|
||||
- repo-local OpenCode config such as `opencode.json`
|
||||
|
||||
If architecture is still unclear after reading config and docs, inspect a small number of representative code files to find the real entrypoints, package boundaries, and execution flow. Prefer reading the files that explain how the system is wired together over random leaf files.
|
||||
|
||||
Prefer executable sources of truth over prose. If docs conflict with config or scripts, trust the executable source and only keep what you can verify.
|
||||
|
||||
## What to extract
|
||||
|
||||
Look for the highest-signal facts for an agent working in this repo:
|
||||
- exact developer commands, especially non-obvious ones
|
||||
- how to run a single test, a single package, or a focused verification step
|
||||
- required command order when it matters, such as `lint -> typecheck -> test`
|
||||
- monorepo or multi-package boundaries, ownership of major directories, and the real app/library entrypoints
|
||||
- framework or toolchain quirks: generated code, migrations, codegen, build artifacts, special env loading, dev servers, infra deploy flow
|
||||
- testing quirks: fixtures, integration test prerequisites, snapshot workflows, required services, flaky or expensive suites
|
||||
- important constraints from existing instruction files worth preserving
|
||||
|
||||
Good `AGENTS.md` content is usually hard-earned context that took reading multiple files to infer.
|
||||
|
||||
## Questions
|
||||
|
||||
Only ask the user questions if the repo cannot answer something important. Use the `question` tool for one short batch at most.
|
||||
|
||||
Good questions:
|
||||
- undocumented team conventions
|
||||
- branch / PR / release expectations
|
||||
- missing setup or test prerequisites that are known but not written down
|
||||
|
||||
Do not ask about anything the repo already makes clear.
|
||||
|
||||
## Writing rules
|
||||
|
||||
Include only high-signal, repo-specific guidance such as:
|
||||
- exact commands and shortcuts the agent would otherwise guess wrong
|
||||
- architecture notes that are not obvious from filenames
|
||||
- conventions that differ from language or framework defaults
|
||||
- setup requirements, environment quirks, and operational gotchas
|
||||
- references to existing instruction sources that matter
|
||||
|
||||
Exclude:
|
||||
- generic software advice
|
||||
- long tutorials or exhaustive file trees
|
||||
- obvious language conventions
|
||||
- speculative claims or anything you could not verify
|
||||
- content better stored in another file referenced via `opencode.json` `instructions`
|
||||
|
||||
When in doubt, omit.
|
||||
|
||||
Prefer short sections and bullets. If the repo is simple, keep the file simple. If the repo is large, summarize the few structural facts that actually change how an agent should work.
|
||||
|
||||
If `AGENTS.md` already exists at `${path}`, improve it in place rather than rewriting blindly. Preserve verified useful guidance, delete fluff or stale claims, and reconcile it with the current codebase.
|
||||
100
packages/core/src/plugin/command/review.txt
Normal file
100
packages/core/src/plugin/command/review.txt
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
You are a code reviewer. Your job is to review code changes and provide actionable feedback.
|
||||
|
||||
---
|
||||
|
||||
Input: $ARGUMENTS
|
||||
|
||||
---
|
||||
|
||||
## Determining What to Review
|
||||
|
||||
Based on the input provided, determine which type of review to perform:
|
||||
|
||||
1. **No arguments (default)**: Review all uncommitted changes
|
||||
- Run: `git diff` for unstaged changes
|
||||
- Run: `git diff --cached` for staged changes
|
||||
- Run: `git status --short` to identify untracked (net new) files
|
||||
|
||||
2. **Commit hash** (40-char SHA or short hash): Review that specific commit
|
||||
- Run: `git show $ARGUMENTS`
|
||||
|
||||
3. **Branch name**: Compare current branch to the specified branch
|
||||
- Run: `git diff $ARGUMENTS...HEAD`
|
||||
|
||||
4. **PR URL or number** (contains "github.com" or "pull" or looks like a PR number): Review the pull request
|
||||
- Run: `gh pr view $ARGUMENTS` to get PR context
|
||||
- Run: `gh pr diff $ARGUMENTS` to get the diff
|
||||
|
||||
Use best judgement when processing input.
|
||||
|
||||
---
|
||||
|
||||
## Gathering Context
|
||||
|
||||
**Diffs alone are not enough.** After getting the diff, read the entire file(s) being modified to understand the full context. Code that looks wrong in isolation may be correct given surrounding logic—and vice versa.
|
||||
|
||||
- Use the diff to identify which files changed
|
||||
- Use `git status --short` to identify untracked files, then read their full contents
|
||||
- Read the full file to understand existing patterns, control flow, and error handling
|
||||
- Check for existing style guide or conventions files (CONVENTIONS.md, AGENTS.md, .editorconfig, etc.)
|
||||
|
||||
---
|
||||
|
||||
## What to Look For
|
||||
|
||||
**Bugs** - Your primary focus.
|
||||
- Logic errors, off-by-one mistakes, incorrect conditionals
|
||||
- If-else guards: missing guards, incorrect branching, unreachable code paths
|
||||
- Edge cases: null/empty/undefined inputs, error conditions, race conditions
|
||||
- Security issues: injection, auth bypass, data exposure
|
||||
- Broken error handling that swallows failures, throws unexpectedly or returns error types that are not caught.
|
||||
|
||||
**Structure** - Does the code fit the codebase?
|
||||
- Does it follow existing patterns and conventions?
|
||||
- Are there established abstractions it should use but doesn't?
|
||||
- Excessive nesting that could be flattened with early returns or extraction
|
||||
|
||||
**Performance** - Only flag if obviously problematic.
|
||||
- O(n²) on unbounded data, N+1 queries, blocking I/O on hot paths
|
||||
|
||||
**Behavior Changes** - If a behavioral change is introduced, raise it (especially if it's possibly unintentional).
|
||||
|
||||
---
|
||||
|
||||
## Before You Flag Something
|
||||
|
||||
**Be certain.** If you're going to call something a bug, you need to be confident it actually is one.
|
||||
|
||||
- Only review the changes - do not review pre-existing code that wasn't modified
|
||||
- Don't flag something as a bug if you're unsure - investigate first
|
||||
- Don't invent hypothetical problems - if an edge case matters, explain the realistic scenario where it breaks
|
||||
- If you need more context to be sure, use the tools below to get it
|
||||
|
||||
**Don't be a zealot about style.** When checking code against conventions:
|
||||
|
||||
- Verify the code is *actually* in violation. Don't complain about else statements if early returns are already being used correctly.
|
||||
- Some "violations" are acceptable when they're the simplest option. A `let` statement is fine if the alternative is convoluted.
|
||||
- Excessive nesting is a legitimate concern regardless of other style choices.
|
||||
|
||||
---
|
||||
|
||||
## Tools
|
||||
|
||||
Use these to inform your review:
|
||||
|
||||
- **Explore agent** - Find how existing code handles similar problems. Check patterns, conventions, and prior art before claiming something doesn't fit.
|
||||
- **Exa Code Context** - Verify correct usage of libraries/APIs before flagging something as wrong.
|
||||
- **Web Search** - Research best practices if you're unsure about a pattern.
|
||||
|
||||
If you're uncertain about something and can't verify it with these tools, say "I'm not sure about X" rather than flagging it as a definite issue.
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
1. If there is a bug, be direct and clear about why it is a bug.
|
||||
2. Clearly communicate severity of issues. Do not overstate severity.
|
||||
3. Critiques should clearly and explicitly communicate the scenarios, environments, or inputs that are necessary for the bug to arise. The comment should immediately indicate that the issue's severity depends on these factors.
|
||||
4. Your tone should be matter-of-fact and not accusatory or overly positive. It should read as a helpful AI assistant suggestion without sounding too much like a human reviewer.
|
||||
5. Write so the reader can quickly understand the issue without reading too closely.
|
||||
6. AVOID flattery, do not give any comments that are not helpful to the reader.
|
||||
30
packages/core/src/plugin/skill.ts
Normal file
30
packages/core/src/plugin/skill.ts
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
export * as SkillPlugin from "./skill"
|
||||
|
||||
import { Effect } from "effect"
|
||||
import { PluginV2 } from "../plugin"
|
||||
import { AbsolutePath } from "../schema"
|
||||
import { SkillV2 } from "../skill"
|
||||
|
||||
export const Plugin = PluginV2.define({
|
||||
id: PluginV2.ID.make("skill"),
|
||||
effect: Effect.gen(function* () {
|
||||
const skill = yield* SkillV2.Service
|
||||
const transform = yield* skill.transform()
|
||||
const content = yield* Effect.promise(() => Bun.file(new URL("./skill/customize-opencode.md", import.meta.url)).text())
|
||||
|
||||
yield* transform((editor) => {
|
||||
editor.source(
|
||||
new SkillV2.EmbeddedSource({
|
||||
type: "embedded",
|
||||
skill: new SkillV2.Info({
|
||||
name: "customize-opencode",
|
||||
description:
|
||||
"Use ONLY when the user is editing or creating opencode's own configuration: opencode.json, opencode.jsonc, files under .opencode/, or files under ~/.config/opencode/. Also use when creating or fixing opencode agents, subagents, skills, plugins, MCP servers, or permission rules. Do not use for the user's own application code, or for any project that is not configuring opencode itself.",
|
||||
location: AbsolutePath.make("/builtin/customize-opencode.md"),
|
||||
content,
|
||||
}),
|
||||
}),
|
||||
)
|
||||
})
|
||||
}),
|
||||
})
|
||||
376
packages/core/src/plugin/skill/customize-opencode.md
Normal file
376
packages/core/src/plugin/skill/customize-opencode.md
Normal file
|
|
@ -0,0 +1,376 @@
|
|||
<!--
|
||||
Built-in skill. Name and description are registered in code at
|
||||
packages/core/src/plugin/skill.ts
|
||||
and CUSTOMIZE_OPENCODE_SKILL_DESCRIPTION). The body below becomes the
|
||||
skill's content.
|
||||
-->
|
||||
|
||||
# Customizing opencode
|
||||
|
||||
opencode validates its own config strictly and refuses to start when a field
|
||||
is wrong. The shapes below cover the common surface area, but they are a
|
||||
**summary, not the source of truth**.
|
||||
|
||||
## Full schema reference
|
||||
|
||||
The authoritative list of every config option — with field types, enums,
|
||||
defaults, and descriptions — lives in the published JSON Schema:
|
||||
|
||||
**<https://opencode.ai/config.json>**
|
||||
|
||||
If a field is not documented in this skill, or you need to confirm an exact
|
||||
shape before writing config, **fetch that URL and read the schema directly**
|
||||
rather than guessing. opencode hard-fails on invalid config, so the cost of a
|
||||
wrong shape is a broken startup.
|
||||
|
||||
Independently, every `opencode.json` should declare
|
||||
`"$schema": "https://opencode.ai/config.json"` so the user's editor catches
|
||||
mistakes as they type.
|
||||
|
||||
## Applying changes
|
||||
|
||||
Config is loaded once when opencode starts and is not hot-reloaded. After
|
||||
saving changes to `opencode.json`, an agent file, a skill, a plugin, or any
|
||||
other config-time file, **tell the user to quit and restart opencode** for
|
||||
the changes to take effect. The running session will keep using the
|
||||
already-loaded config until then.
|
||||
|
||||
## Where files live
|
||||
|
||||
| Scope | Path |
|
||||
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Project config | `./opencode.json`, `./opencode.jsonc`, or `.opencode/opencode.json` (opencode walks up from the cwd to the worktree root) |
|
||||
| Global config | `~/.config/opencode/opencode.json` (NOT `~/.opencode/`) |
|
||||
| Project agents | `.opencode/agent/<name>.md` or `.opencode/agents/<name>.md` |
|
||||
| Global agents | `~/.config/opencode/agent(s)/<name>.md` |
|
||||
| Project skills | `.opencode/skill(s)/<name>/SKILL.md` |
|
||||
| Global skills | `~/.config/opencode/skill(s)/<name>/SKILL.md` |
|
||||
| External skills (auto-loaded) | `~/.claude/skills/<name>/SKILL.md`, `~/.agents/skills/<name>/SKILL.md` |
|
||||
|
||||
Configs from each scope are deep-merged. Project overrides global. Unknown
|
||||
top-level keys in `opencode.json` are rejected with `ConfigInvalidError`.
|
||||
|
||||
## opencode.json
|
||||
|
||||
Every field is optional.
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"username": "string",
|
||||
"model": "provider/model-id",
|
||||
"small_model": "provider/model-id",
|
||||
"default_agent": "agent-name",
|
||||
"shell": "/bin/zsh",
|
||||
"logLevel": "DEBUG" | "INFO" | "WARN" | "ERROR",
|
||||
"share": "manual" | "auto" | "disabled",
|
||||
"autoupdate": true | false | "notify",
|
||||
"snapshot": true,
|
||||
"instructions": ["AGENTS.md", "docs/style.md"],
|
||||
|
||||
"skills": {
|
||||
"paths": [".opencode/skills", "/abs/path/to/skills"],
|
||||
"urls": ["https://example.com/.well-known/skills/"]
|
||||
},
|
||||
|
||||
"agent": {
|
||||
"my-agent": {
|
||||
"model": "anthropic/claude-sonnet-4-6",
|
||||
"mode": "subagent",
|
||||
"description": "...",
|
||||
"permission": { "edit": "deny" }
|
||||
}
|
||||
},
|
||||
|
||||
"command": {
|
||||
"deploy": { "description": "...", "prompt": "..." }
|
||||
},
|
||||
|
||||
"provider": {
|
||||
"anthropic": { "options": { "apiKey": "..." } }
|
||||
},
|
||||
"disabled_providers": ["openai"],
|
||||
"enabled_providers": ["anthropic"],
|
||||
|
||||
"mcp": {
|
||||
"playwright": {
|
||||
"type": "local",
|
||||
"command": ["npx", "-y", "@playwright/mcp"],
|
||||
"enabled": true,
|
||||
"env": {}
|
||||
},
|
||||
"remote-thing": {
|
||||
"type": "remote",
|
||||
"url": "https://...",
|
||||
"headers": { "Authorization": "Bearer ..." }
|
||||
}
|
||||
},
|
||||
|
||||
"plugin": [
|
||||
"opencode-gemini-auth",
|
||||
"opencode-foo@1.2.3",
|
||||
"./local-plugin.ts",
|
||||
["opencode-bar", { "option": "value" }]
|
||||
],
|
||||
|
||||
"permission": {
|
||||
"edit": "deny",
|
||||
"bash": { "git *": "allow", "*": "ask" }
|
||||
},
|
||||
|
||||
"formatter": false,
|
||||
"lsp": false,
|
||||
|
||||
"experimental": {
|
||||
"primary_tools": ["edit"],
|
||||
"mcp_timeout": 30000
|
||||
},
|
||||
|
||||
"tool_output": { "max_lines": 200, "max_bytes": 8192 },
|
||||
|
||||
"compaction": { "auto": true, "tail_turns": 15 }
|
||||
}
|
||||
```
|
||||
|
||||
Shape notes worth being explicit about:
|
||||
|
||||
- `model` always carries a provider prefix: `"anthropic/claude-sonnet-4-6"`.
|
||||
- `skills` is an object with `paths` and/or `urls`, not an array.
|
||||
- `agent` is an object keyed by agent name, not an array.
|
||||
- `plugin` is an array of strings or `[name, options]` tuples, not an object.
|
||||
- `mcp[name].command` is an array of strings, never a single string. `type` is required.
|
||||
- `permission` is either a string action or an object keyed by tool name.
|
||||
|
||||
## Skills
|
||||
|
||||
opencode's skill loader scans for `**/SKILL.md` inside skill directories. The
|
||||
file is named `SKILL.md` exactly, and lives in its own folder named after the
|
||||
skill:
|
||||
|
||||
```
|
||||
.opencode/skills/my-skill/SKILL.md
|
||||
```
|
||||
|
||||
Frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: One sentence covering what this skill does AND when to trigger it. Front-load the literal keywords or filenames the user is likely to say.
|
||||
---
|
||||
|
||||
# My Skill
|
||||
|
||||
(skill body in markdown: instructions, examples, references)
|
||||
```
|
||||
|
||||
- `name` is required, lowercase hyphen-separated, up to 64 chars, and matches the folder name.
|
||||
- `description` is effectively required: skills without one are filtered out and never surfaced to the model. Cover both _what_ the skill does and _when_ to use it. Write in third person ("Use when...", not "I help with..."). Front-load concrete trigger keywords and filenames; gate with "Use ONLY when..." if the skill should stay quiet on adjacent topics.
|
||||
- Optional: `license`, `compatibility`, `metadata` (string-string map).
|
||||
|
||||
Register skills from non-default locations via `skills.paths` (scanned
|
||||
recursively for `**/SKILL.md`) and `skills.urls` (each URL serves a list of
|
||||
skills).
|
||||
|
||||
## Agents
|
||||
|
||||
Two ways to define an agent. Use the file form for anything non-trivial.
|
||||
|
||||
### Inline (in `opencode.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": {
|
||||
"my-reviewer": {
|
||||
"description": "Reviews PRs for style violations.",
|
||||
"mode": "subagent",
|
||||
"model": "anthropic/claude-sonnet-4-6",
|
||||
"permission": { "edit": "deny", "bash": "ask" },
|
||||
"prompt": "You are a strict PR reviewer..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### File
|
||||
|
||||
```
|
||||
.opencode/agent/my-reviewer.md OR .opencode/agents/my-reviewer.md
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Reviews PRs for style violations.
|
||||
mode: subagent
|
||||
model: anthropic/claude-sonnet-4-6
|
||||
permission:
|
||||
edit: deny
|
||||
bash: ask
|
||||
---
|
||||
|
||||
You are a strict PR reviewer. Focus on...
|
||||
```
|
||||
|
||||
The file body becomes the agent's `prompt`. Do not also put `prompt:` in the
|
||||
frontmatter.
|
||||
|
||||
`mode` is one of `"primary"`, `"subagent"`, `"all"`.
|
||||
|
||||
Allowed top-level frontmatter fields: `name, model, variant, description, mode,
|
||||
hidden, color, steps, options, permission, disable, temperature, top_p`. Any
|
||||
unknown field is silently routed into `options`.
|
||||
|
||||
To disable a built-in agent: `agent: { build: { disable: true } }`, or in a
|
||||
file, `disable: true` in frontmatter.
|
||||
|
||||
`default_agent` must point to a non-hidden, primary-mode agent.
|
||||
|
||||
### Built-in agents
|
||||
|
||||
opencode ships with `build`, `plan`, `general`, `explore`. Hidden internal agents:
|
||||
`compaction`, `title`, `summary`. To override a built-in's fields, define the
|
||||
same key in `agent: { <name>: { ... } }`.
|
||||
|
||||
## Plugins
|
||||
|
||||
`plugin:` is an array. Each entry is one of:
|
||||
|
||||
```json
|
||||
"plugin": [
|
||||
"opencode-gemini-auth", // npm spec, latest
|
||||
"opencode-foo@1.2.3", // npm spec, pinned
|
||||
"./local-plugin.ts", // file path, relative to the declaring config
|
||||
"file:///abs/path/plugin.js", // file URL
|
||||
["opencode-bar", { "key": "val" }] // tuple form with options
|
||||
]
|
||||
```
|
||||
|
||||
Auto-discovered plugins (no config entry needed): any `*.ts` or `*.js` file in
|
||||
`.opencode/plugin/` or `.opencode/plugins/`.
|
||||
|
||||
A plugin module exports `default` (or any named export) of type
|
||||
`Plugin = (input: PluginInput, options?) => Promise<Hooks>`. The export is a
|
||||
function, not a plain object literal, and the function returns an object
|
||||
(return `{}` if there is nothing to register).
|
||||
|
||||
```ts
|
||||
import type { Plugin } from "@opencode-ai/plugin"
|
||||
|
||||
export default (async ({ client, project, directory, $ }) => {
|
||||
return {
|
||||
config: (cfg) => {
|
||||
// cfg is the live merged config; mutate fields here.
|
||||
},
|
||||
"tool.execute.before": async (input, output) => {
|
||||
// mutate output.args before the tool runs
|
||||
},
|
||||
}
|
||||
}) satisfies Plugin
|
||||
```
|
||||
|
||||
Hook surface (mutate `output` in place; return `void`):
|
||||
|
||||
- `event(input)`: every bus event
|
||||
- `config(cfg)`: once on init with the merged config
|
||||
- `chat.message`, `chat.params`, `chat.headers`
|
||||
- `tool.execute.before`, `tool.execute.after`
|
||||
- `tool.definition`
|
||||
- `command.execute.before`
|
||||
- `shell.env`
|
||||
- `permission.ask`
|
||||
- `experimental.chat.messages.transform`, `experimental.chat.system.transform`,
|
||||
`experimental.session.compacting`, `experimental.compaction.autocontinue`,
|
||||
`experimental.text.complete`
|
||||
|
||||
Special object-shaped (not callbacks): `tool: { my_tool: { ... } }`,
|
||||
`auth: { ... }`, `provider: { ... }`.
|
||||
|
||||
## MCP servers
|
||||
|
||||
`mcp:` is an object keyed by server name. Each server is discriminated by
|
||||
`type`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"playwright": {
|
||||
"type": "local",
|
||||
"command": ["npx", "-y", "@playwright/mcp"],
|
||||
"enabled": true,
|
||||
"env": { "BROWSER": "chromium" }
|
||||
},
|
||||
"github": {
|
||||
"type": "remote",
|
||||
"url": "https://...",
|
||||
"enabled": true,
|
||||
"headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
|
||||
},
|
||||
"old-server": { "enabled": false }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`command` is an array of strings. `type` is required. Use `enabled: false` to
|
||||
disable a server inherited from a parent config.
|
||||
|
||||
## Permissions
|
||||
|
||||
```json
|
||||
"permission": {
|
||||
"edit": "deny",
|
||||
"bash": { "git *": "allow", "rm *": "deny", "*": "ask" },
|
||||
"external_directory": { "~/secrets/**": "deny", "*": "allow" }
|
||||
}
|
||||
```
|
||||
|
||||
Actions: `"allow"`, `"ask"`, `"deny"`.
|
||||
|
||||
Per-tool value forms: `"allow"` shorthand (treated as `{"*": "allow"}`), or an
|
||||
object `{ pattern: action }`. Within an object, **insertion order matters**.
|
||||
opencode evaluates the LAST matching rule, so put broad rules first and narrow
|
||||
rules last.
|
||||
|
||||
`permission: "allow"` (a string at the top level) is shorthand for "allow
|
||||
everything" and is rarely what the user wants.
|
||||
|
||||
Known permission keys: `read, edit, glob, grep, list, bash, task,
|
||||
external_directory, todowrite, question, webfetch, websearch, lsp, doom_loop,
|
||||
skill`. Some of these (`todowrite,
|
||||
question, webfetch, websearch, doom_loop`) only accept a flat
|
||||
action, not a per-pattern object.
|
||||
|
||||
`external_directory` patterns are filesystem paths (use `~/`, absolute paths,
|
||||
or globs like `~/projects/**`).
|
||||
|
||||
Per-agent `permission:` overrides top-level `permission:`. Plan Mode lives on
|
||||
the `plan` agent's permission ruleset (`edit: deny *`).
|
||||
|
||||
## Escape hatches
|
||||
|
||||
When a user's config is broken and opencode won't start, these env vars help:
|
||||
|
||||
- `OPENCODE_DISABLE_PROJECT_CONFIG=1`: skip the project's local `opencode.json`
|
||||
and start from globals only. Run from the project directory, opencode loads,
|
||||
the user edits the broken file, then they restart without the flag.
|
||||
- `OPENCODE_CONFIG=/path/to/file.json`: load an additional explicit config.
|
||||
- `OPENCODE_CONFIG_CONTENT='{"$schema":"https://opencode.ai/config.json"}'`:
|
||||
inject inline JSON as a final local-scope merge.
|
||||
- `OPENCODE_DISABLE_DEFAULT_PLUGINS=1`: skip default plugins.
|
||||
- `OPENCODE_PURE=1`: skip external plugins entirely.
|
||||
- `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`,
|
||||
`OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`: skip the external skill scans under
|
||||
`~/.claude/` and `~/.agents/`.
|
||||
|
||||
## When proposing edits
|
||||
|
||||
- Validate against the schema before writing. If you are unsure of a field's
|
||||
exact shape, or the field is not covered in this skill, fetch
|
||||
`https://opencode.ai/config.json` and read the schema rather than guessing.
|
||||
- Preserve `$schema` and any existing fields the user did not ask to change.
|
||||
- For agent, skill, and plugin definitions, prefer creating new files in the
|
||||
correct location over inlining everything in `opencode.json`.
|
||||
- If the user's existing config is malformed, point them at the env-var escape
|
||||
hatches above so they can edit from inside opencode without breaking their
|
||||
session.
|
||||
- After saving any config change, remind the user to quit and restart opencode
|
||||
— running sessions keep using the already-loaded config.
|
||||
Loading…
Add table
Add a link
Reference in a new issue