[Feature]: Adopt an existing local Git checkout as a T3 Code project

[christhomas]

Problem

T3 Code is oriented around creating projects by cloning or creating new
worktrees. There is no clear way to open an already-existing local checkout
and adopt it as a T3 Code project.

This affects:

• repositories already cloned on the machine;
• the repository's main checkout;
• worktrees created by Git or another tool;
• checkouts containing existing uncommitted work.

Without an adoption flow, users may create duplicate clones or project records,
making it easy to work in the wrong checkout. T3 Code should be able to attach
to the checkout that already exists.

Proposed solution

Add an Open existing checkout / Adopt existing project option alongside
the current clone/new-project flow.

The user should be able to:

1. Select an existing local directory.
2. Have T3 Code validate and resolve its Git repository root.
3. See the detected branch, checkout path, and whether it is a worktree.
4. Create a T3 Code project record pointing at that directory.
5. Start threads in that checkout without cloning, moving, or creating another
   worktree.

The selected checkout should be allowed to contain uncommitted changes.

If the path or repository is already registered, T3 Code should focus or reuse
the existing project instead of creating a duplicate.

Removing the T3 Code project should remove only T3 Code's project record; it
must not delete or modify the checkout.

Expected behavior

An existing checkout should become usable in T3 Code without requiring:

• git clone;
• git worktree add;
• moving the directory;
• creating a duplicate project;
• manually editing T3 Code state.

This is different from cloning a repository from a URL and different from
relinking a project after its directory has moved.

Related issues

• [Feature]: Enable renaming of project directories #2357 — Enable renaming of project directories
• [Bug]: Moving a project folder reports a Codex spawn failure instead of the missing folder, and the project cannot be re-linked #4940 — Moving a project folder reports an error and cannot be re-linked
• Let the agent move its thread into a worktree #3753 / Add worktree handoff and status tools to the t3-code MCP server #3754 — Worktree handoff, focused on creating a new worktree

[juliusmarminge]

Triage

This is a valid enhancement, not a duplicate of clone, relink-after-move, or worktree handoff.

What already exists

T3 Code can already attach a T3 project record to a directory that is already on disk. It does not require git clone or git worktree add.

• Web / desktop: Command palette Add project → Local folder (also from the empty-state / sidebar “New project” / “Add project” actions). Choosing a path that is already registered focuses that project instead of creating a second one.
• Mobile: Add project → Local folder, with the same path reuse.
• Desktop CLI: npx t3 app (or npx t3 app <path>) opens the current/given directory, adding the project if needed. This is the completed form of [Feature Request] Add cli command to open folder inside desktop app #517.
• Onboarding: the welcome wizard can import Claude/Codex checkouts. Linked git worktrees are intentionally not offered there.
• Delete: removing a T3 project removes the project record (and its threads), not the files on disk.
• Dirty trees: project.create only records workspaceRoot. Uncommitted work is not a blocker.
• New threads default to local workspace mode (defaultThreadEnvMode: "local"), so they start in that checkout unless the user/project default is New worktree.

Dedup today is path-scoped (same environment + same normalized workspaceRoot), which is the right model. Two checkouts of one remote (main + a worktree) should remain two projects.

What is still missing

The report is still right that there is no git-aware adopt step:

• No resolve-to-repository-root if the user picks a nested folder.
• No confirm UI showing branch, checkout path, and whether it is a worktree.
• Palette add can create a missing directory (createWorkspaceRootIfMissing: true) instead of requiring an existing checkout.
• Linked / externally created worktrees are easy to miss (onboarding skips them; [Bug]: Externally created Git worktrees are treated as “Local” #1714 is a separate recognition bug).
• Naming is “Add project” / “Local folder”, not “Open existing checkout”, so clone is the more obvious path and people recreate repos.

This is different from #4940 (relink after a folder moved), #2357 (rename), and #3753 / #3754 (handoff into a new worktree).

Recommended direction

Keep this issue open. Extend the existing Local folder flow rather than adding a parallel product:

1. After a directory is chosen, inspect Git (root, branch, worktree vs main checkout) and confirm before create.
2. Point the project at that checkout; allow a dirty tree; do not clone, move, or add a worktree.
3. If that path is already a project, focus/reuse it.
4. Ship the same confirm on web, desktop, and mobile.
5. Optionally offer linked worktrees in onboarding import.

Workaround until then: Add project → Local folder, or on desktop npx t3 app from the checkout.