Where OpenCode stores its database (and how to find it)

The one command that ends the guessing

Path advice ages badly. Releases change directories, package managers change defaults, and one environment variable changes everything. The CLI already knows the answer, so the reliable move is to ask it rather than to trust a blog post from last year, including this one.

opencode debug paths          # all paths, with labels
opencode debug paths db       # just the database file
opencode debug paths data     # the data directory
opencode debug paths config cache state log repos bin tmp home

The selector prints one line and exits. It does not start the background server and does not open the database, so it is safe to run while OpenCode is working. Relative overrides resolve under the data directory, and :memory: prints as-is, which tells you the install is not writing a file at all.

Two settings move the target. OPENCODE_DB overrides the database path, and XDG_DATA_HOME moves the whole data tree on Linux and macOS. If a tool shows no data while the TUI clearly has sessions, one of those is almost always the reason. The usage not showing checklist walks through the same causes in order.

Default locations, and why they differ

Defaults follow each platform's convention, which is why the folder name moves around while the contents stay the same.

The macOS line is deliberately two entries. Some builds follow the Linux convention and some follow Apple's application support convention, and neither is wrong. Run the command on the machine in front of you instead of picking the shorter path.

On Windows, %APPDATA% is the roaming profile, not %LOCALAPPDATA%. They are different folders and only one of them holds your sessions. In PowerShell, $env:APPDATA prints the first one, which is the value you want when a tracker asks for a directory.

What else sits in that folder

• opencode.db plus -wal and -shm files while the database is open. Copy all three or close OpenCode first.
• A storage directory in builds that predate the SQLite file, holding JSON for sessions, messages, and parts.
• log, bin, repos, cache, and state directories that the debug paths command labels individually.
• Configuration usually lives elsewhere, under ~/.config/opencode or %APPDATA% on Windows, depending on the build.

Backing up is a file copy, but timing matters. Copying only opencode.db while a write-ahead log is pending can lose the newest messages. Close the app, or copy the database together with its sidecar files, then open the copy read-only.

Once you know the path, the useful next step is reading it. The token usage explainer maps the columns, and the session history guide shows how to pull a specific conversation back out. Exporting a CSV is covered in the export walkthrough if you would rather work in a spreadsheet.

Questions, answered