[Feature]: Support .worktreeinclude when creating worktrees

[LunarRed]

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/server

Problem or use case

When T3 Code creates a Git worktree, ignored local files from the source checkout are missing. Projects commonly need files such as .env, .env.local, or config/secrets.json before setup commands, development servers, tests, or the agent can run correctly.

Claude Code and Codex both support a checked-in .worktreeinclude file at the repository root for this purpose:

• Claude Code reads .worktreeinclude for the Git worktrees it creates, including CLI, subagent, and desktop worktrees.
• Codex reads .worktreeinclude for local Codex-managed worktrees.

Both use Git ignore style patterns and copy matching ignored files from the source checkout into the new worktree. A repository can therefore define this requirement once for multiple agent tools, but T3 Code currently does not honor it.

The practical failure is that a T3 worktree can look valid while being unable to start the application or run its setup. The agent may then report missing configuration or spend time diagnosing a broken project when the required local file simply was not copied.

Proposed solution

When T3 Code creates a worktree:

1. Look for .worktreeinclude at the source repository root.
2. Read it using Git ignore style pattern matching.
3. Copy matching paths from the source checkout into the new worktree only when Git marks the source path as ignored.
4. Preserve project-relative paths and create required parent directories.
5. Complete the copy before any runOnWorktreeCreate action or first agent turn starts.
6. If .worktreeinclude is absent, keep the current behavior.

For safe default behavior, T3 Code should not copy tracked files, should not follow source symlinks, should reject paths that escape either repository root, and should not overwrite a destination file that already exists. Copy failures should be surfaced clearly instead of silently starting with an incomplete worktree.

Example:

# .worktreeinclude
.env
.env.local
config/secrets.json

This should require no new settings screen. The repository file is the explicit, project-scoped allowlist.

Why this matters

Repositories that already work in Claude Code or Codex should produce an equally usable worktree in T3 Code without requiring a second setup mechanism.

Supporting the existing file would:

• prevent setup commands and application startup from failing because local configuration is absent;
• stop agents from diagnosing missing-file problems that T3 Code can prevent during worktree creation;
• let teams maintain one checked-in allowlist across T3 Code, Claude Code, and Codex;
• avoid T3-specific per-user configuration that can drift between teammates.

Smallest useful scope

Support a root-level .worktreeinclude when T3 Code creates a local Git worktree:

• files only;
• Git ignore style patterns;
• copy only matching paths that are actually ignored;
• preserve relative paths;
• run before the existing automatic worktree setup action;
• no UI, manual sync action, directory copying, or custom per-user configuration.

Directory copying and additional policy controls could be considered separately if needed.

Alternatives considered

• Project action or Git post-checkout hook: This can copy files, but every user must configure or import it, and the repository may need tool-specific scripts. It also makes a simple declarative allowlist imperative.
• T3-specific dotenv settings: Closed issue dotenv sync for new worktrees #764 proposed a project-scoped UI allowlist limited to .env* files. That was closed as not planned. This request is narrower in product scope because it adds no UI or new configuration model and instead honors an existing cross-tool repository file.
• Known filename detection: Closed issue [Feature]: Copy or link .envrc in worktrees #1141 suggested copying or linking names such as .envrc and was closed as a duplicate of dotenv sync for new worktrees #764. Guessing filenames can copy the wrong local data, while .worktreeinclude is explicit.
• Agent instructions: Instructions run after worktree creation and can be missed or consume an agent turn before the project is usable.

Risks or tradeoffs

• The listed files may contain secrets. Copying must remain limited to paths explicitly selected by the repository's .worktreeinclude and already present on the user's machine. File contents should never be logged.
• Malicious or mistaken patterns must not escape the source or destination repository root.
• Symlinks can point outside the repository and should be skipped.
• Large matches can increase worktree creation time and disk usage. The smallest scope can support files only and leave directory copying for later.
• Claude Code and Codex differ in some edge-case behavior. T3 Code can begin with the conservative shared behavior described above.

Examples or references

