Idea: respect the XDG Base Directory spec on Linux instead of a single ~/.dsh root

[anntnzrb]

Idea: respect the XDG Base Directory spec on Linux instead of a single ~/.dsh root

The problem

dsh keeps everything under one hardcoded root: ~/.dsh on every platform. Configuration, API keys, raw session transcripts, SQLite indexes, profiles, and skills all share one directory. The XDG Base Directory Specification defines a separate location for each of those classes, and the pre-release stance of this repo makes now the cheapest possible time to adopt it. A tagged release and a pile of community docs pointing at ~/.dsh would turn this from a small change into a migration.

What XDG says

The spec splits user files by purpose:

Variable	Default	Purpose
$XDG_CONFIG_HOME	$HOME/.config	user-specific configuration, the user equivalent of /etc
$XDG_DATA_HOME	$HOME/.local/share	user-specific data, the user equivalent of /usr/share
$XDG_STATE_HOME	$HOME/.local/state	persistent state, the user equivalent of /var/lib
$XDG_CACHE_HOME	$HOME/.cache	disposable cache, the user equivalent of /var/cache
$XDG_RUNTIME_DIR	set by pam_systemd	sockets and transient files, must be owned 0700

Mixing those classes in one directory has real costs:

• Home hygiene. $HOME is the user's namespace. Each app that creates its own dot-directory adds permanent ls -a noise the user cannot reorganize without breaking the app.
• Backup and dotfiles separation. Config belongs in a version-controlled dotfiles repo and weighs kilobytes. Session transcripts, attachments, and indexes can weigh gigabytes and are machine-local. With one root, a backup tool or dotfiles repo cannot express "back up my dsh config but not my session logs". It is all-or-nothing. The Arch Wiki XDG Base Directory page tracks this support matrix per application and files single-root layouts under "hardcoded".
• Different trust levels share one directory. .credentials.yaml and raw session logs are sensitive. settings.yaml and profiles are shareable. Splitting config from state lets users apply different encryption, permission, and sync policies per class.
• Platform conventions get ignored too. The same hardcoded path applies on macOS and Windows, which have their own standards.

Current behavior

defaultDshHome() is join(homedir(), '.dsh') with no platform split: packages/util/home-paths/src/index.ts:60-62. Resolution precedence is an explicit configured path, then $DSH_HOME, then that default. Everything lands under the one root: settings.yaml, .credentials.yaml, .env, cordis.patch.yml, profiles/, sessions/, skills/, and the SQLite query database. The default JSONL persistence root is dshHomePath('sessions'): packages/bundle/base/cordis.patch.yml:101.

Why now

The root AGENTS.md is explicit: pre-release means "foundation over blast radius". Rename freely, reject old on-disk formats, SESSION_FORMAT_VERSION stays at 0 with no compatibility promise. Every month of preview accumulates docs, tutorials, and tooling that point at ~/.dsh, so the migration cost grows monotonically. Today it is a rename. After the first tagged release it becomes a migration story with legacy fallbacks.

Precedent

OpenCode, the closest peer in this space, already resolves its paths through the xdg-basedir library at packages/core/src/global.ts:3-14:

import { xdgData, xdgCache, xdgConfig, xdgState } from "xdg-basedir"
const data = path.join(xdgData!, app)     // $XDG_DATA_HOME/opencode
const cache = path.join(xdgCache!, app)   // $XDG_CACHE_HOME/opencode
const config = path.join(xdgConfig!, app) // $XDG_CONFIG_HOME/opencode
const state = path.join(xdgState!, app)   // $XDG_STATE_HOME/opencode

The library's own README is blunt about scope: XDG is a Linux convention. On macOS and Windows you follow the platform's own conventions, and it recommends env-paths for cross-platform resolution. I think that split is right for dsh too. Linux gets the XDG layout, and the other platforms can get their native paths either in the same change or later, without one blocking the other.

Proposal

Split the home into XDG classes on Linux and keep $DSH_HOME as the single-root collapse override, so nothing that works today breaks:

Content	Proposed location on Linux
settings.yaml, .credentials.yaml, .env, cordis.patch.yml, profiles/, skills/	$XDG_CONFIG_HOME/dsh/, default ~/.config/dsh/
sessions/ transcripts and attachments, storage/	$XDG_DATA_HOME/dsh/, default ~/.local/share/dsh/
SQLite query and index databases	$XDG_STATE_HOME/dsh/, default ~/.local/state/dsh/
derived caches, if any appear	$XDG_CACHE_HOME/dsh/, default ~/.cache/dsh/
unix-socket surfaces, if any appear	$XDG_RUNTIME_DIR/dsh

Resolution precedence, highest first: an explicit configured path, then $DSH_HOME with its current single-root semantics, then the XDG split on Linux, then the platform convention elsewhere. The change should be contained in home-paths plus the default persistence and query roots in the base bundle patch, so most packages keep using the same path API.

Open questions:

• Does .credentials.yaml belong in config, where a dotfiles repo picks it up like .env, or in state, where it stays machine-local like session history? I lean config, but it is a policy question more than a technical one.
• Are session transcripts data or state? I say data: they are content produced for the user, parallel to OpenCode's data/repos and data/log. The SQLite index is derived state.
• Should ~/.dsh be read as a legacy fallback with a warning, or dropped outright? Given the pre-release stance I would drop it, but a one-line warning during preview costs nothing.

Alternatives considered

• Do nothing. Most tools do nothing. They also end up in the Arch Wiki's "hardcoded" table with a workaround section explaining how to fake XDG support with environment tricks. That is where single-root tools live, and it is avoidable here.
• $DSH_HOME only. Today's behavior. It pushes the configuration burden onto every user for something the ecosystem already standardizes, and it does nothing for macOS and Windows.
• $XDG_CONFIG_HOME only. The common half-measure. It still mixes session logs and credentials into config, which defeats the backup and encryption separation that makes XDG worth doing at all.

[Tobiichi-Origuchi]

google-gemini/gemini-cli#1825 (comment)

The Situation

Current behavior: "What's XDG? Is that a new cryptocurrency?"
~/ directory: sobbing in the corner, cluttered with .$everything

A Brief History of Home Directory Crimes

Once upon a time, Unix said: "Thou shalt not pollute thy home directory."
And developers said: "lol ok" and proceeded to create .myapp, .anotherapp, .seriously-another-one

Then came XDG Base Directory Specification (circa 2003 - yes, it's older than some of you):

• "Hey, maybe we should organize things?"
• "Config goes in ~/.config/"
• "Data goes in ~/.local/share/"
• "Revolutionary, I know."

Current status: It's 2025 and we're still debating this. Outstanding.

It's 2026 and we're still debating this. Outstanding.