e97f85bd53
* Add OpenCode converter coverage and specs * Add Codex target support and spec docs * Generate Codex command skills and refresh spec docs * Add global Codex install path * fix: harden plugin path loading and codex descriptions * feat: ensure codex agents block on convert/install * docs: clarify target branch usage for review * chore: prep npm package metadata and release notes * docs: mention opencode and codex in changelog * docs: update CLI usage and remove stale todos * feat: install from GitHub with global outputs
58 lines
3.5 KiB
Markdown
58 lines
3.5 KiB
Markdown
# OpenCode Spec (Config, Agents, Plugins)
|
|
|
|
Last verified: 2026-01-21
|
|
|
|
## Primary sources
|
|
|
|
```
|
|
https://opencode.ai/docs/config
|
|
https://opencode.ai/docs/tools
|
|
https://opencode.ai/docs/permissions
|
|
https://opencode.ai/docs/plugins/
|
|
https://opencode.ai/docs/agents/
|
|
https://opencode.ai/config.json
|
|
```
|
|
|
|
## Config files and precedence
|
|
|
|
- OpenCode supports JSON and JSONC configs. citeturn10view0
|
|
- Config sources are merged (not replaced), with a defined precedence order from remote → global → custom → project → `.opencode` directories → inline overrides. citeturn10view0
|
|
- Global config is stored at `~/.config/opencode/opencode.json`, and project config is `opencode.json` in the project root. citeturn10view0
|
|
- Custom config file and directory can be provided via `OPENCODE_CONFIG` and `OPENCODE_CONFIG_DIR`. citeturn10view0
|
|
- The `.opencode` and `~/.config/opencode` directories use plural subdirectory names (`agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, `themes/`), but singular names are also supported for backwards compatibility. citeturn10view0
|
|
|
|
## Core config keys
|
|
|
|
- `model` and `small_model` set the primary and lightweight models; `provider` configures provider options. citeturn10view0
|
|
- `tools` is still supported but deprecated; permissions are now the canonical control surface. citeturn1search0
|
|
- `permission` controls tool approvals and can be configured globally or per tool, including pattern-based rules. citeturn1search0
|
|
- `mcp`, `instructions`, and `disabled_providers` are supported config sections. citeturn1search5
|
|
- `plugin` can list npm packages to load at startup. citeturn1search2
|
|
|
|
## Tools
|
|
|
|
- OpenCode ships with built-in tools, and permissions determine whether each tool runs automatically, requires approval, or is denied. citeturn1search3turn1search0
|
|
- Tools are enabled by default; permissions provide the gating mechanism. citeturn1search3
|
|
|
|
## Permissions
|
|
|
|
- Permissions resolve to `allow`, `ask`, or `deny` and can be configured globally or per tool, with pattern-based rules. citeturn1search0
|
|
- Defaults are permissive, with special cases such as `.env` file reads. citeturn1search0
|
|
- Agent-level permissions override the global permission block. citeturn1search1turn1search0
|
|
|
|
## Agents
|
|
|
|
- Agents can be configured in `opencode.json` or as markdown files in `~/.config/opencode/agents/` or `.opencode/agents/`. citeturn1search1turn10view0
|
|
- Agent config supports `mode`, `model`, `temperature`, `tools`, and `permission`, and agent configs override global settings. citeturn1search1
|
|
- Model IDs use the `provider/model-id` format. citeturn1search1
|
|
|
|
## Plugins and events
|
|
|
|
- Local plugins are loaded from `.opencode/plugin/` (project) and `~/.config/opencode/plugin/` (global). npm plugins can be listed in `plugin` in `opencode.json`. citeturn1search2
|
|
- Plugins are loaded in a defined order across config and plugin directories. citeturn1search2
|
|
- Plugins export a function that returns a map of event handlers; the plugins doc lists supported event categories. citeturn1search2
|
|
|
|
## Notes for this repository
|
|
|
|
- Config docs describe plural subdirectory names, while the plugins doc uses `.opencode/plugin/`. This implies singular paths remain accepted for backwards compatibility, but plural paths are the canonical structure. citeturn10view0turn1search2
|