OpenCode CLI reference - Config files
OpenCode config files and locations
OpenCode documents 31 config files, including opencode.json, opencode.jsonc and ~/.config/opencode/opencode.json. These are the files and directories OpenCode reads its configuration from. Each row gives the docs' description, accepted values and an example where one is documented.
Last verified 14 official pagesFull OpenCode reference
| Path | Description |
|---|---|
opencode.json | Project config file in the project root (JSON or JSONC); OpenCode looks in the current directory then traverses up to the nearest Git directory. Docs: opencode.json |
opencode.jsonc | JSONC (JSON with Comments) form of the OpenCode config file. Docs: opencode.jsonc |
~/.config/opencode/opencode.json | Global config for user-wide server/runtime preferences like providers, models and permissions. Docs: ~/.config/opencode/opencode.json |
~/.config/opencode/tui.json | Global TUI-specific settings file (also tui.jsonc); project tui.json can sit alongside opencode.json. Docs: ~/.config/opencode/tui.json |
tui.json | TUI config file (or tui.jsonc) for theme, keybinds, scrolling, cursor, mouse and attention settings, separate from opencode.json. Docs: tui.json |
.well-known/opencode | Remote organizational config endpoint fetched when authenticating with a supporting provider; loaded first as the base layer. Docs: .well-known/opencode |
/Library/Application Support/opencode/ | macOS managed config directory for an admin-controlled opencode.json or opencode.jsonc at highest priority. Docs: /Library/Application Support/opencode/ |
/etc/opencode/ | Linux managed config directory for admin-controlled opencode.json or opencode.jsonc. Docs: /etc/opencode/ |
%ProgramData%\opencode | Windows managed config directory for admin-controlled opencode.json or opencode.jsonc. Docs: %ProgramData%\opencode |
/Library/Managed Preferences/<user>/ai.opencode.managed.plist | macOS per-user managed preferences (ai.opencode.managed domain via MDM .mobileconfig); plist keys map to opencode.json fields. Docs: /Library/Managed Preferences/<user>/ai.opencode.managed.plist |
/Library/Managed Preferences/ai.opencode.managed.plist | macOS machine-wide managed preferences for the ai.opencode.managed domain. Docs: /Library/Managed Preferences/ai.opencode.managed.plist |
.opencode/ | Project directory for agents/, commands/, modes/, plugins/, skills/, tools/ and themes/ (plural names; singular also supported). Docs: .opencode/ |
~/.local/share/opencode/auth.json | Credentials file for provider API keys and OAuth tokens added via /connect or opencode auth login. Docs: ~/.local/share/opencode/auth.json |
~/.local/share/opencode/mcp-auth.json | Where OAuth tokens for MCP servers are stored after opencode mcp auth. Docs: ~/.local/share/opencode/mcp-auth.json |
~/.local/share/opencode/ | Application data directory (sessions, auth.json, log/, project/). Windows: %USERPROFILE%\.local\share\opencode. Docs: ~/.local/share/opencode/ |
~/.local/share/opencode/log/ | Log directory; files are timestamped and the most recent 10 are kept. Docs: ~/.local/share/opencode/log/ |
~/.cache/opencode | Cache directory including provider packages and npm plugins (node_modules); can be deleted to force reinstall. Docs: ~/.cache/opencode |
AGENTS.md | Project rules file with custom instructions included in the LLM context; created or updated by /init. Docs: AGENTS.md |
~/.config/opencode/AGENTS.md | Global rules applied across all opencode sessions. Docs: ~/.config/opencode/AGENTS.md |
CLAUDE.md | Claude Code compatible project rules fallback, used if no AGENTS.md exists. Docs: CLAUDE.md |
~/.claude/CLAUDE.md | Claude Code compatible global rules fallback, used if no ~/.config/opencode/AGENTS.md exists. Docs: ~/.claude/CLAUDE.md |
.opencode/agents/ | Per-project markdown agent definitions; file name becomes the agent name. Global: ~/.config/opencode/agents/. Docs: .opencode/agents/ |
.opencode/commands/ | Per-project markdown custom commands; file name becomes the command name. Global: ~/.config/opencode/commands/. Docs: .opencode/commands/ |
.opencode/skills/<name>/SKILL.md | Project skill location; also ~/.config/opencode/skills, .claude/skills, ~/.claude/skills, .agents/skills and ~/.agents/skills. Docs: .opencode/skills/<name>/SKILL.md |
.opencode/plugins/ | Project-level plugin directory; global plugins live in ~/.config/opencode/plugins/. Docs: .opencode/plugins/ |
.opencode/package.json | Declares npm dependencies for local plugins and custom tools; OpenCode runs bun install at startup. Docs: .opencode/package.json |
.opencode/tools/ | Project custom tool definitions; global custom tools go in ~/.config/opencode/tools/. Docs: .opencode/tools/ |
~/.config/opencode/themes/*.json | User custom theme directory; project themes go in .opencode/themes/*.json. Docs: ~/.config/opencode/themes/*.json |
.ignore | File in the project root that re-includes paths ignored by .gitignore for ripgrep-based tools like grep and glob. Docs: .ignore |
.github/workflows/opencode.yml | GitHub Actions workflow file for the OpenCode GitHub agent. Docs: .github/workflows/opencode.yml |
$HOME/intelephense/license.txt | File containing only a PHP Intelephense license key for premium features (Windows: %USERPROFILE%/intelephense/license.txt). Docs: $HOME/intelephense/license.txt |
The rest of the OpenCode reference
FAQ
How many config files does OpenCode have?
The official OpenCode docs list 31 config files, including opencode.json, opencode.jsonc and ~/.config/opencode/opencode.json. All of them are in the table above, in the docs' order.
What does opencode.json do in OpenCode?
Project config file in the project root (JSON or JSONC); OpenCode looks in the current directory then traverses up to the nearest Git directory.
Where are OpenCode config files documented?
On 14 official docs pages at opencode.ai, last read on October 17, 2026. Every row in the table links the exact section it came from.
More on OpenCode
- OpenCode in the tools directoryWhat it is, who makes it and how it fits next to other coding agents.
- OpenCode errors and fixes17 error messages, quoted verbatim, with the documented fix for each.
Use other models in OpenCode
Setup guides from the model-in-tool directory, each with the env vars and base URL from official docs.
Sources
Last verified . Names and examples are copied verbatim from the 14 official pages below, and every row above links the exact section it came from.
- opencode.ai/docs/config/11 items
- opencode.ai/docs/tui/1 item
- opencode.ai/docs/troubleshooting/4 items
- opencode.ai/docs/mcp-servers/1 item
- opencode.ai/docs/rules/4 items
- opencode.ai/docs/agents/1 item
- opencode.ai/docs/commands/1 item
- opencode.ai/docs/skills/1 item
- opencode.ai/docs/plugins/2 items
- opencode.ai/docs/custom-tools/1 item
- opencode.ai/docs/themes/1 item
- opencode.ai/docs/tools/1 item
- opencode.ai/docs/github/1 item
- opencode.ai/docs/lsp/1 item
Newsletter
Know when your tools change
One email per week. New coding agent releases, the flags and commands they add, and what they mean for how you work.