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/