Start the Add Project browser in the xdg-user-dirs Projects directory on Linux

[yzhou216]

Problem

xdg-user-dirs 0.20 (April 2026) gives every account a Projects directory by default. xdg-user-dirs-update creates ~/Projects and records it in ~/.config/user-dirs.dirs next to Documents and Downloads:

XDG_PROJECTS_DIR="$HOME/Projects"

The Add project browser does not use it. While Settings → General → Add project starts in is empty, the browser always opens at ~/. That fallback is hard-coded in the command palette (getAddProjectInitialQueryForEnvironment in apps/web/src/components/CommandPalette.tsx) and in the shared getAddProjectInitialQuery that mobile uses. Linux users who keep their code in the Projects directory have to open it every time, or type the path into the setting once per environment.

Proposal

While Add project starts in is empty, open the browser in the environment's xdg-user-dirs Projects directory when that directory exists. Otherwise keep ~/.

• The server resolves it, because the environment owns the filesystem. Remote, relay, and tunnel clients get the remote machine's directory. The server reads $XDG_CONFIG_HOME/user-dirs.dirs (default ~/.config/user-dirs.dirs) with the same rules as xdg-user-dirs' own xdg-user-dir, and sends the directory as a new optional ServerConfig.userProjectsRoot, for example ~/Projects. It is read when a client loads the server config, so edits apply on the next connect without a restart.
• Only an existing directory counts. xdg-user-dirs does not recreate a Projects directory the user deleted, and pointing a directory at $HOME is how it disables one. Both cases keep ~/.
• Linux and other freedesktop systems only. Windows and macOS keep ~/.
• The setting still wins. A non-empty Add project starts in works exactly as today, and resetting it returns to the Projects directory.
• Every client follows. The web and desktop command palette and the mobile Add Project screen share getAddProjectInitialQuery: the setting, then userProjectsRoot, then ~/. The desktop's native directory picker already takes its starting directory from the palette's path. The settings row shows the actual default (Leave empty to use "~/Projects/" when the Add Project browser opens.) instead of a hard-coded ~/, or Mixed when the environments in scope differ.
• Clones follow it. The Add Project clone destination already starts from the browser's directory, so Git URL and provider clones propose ~/Projects/<repo> instead of ~/<repo>. Prompt-link clones keep using <T3 home>/projects.
• Compatibility. Older servers don't send the field, so clients keep ~/. Older clients ignore it.

What changes for existing users

On Linux with a Projects directory and an empty setting, the browser opens one level deeper, in ~/Projects/, with .. at the top of the list, and clones started from Add project propose ~/Projects/<repo> instead of ~/<repo>. Anyone who prefers home can type ~/ into the setting. Nothing changes for users who already set the field, for machines without a Projects directory, or on Windows and macOS.

Not in scope

• Where New project creates directories. That stays <T3 home>/projects (Setting for where New project creates folders ("New projects are created in") #14973, feat(projects): configure the directory for new projects #18905).
• T3's own storage locations. This is separate from the XDG Base Directory proposal in Honor XDG Base Directory paths on Linux #17971.
• No new setting.

Alternatives considered

• Read the XDG_PROJECTS_DIR environment variable. xdg-user-dir 0.20 ignores it and reads only user-dirs.dirs, so this would disagree with the reference tool.
• Run xdg-user-dir PROJECTS. It adds a process per config load, is not installed everywhere, and prints $HOME when the key is missing.
• Resolve it in the client. That breaks remote environments, since the client cannot see the server's filesystem.
• Write the directory into the setting on first run. That is a hidden settings write, and it would stop following later changes to user-dirs.dirs.

Prototype

The prototype is up as #21132 with before and after screenshots: yzhou216/t3code@8951d75 on main at d0918f1, one commit, 10 files, +286/-15.

• Focused tests. The parser cases mirror what xdg-user-dirs 0.20's xdg-user-dir prints for the same lines: quoting, escapes, the last valid line winning, and the forms it rejects. The resolver cases cover a missing file, a deleted directory, a disabled directory, XDG_CONFIG_HOME, and Windows and macOS. Typecheck passes for server, web, mobile, contracts, and client-runtime.
• Manual check in a NixOS QEMU VM with xdg-user-dirs 0.20, using the web client:
  • An account set up by xdg-user-dirs-update opens in ~/Projects/, Git URL proposes ~/Projects/Hello-World, and Settings shows Leave empty to use "~/Projects/".
  • Setting the field to ~/Documents takes precedence, and resetting it returns to ~/Projects/.
  • Editing user-dirs.dirs takes effect on reconnect with no server restart. A missing directory falls back to ~/.
  • An account without user-dirs.dirs still opens at ~/.
  • One client connected to both accounts' servers opens each environment in its own directory, and the settings row shows Mixed.
• All of these checks were rerun on 8951d75.
• Not checked: the native mobile app (typechecked only) and the Electron shell, which uses the same palette code.

Would a maintainer approve this direction and scope? #21132 is waiting on that decision. If you would rather keep ~/ as the default and make this opt-in, I can rework it.

Edited on 2026-10-18: added that clones from Add project follow the new default (an earlier version listed clone destinations as out of scope), and linked #21132.

Prototype and write-up by Claude Opus 5.5 in Claude Code.