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/