Repository navigation
Honor XDG Base Directory paths on Linux #10810
Description
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.
Activity
juliusmarminge commentedon Sep 8, 2026
Thanks for the clear write-up.
Triage: this is a valid enhancement, not a bug. T3 still uses one relocatable home (
~/.t3by default;T3CODE_HOME/--home-dir/--base-dirto move it). Config, SQLite, logs, attachments, secrets, worktrees, and caches are derived from that single root (resolveBaseDir→deriveServerPaths). Desktop already uses XDG for ElectronuserDataand.desktopfiles; 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
~/.t3installs — 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.