[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