Repository navigation
Reorganize and document dirs for config, agents, auth credentials, sessions #4170
Description
Description
Opencode docs give the incorrect impression that all configuration (aka everything worth preserving) is in ~/.config/opencode/ which is not true. If installed via Bun on Debian, more important things are in ~/.local/share/opencode/. Please reorganize/deduplicate dirs and document what is where (and what one should preserve).
~/.local/share/opencode/: Auth credentials, sessions, logs, and binaries (why are binaries not installed as requirements?).
auth.json bin log storage
~/.local/state/opencode: Recently used model (why separate from config?).
model.json
~/.config/opencode/: Main configuration if you create it (why is there no config by default?), and agent definitions if you create them. Dependencies (duplicates of .bun/install/cache/) (why is code under config?).
bun.lock node_modules package.json
~/.cache/opencode/: Dependencies (duplicates of .bun/install/cache/).
bun.lock models.json node_modules package.json version
OpenCode version
v1.0.55
Steps to reproduce
Run opencode in a clean environment (docker run -it --rm oven/bun:1.3-debian bash) and check what gets created in home dir.
Screenshot and/or share link
No response
Operating System
Debian
Terminal
No response
Activity
rekram1-node commentedon Nov 10, 2025
Most of this is because you as a user shouldn't touch any of the other files.
This is XDG Base Directory Specification
User configuration files: ~/.config/
User data files: ~/.local/share/
User cache files: ~/.cache/
User state files: ~/.local/state/
gw0 commentedon Nov 10, 2025
So why not have all configuration here? Like auth credentials (
~/.local/share/opencode/auth.json) and recently used model (~/.local/state/opencode/model.json)?Following XDG specs code (
node_modules) should not be there.rekram1-node commentedon Nov 10, 2025
We use the other ones because u as a user shouldn't be editing either of those manually
rekram1-node commentedon Nov 10, 2025
Everything in ~/.config/opencode is owned by u the user, we automatically install the opencode plugin dep in their because people kept getting confused about it not being installed
docs: Add configuration directory locations documentation (Fixes anom…
maiterth commentedon Apr 22, 2026
This solution requires to exclude all non configuration files from the configurations via .gitignore.
Issues #18633 and #18980 still stand with this response.
This is nicely split and detailed in the XDG specifications: https://specifications.freedesktop.org/basedir/latest/
Would be great to reconsider this choice or explicilty state that this project does not follow these specifications. (I would prefer if it would!)
currently my $XDG_CONFIG_HOME/opencode is filled with cache and state information, but the config is picked up from ~/.config/opencode.
This is exactly the opposite of what I expected would happen when I saw XDG variables are picked up by the project.
$XDG_DATA_HOME
$XDG_CACHE_HOME and
$XDG_STATE_HOME do exist and people manage their
$XDG_CONFIG_HOME via git.
Sorry to dig up closed issues.