Where Does OpenCode Store Config and Custom Agents?
Where OpenCode keeps its global and project config files, plus custom agents, commands, and skills on every OS.
Last updated
OpenCode splits its files across two scopes. Project config lives in the repo itself as opencode.json (or .opencode/opencode.json), while your personal defaults live in ~/.config/opencode/opencode.json. Project settings win when both define the same key.
Custom agents, commands, and skills are plain markdown files in matching folders, either per project under .opencode or global under ~/.config/opencode. Login tokens stay out of those files entirely, in a separate auth.json under the OS app data directory.
Where OpenCode stores this, by platform
~/.config/opencode
Holds opencode.json or opencode.jsonc plus agent/, command/, and skills/ subfolders. Project config found here overrides the global file for this repo only. Unknown top level keys make OpenCode refuse to start, so validate before saving.
~/.config/opencode
Same layout as macOS. On Windows prefer these paths when running inside WSL, which is the recommended setup. Auth state sits separately under the local app data dir, not in this folder.
%USERPROFILE%\.config\opencode
Global config goes in %USERPROFILE%\.config\opencode\opencode.json. Project files work the same as elsewhere: .\opencode.json or .\.opencode\opencode.json in the repo root. Restart the session after edits.
Frequently asked questions
where is the opencode config file
Edit ~/.config/opencode/opencode.json (create it if it is missing). Project files override globals, so check ./opencode.json and .opencode/opencode.json too. Restart OpenCode after saving, since config loads once at startup.
where do i put opencode agents and commands
As markdown files under .opencode in the project: agent/ for agents, command/ for commands, skills/<name>/SKILL.md for skills. Global versions of the same folders live under ~/.config/opencode/. Files beat inline JSON for anything non-trivial.
where does opencode store provider logins
In ~/.local/share/opencode/auth.json on macOS and Linux (the equivalent app data folder on Windows). It holds provider tokens, so keep it out of dotfile repos and screenshots.
Notice an outdated path? Let us know.