[Feature]: configurable worktree location

[danielo515]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/web

Problem or use case

Hello. I currently have some requirements on some of my projects that doesn't allow me to put them in arbitrary locations. For example, the current location of the worktrees. I want them to be children of the main project folder so I can take advantage of all my local tools configured for that particular folder.

Proposed solution

I want a setting that I can adjust per project to tell where to create the worktrees, either in a global place or as children of the current worktree.

Why this matters

As I said I use tools that are folder-dependent to handle my available dependencies, and they will not be available if you put the worktree in some random place.

Smallest useful scope

All the people using direnv and flakes on parent directories and similar stuff

Alternatives considered

NOt using worktrees

Risks or tradeoffs

This will be backwards compatible

Examples or references

No response

Contribution

• I would be open to helping implement this.

[mhabegger]

This would be very helpful especially on Windows because of two reasons:

1. The dev drive usually runs ReFS and not NTFS, which is for small files. https://learn.microsoft.com/en-us/windows/dev-drive/
2. From company policy and attack surface reduction: the D-drive for depth is usually excluded from live scanning, https://learn.microsoft.com/en-us/defender-endpoint/microsoft-defender-endpoint-antivirus-performance-mode

[juliusmarminge]

#6975 proposes the same per-project worktree location with a literal path. It adds useful constraints: apply the setting server-side to desktop, mobile and PR-created threads, and allow the configured root in review/diff validation. Existing worktrees need not move.

[murbanowicz]

I had a go at this — #9681.

Follows the constraints @juliusmarminge listed: the root is resolved server-side, so new worktree threads, PRs opened as threads and mobile all land in the same place, and existing worktrees stay where they are. One difference worth flagging — for review/diff validation I ended up authorizing the worktree path each thread recorded rather than the project's current configured root. Same effect, but it keeps working after you change the setting, and it avoids a root like / authorizing everything.

@danielo515 your case works: set it to /path/to/myrepo/.worktrees and branches land at .worktrees/<branch>, so direnv walking up from there finds the .envrc in your main checkout. Worth gitignoring .worktrees/ so it doesn't show up as untracked. The one limitation is that the path has to be absolute — there's no way to say "relative to this project" yet. It's stored per checkout, so an absolute path is fine per machine, but if ./.worktrees is what you actually wanted, that'd be a follow-up.

@mhabegger Windows drive and UNC paths work, and a root the hosting server can't read as absolute is ignored rather than resolved somewhere unexpected.

First time contributing here so I'm not sure how you prefer to handle this — CONTRIBUTING says to discuss non-trivial changes first, which is why I'm posting rather than just leaving the PR sitting. CI also hasn't run on it; looks like it needs a maintainer to approve workflows for a first-time contributor. No expectations either way — happy for it to sit, or be closed if it's not a direction you want.

[danielo515]

The one limitation is that the path has to be absolute — there's no way to say "relative to this project" yet. It's stored per checkout, so an absolute path is fine per machine, but if ./.worktrees is what you actually wanted, that'd be a follow-up.

Where is that config stored? My main limitation is that I don't want 55 config files of each of the tools I'm trying. Relative path should be doable by quering git for the main folder of the repository. worktrunk does it that way

[murbanowicz]

@juliusmarminge — #9681 is rebased on current main and mergeable, if you ever want to look. It implements the constraints you listed here.

CI hasn't run on it, so there's nothing green to judge it by — it needs the workflow approval first-time contributors need. Genuinely no pressure either way; happy to close it if it's not wanted.

[DominicVonk]

@juliusmarminge — #11747 implements your constraints: server-side placement for desktop, mobile and PR-created threads, working review/diff access, and no relocation of existing worktrees. Related implementation: #9681. This is still under review, not shipped.

• Configuration: Location and layout have environment defaults and project overrides, stored in T3 settings. Other T3 state stays put. Paths must be absolute (~/ expands on the server); an explicit worktree path takes precedence. Removing a project override restores inheritance; an empty location uses the built-in default.
• Layouts: <repo-name>/<branch> (default) or <repo-name>-<branch> beneath the base directory. Branch slashes become hyphens. Both retain the repo name, unlike the direct <base>/<branch> layout proposed in [Feature]: Per-project worktree location #6975. Changes affect new worktrees only; existing ones are neither moved nor cleaned up.
• Edge cases: Project matching handles symlink aliases. Existing custom worktrees remain reviewable after changing/resetting settings; stale project folders do not block lookup. Discovery and recent-thread imports exclude linked worktrees, their subfolders and symlink aliases, while keeping ordinary checkouts beneath custom bases.
• Verification: Focused tests and a real web UI pass. The PR’s updated inline recording shows both layouts, project overrides and reset to inheritance. Placement alone does not configure direnv/nix or other directory-dependent tooling.

direnv workaround: reuse the source checkout’s environment

