# 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: **** 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/.md` or `.opencode/agents/.md` | | Global agents | `~/.config/opencode/agent(s)/.md` | | Project skills | `.opencode/skill(s)//SKILL.md` | | Global skills | `~/.config/opencode/skill(s)//SKILL.md` | | External skills (auto-loaded) | `~/.claude/skills//SKILL.md`, `~/.agents/skills//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`, plus optionally `scout` (gated on `OPENCODE_EXPERIMENTAL_SCOUT`). Hidden internal agents: `compaction`, `title`, `summary`. To override a built-in's fields, define the same key in `agent: { : { ... } }`. ## 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`. 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, repo_clone, repo_overview, 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.