Repository navigation
Docs miss mentioning XDG base directories for global configuration while already supporting them #6669
Description
Description
In the configuration documentation, it is only stated that the global configuration file is located at ~/.config/opencode/opencode.json. However, in cases where the XDG_CONFIG_HOME environment variable is set, OpenCode will look up the global configuration file in XDG_CONFIG_HOME/opencode/opencode.json. This also applies for all other global configurations and files.
It is amazing that opencode supports the XDG spec. I just came across this misinformation in the docs because I couldn't get my global configuration file to work (I have a different folder set as my XDG config home). IMHO, this should be aligned better in the docs, although I understand that many users won't know of XDG base directory variables.
OpenCode version
v1.0.223
Steps to reproduce
- Place a file with custom configuration in
~/.config/opencode/opencode.json - Run opencode with a custom
XDG_CONFIG_HOMEenvironment variable set (e.g.,export XDG_CONFIG_HOME="$HOME/.imaginary-folder" - Observe how the global configuration in
~/.config/opencode/opencode.jsondoes not have any effect anymore and$HOME/.imaginary-folder/opencodehas been created.
Screenshot and/or share link
Current documentation content: https://github.com/sst/opencode/blob/70881b2937fab1e425416659445875952730934a/packages/web/src/content/docs/config.mdx?plain=1#L41-L43
Relevant implementation specs:
- Defining
XDG_CONFIG_HOME/opencodeas the global config dir: https://github.com/sst/opencode/blob/70881b2937fab1e425416659445875952730934a/packages/opencode/src/global/index.ts#L10 - Relevant source code of
xdg-basedir: https://github.com/sindresorhus/xdg-basedir/blob/8cceade858e4da18cb971bf1844f086e9e213563/index.js#L10-L11 - Adding the global config dir to the locations that are searched for global
opencode.jsonfiles: https://github.com/sst/opencode/blob/47ebb2973f8bad2c98f4834de7f443b03b097ccd/packages/opencode/src/config/config.ts#L71
Operating System
macOS Tahoe 26.2 (25C56)
Terminal
Ghostty v1.2.3 (build 12214)
Activity
github-actions commentedon Jan 2, 2026
This issue might be a duplicate of existing issues. Please check:
Feel free to ignore if none of these address your specific case.
pwuersch commentedon Jan 2, 2026
I apologize for missing the discussion in #4170 which seems to partially relate to my concerns. However, I am not convinced that that big of a change is necessary, as stated in the issue description above. Hence, I wouldn't call this a duplicate.
I created a draft PR with a proposal on how to mention both the XDG base directory spec as well as the used default of
~/.config/opencodehere: #6670As a side note,
bugmight not be the appropriate label for this issue; it should rather only bedocs.github-actions commentedon Mar 25, 2026
To stay organized issues are automatically closed after 90 days of no activity. If the issue is still relevant please open a new one.
pwuersch commentedon Mar 25, 2026
The docs are still incorrect to this day, but I understand that interest in such minor details is low at the current time because of the high velocity in other areas.
fix(init): resolve the OpenCode global path properly and guard the block