Worktree placement is not the only option. git remote get-url origin can identify a repo for an explicit mapping to a trusted local environment file, but the URL itself cannot locate the source checkout. For linked worktrees, Git’s shared metadata can.

For a normal non-bare checkout with a .git directory, use this in the worktree’s .envrc; it can also be tracked and shared with the main checkout:

git_dir=$(git rev-parse --absolute-git-dir) || return 1
common_dir=$(git rev-parse --path-format=absolute --git-common-dir) || return 1

if [[ "$git_dir" != "$common_dir" && "${common_dir##*/}" == ".git" ]]; then
  source_env "${common_dir%/.git}/.envrc"
else
  # Your normal main-checkout environment setup, e.g.:
  export PROJECT_ENV=development
fi

--git-common-dir locates the source checkout’s .git. source_env loads its .envrc from that directory, then restores the working directory; the main-checkout branch prevents recursion.

Review the file and run direnv allow in the worktree. The sourced file is not independently approval-checked, so the source checkout must be trusted. This shares its source-relative paths and virtual environments; use worktree-local setup when isolation matters. Bare repos and separate Git-directory layouts need an explicit local-path mapping.

The Git-path logic was checked with a temporary repo and linked worktree, including paths with spaces. References: Git shared-directory lookup, direnv source_env.

[tarurar]

+1 for project-relative worktree locations.

I use T3 Code locally on my laptop for both work and personal projects. My mise configuration selects CODEX_HOME and CLAUDE_CONFIG_DIR based on the project's parent directories.

When T3 creates a worktree under ~/.t3/worktrees, that worktree leaves the original configuration hierarchy and picks up my default profile. This also affects my directory-change hook, which links CODING_STANDARDS.md to the guidance for the active profile.

The new absolute worktree-location setting helps, but one shared directory does not preserve different profiles for different projects. Even if T3 starts the correct provider instance, directory-based mise configuration still depends on the worktree's actual path.

I'd like to configure .t3/worktrees once and have T3 resolve it relative to each project's main checkout. For example:

~/Sources/work/project-a/
└── .t3/worktrees/<branch>/

~/Sources/personal/project-b/
└── .t3/worktrees/<branch>/

This would preserve the existing profile rules without a separate absolute-path setting for every project.

[magroski]

Also agree with this one.

Some of my projects are very read-write intensive so I moved them to a separate external drive, while keeping pet projects at the main drive.

By forcing all worktrees to a single location, I would need to either move everything back to the main drive, or always carry the external drive with me.

This on top of things that are configured to manage the worktrees per project

[viclafouch]

#16231 shipped an absolute Worktree location, so worktrees can now move to another drive. The ask of this discussion stays open: worktrees as children of the project folder.

Problem

Claude Code creates claude --worktree checkouts under <repo>/.claude/worktrees/<name>/ (docs). A session there loads every CLAUDE.md and CLAUDE.local.md of the parent folders: the main checkout and the folders above it.

T3 creates worktrees under <T3 home>/worktrees/<repo>/<branch>. The same Claude session in a T3 worktree loses those files, and with them the user and team instructions that live above the repo.

The setting can't fix it for every project:

• resolveWorktreesDirectory accepts one absolute path and returns null for a relative one.
• The row is hidden in project scope.

Proposed solution

Accept a location relative to the project root, resolved per project, for example .claude/worktrees. New worktrees then land at <project>/.claude/worktrees/<branch>, the layout claude --worktree uses. One setting then covers every project and every environment. An empty value keeps today's default.

Risks

• The main checkout must ignore the folder. Claude Code asks users to add .claude/worktrees/ to .gitignore. T3 could run git check-ignore and warn when the folder is not ignored.
• Storage cleanup and isManagedWorktreePath need each project's folder in their list of managed roots.

[jdillon]

+1 for project-relative locations, with a use case where the folder hierarchy above the project matters, not just the project folder itself.

My projects are grouped in folders, and direnv loads a parent .envrc from each group (and from some intermediate folders) on the way down to a repo. For example:

• ~/projects/acme/.envrc
• ~/projects/acme/widget-api/.envrc
• ~/projects/acme/ops/infra/.envrc
• ~/projects/homelab/.envrc

A worktree only gets the right environment if it sits under the same group folder as its project. The absolute Worktree location from #16231 doesn't cover this: every worktree goes to <location>/<repo name>/<branch>, so a single folder can't follow the group, and a relative value like ../.t3code/ is rejected when the worktree is created.

Orca handles this with a relative workspace directory. I use ../.orca/ there, so ~/projects/acme/widget-api gets its worktrees at ~/projects/acme/.orca/widget-api/<branch> and ~/projects/acme/ops/infra gets ~/projects/acme/ops/.orca/infra/<branch>. The parent .envrc files keep applying and nothing ends up inside the repo.

I'd like the same in T3, with something like ../.t3code/ giving ~/projects/acme/.t3code/widget-api/<branch>.

T3 Code 0.1.5 (Beta), macOS.