Customizing OpenCode
Configure OpenCode behavior through config files, agents, commands, and extensions.
Config File Locations
| Location | Path | Purpose |
|---|---|---|
| Global | ~/.config/opencode/opencode.json | User-wide preferences |
| Project | ./opencode.json | Project-specific settings |
| Custom | $OPENCODE_CONFIG env var | Override path |
Precedence (later overrides earlier): Remote .well-known/opencode < Global < Custom < Project
Quick Reference
| Task | Where | Reference |
|---|---|---|
| Set theme, model, autoupdate | opencode.json | config-schema.md |
| Define specialized agents | .opencode/agents/*.md or config | agents.md |
| Create slash commands | .opencode/commands/*.md or config | commands.md |
| Add external tools via MCP | opencode.json mcp section | mcp-servers.md |
| Write custom tool functions | .opencode/tools/*.ts | custom-tools.md |
| Extend with plugins/hooks | .opencode/plugins/*.ts or npm | plugins.md |
| Control tool access | opencode.json permission section | permissions.md |
| Customize keyboard shortcuts | opencode.json keybinds section | keybinds.md |
| Change colors/appearance | opencode.json theme or custom JSON | themes.md |
Directory Structure
code
~/.config/opencode/ # Global config ├── opencode.json ├── AGENTS.md # Global rules ├── agents/ # Global agents ├── commands/ # Global commands ├── plugins/ # Global plugins ├── skills/ # Global skills ├── tools/ # Global custom tools └── themes/ # Global custom themes .opencode/ # Project config (same structure) ├── agents/ ├── commands/ ├── plugins/ ├── skills/ ├── tools/ └── themes/
When to Use What
| Need | Solution |
|---|---|
| Change model/theme for all projects | Global opencode.json |
| Project-specific agent behavior | Project .opencode/agents/ |
| Reusable prompt templates | Commands (.opencode/commands/) |
| External service integration | MCP servers |
| Custom logic the LLM can call | Custom tools |
| React to OpenCode events | Plugins |
| Restrict dangerous operations | Permissions |
Variable Substitution
Use in any config value:
jsonc
{
"model": "{env:OPENCODE_MODEL}", // Environment variable
"instructions": ["{file:./rules.md}"] // File contents
}
Rules (AGENTS.md)
Project instructions loaded into LLM context:
| File | Scope |
|---|---|
./AGENTS.md | Project (traverses up to git root) |
~/.config/opencode/AGENTS.md | Global |
instructions array in config | Additional files/globs |
jsonc
{
"instructions": ["CONTRIBUTING.md", "docs/*.md"]
}
Docs
Full documentation: https://opencode.ai/docs/config/