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
~/.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:
{
"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 |
{
"instructions": ["CONTRIBUTING.md", "docs/*.md"]
}
Docs
Full documentation: https://opencode.ai/docs/config/