• Claude Code worktree documentation: https://code.claude.com/docs/en/worktrees#copy-gitignored-files-into-worktrees
• Codex worktree documentation: https://developers.openai.com/codex/environments/git-worktrees#copy-ignored-local-files-into-managed-worktrees
• Prior T3 Code issue dotenv sync for new worktrees #764: dotenv sync for new worktrees #764
• Prior T3 Code issue [Feature]: Copy or link .envrc in worktrees #1141: [Feature]: Copy or link .envrc in worktrees #1141
• Related hook-output issue feat: Surface post-checkout hook output during worktree creation #551: feat: Surface post-checkout hook output during worktree creation #551

Contribution

• I would be open to helping implement this.

[ryanleichty]

Dito

[theDanielJLewis]

YES! We need this for effective worktree use!

[theDanielJLewis]

Maybe Theo never uses .env files?

Anyway, what are you doing in the meantime to easily copy or symlink your important git-ignored files?

[LunarRed]

Anyway, what are you doing in the meantime to easily copy or symlink your important git-ignored files?

I worked around this globally with Worktrunk rather than copying or symlinking files manually. I installed Worktrunk through mise and configured a global Git post-checkout hook that runs:

mise --no-config exec worktrunk@latest -- \
  wt step copy-ignored --require-include

The hook only runs when Git creates a worktree and the repository has a .worktreeinclude file. That makes it work for T3 Code and anything else that uses a normal git worktree add. Repositories without .worktreeinclude are unaffected.

It works well for me, but it is still a local workaround.

[Arsik0153]

My workaround:
Create project script and check "Run automatically on worktree creation"
Paste this command:

set -e

[ -e .env ] || cp "$T3CODE_PROJECT_ROOT/.env" .env

[jpambrun]

I feel like this is standard now? Does t3 support any alternative?

[jskorlol]

This feature is absolutely essential.
Without it, smooth development in worktree mode is impossible.

[raeperd]

+1, I need this too.

.worktreeinclude isn't an official standard, but it's a widely followed convention:

• Gitignore-style patterns in a root-level file
• Only files that match and are gitignored get copied into the new worktree

Already supported by:

• Claude Code
• Codex
• Conductor
• Roo Code

Also proposed via PR in opencode, pando, arc-framework, wtm and geniro-app.

The earlier T3 Code implementation, #7956, was closed without merging. Honoring the existing file would make repos that already work in Claude Code/Codex work in T3 Code too.

[josepozuelo]

+1 it's pretty much the standard in other coding apps.

[drzett]

The first thing happening to me after sending my first ever prompt in t3 code ... was a missing file in my worktree. The model then scanned the repo by itself, found my .worktreeinclude and copied the missing files over to it's t3 worktree... 🤣. Funny, but also shows:

The feature is missing. Should be integrated.

[devohmycode]

I'd like maintainer approval for the direction and scope of this before opening a PR, since #7956 was closed for lacking it.

Proposed scope (server only, no contract or client change): when the source checkout has a .worktreeinclude at its root, GitVcsDriver.createWorktree copies the ignored, untracked files its gitignore-style patterns match, before setup scripts run. It applies to every worktree creation path. Tracked files and files already in the worktree are never touched. A failed copy only logs a warning and never blocks worktree creation.

Performance, measured on this repo under Windows:

• git ls-files --others --ignored --exclude-from=.worktreeinclude, the approach in feat(server): copy .worktreeinclude files into new worktrees #7956, walks all of node_modules: about 50 s.
• Listing ignored entries with --exclude-standard --directory, then filtering them with the ignore package: 4 to 9 s, because ignored folders are not walked.
• Without a .worktreeinclude, worktree creation runs no extra git command, so the existing single-discovery tests still pass.

One deliberate difference from strict gitignore matching: a pattern without a slash (.env) is not searched inside an ignored folder like node_modules. Naming the folder (secrets/) or an anchored path inside it (config/local/*.json) works.

A working implementation with a test is in my fork: devohmycode#1. Would you accept a PR with this scope?
@t3dotgg 😸

[theDanielJLewis]

I think we might have to @-mention a maintainer in order to bring this to their attention because I doubt they have the time to read every comment.