| name | opencode-config |
| description | Working on config and plugins for opencode |
Global config in ~/.config/opencode and project-local config in ./.opencode
Opencode source code is
Guides
command_tutorial.md describes creating commands in opencode
What opencode looks for in .opencode
The project-local .opencode/ directory is discovered by walking up from the current directory to the worktree root, finding every ancestor with a .opencode folder. All discovered directories contribute to a combined config layer (with later/higher precedence in some cases).
Config Files
| File | What it configures |
|---|
opencode.json / .jsonc | Main project configuration (merged from all .opencode dirs) |
tui.json / .jsonc | TUI-specific settings: keybindings, theme preferences |
Subdirectories
| Directory | Contents |
|---|
agent/ or agents/ | Custom agent definitions (*.md) |
command/ or commands/ | Custom slash commands (*.md) |
plugin/ or plugins/ | Local plugins (*.ts / .js) |
mode/ or modes/ | Mode definitions (*.md) |
themes/ | Custom TUI themes (*.json) |
plans/ | Session plan files (*.md) — auto-generated (VCS-backed projects only) |
bin/ | Installation binaries (managed by the installer) |
Root-Level Files
AGENTS.md — Project-level instructions injected into agent prompts (can also live at any ancestor directory, not just .opencode)
CONTEXT.md / CLAUDE.md — Also discovered as instruction files up the tree
Flags That Control Discovery
| Flag | Effect |
|---|
OPENCODE_CONFIG_DIR | Override base config directory path |
OPENCODE_CONFIG | Point to a specific opencode.json file |
OPENCODE_TUI_CONFIG | Point to a specific tui.json file |
OPENCODE_DISABLE_PROJECT_CONFIG | Skip all project-local .opencode discovery entirely |
Priority Order
Config directories are collected in this order (later = higher precedence in merge):
- Global config dir (
~/.config/opencode)
- Project-local
.opencode dirs (walked up from cwd → worktree)
- Home
.opencode (~/.opencode)
OPENCODE_CONFIG_DIR env var override
Within the project-local chain, the deepest .opencode (closest to cwd) has highest precedence. Multiple nested .opencode dirs (e.g., monorepo + subproject) are all merged.