Honor XDG Base Directory paths on Linux

[repparw]

Problem

T3 Code currently keeps most persistent files under ~/.t3. T3CODE_HOME / --home-dir makes that tree relocatable, but configuration, state, logs, worktrees, attachments, caches, etc. still share one root.

#748 / #826 solved the configurable-base-directory problem, but not XDG Base Directory separation.

On Linux, it would be useful for T3 Code to honor the standard XDG locations when T3CODE_HOME is not explicitly set.

Possible layout

The exact classification depends on the semantics of the existing files, but roughly:

$XDG_CONFIG_HOME/t3/   configuration
$XDG_STATE_HOME/t3/    database/state, logs, possibly managed worktrees
$XDG_DATA_HOME/t3/     durable application/user data and attachments
$XDG_CACHE_HOME/t3/    regenerable caches
$XDG_RUNTIME_DIR/t3/   sockets/other runtime-only files, if applicable

with the standard fallbacks (~/.config, ~/.local/state, ~/.local/share, ~/.cache) when those variables are unset.

T3CODE_HOME could remain as an explicit override/backwards-compatible way to keep everything under one root.

Worktrees are a special case: for T3-managed worktrees, $XDG_STATE_HOME/t3/worktrees seems like a reasonable default because they are persistent machine/project-specific application state rather than cache. However, they can contain user changes, so independently configurable placement is useful regardless of the default; #9681 is addressing that part.

Related

• Add env var for configurable base or root directory #748 / feat: added configurable base directory. #826 — configurable T3 base directory
• feat(projects): configurable per-project worktree location #9681 — configurable per-project worktree location

Drafted with GPT-5.6 Sol via ChatGPT.

[juliusmarminge]

Thanks for the clear write-up.

Triage: this is a valid enhancement, not a bug. T3 still uses one relocatable home (~/.t3 by default; T3CODE_HOME / --home-dir / --base-dir to move it). Config, SQLite, logs, attachments, secrets, worktrees, and caches are derived from that single root (resolveBaseDir → deriveServerPaths). Desktop already uses XDG for Electron userData and .desktop files; that does not move server state.

Not a duplicate of #748 / #826. Those shipped the configurable single root. They did not split XDG categories.

Not in scope for #9681. That PR is per-project worktree location only. Useful if you want worktrees off the default tree; it does not honor XDG for the rest of the home, and this issue should not ride on that PR.

Prior implementation: #4419 (superseded) and #4437 (full five-root layout) were closed. #4437 was closed as an unsolicited cross-system architecture change that exceeds contribution policy. A correct XDG default is a storage-contract change (server, desktop, CLI, WSL/systemd, review/worktree path guards, docs) plus a safe policy for existing ~/.t3 installs — empty XDG dirs must not hide live data, and we should not auto-move SQLite/worktrees.

Workaround today: set T3CODE_HOME (or --home-dir) to keep everything under one chosen directory. That is still one tree, which is what this issue is asking to go beyond.

Next: leave open for a maintainer storage-layout decision (classification + new-vs-legacy policy). Please do not open another large XDG PR unless that design is accepted. Per CONTRIBUTING.md, a short Ideas discussion is the right place if you want to argue the product direction further.

[colonelpanic8]

@juliusmarminge You noted this is waiting on a maintainer storage-layout decision (classification + new-vs-legacy policy). I wrote up a classification in #19591 and staged it so the decision splits in two. Opt-in location overrides come first; they change no defaults, so they need no legacy policy. XDG defaults for new installs come later as their own decision. Would that sequencing work for you?