customizing-opencode

name	customizing-opencode
description	Configure OpenCode via opencode.json, agents, commands, MCP servers, custom tools, plugins, themes, keybinds, and permissions. Use when setting up or modifying OpenCode configuration.

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/