[Feature]: Let new-worktree threads attach to an existing branch instead of always forking a new one
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 23k
- Forks
- 5.9k
- Avg merge
- 11h 14m
- Merged PRs (30d)
- 357
Description
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 composer / thread bootstrap (apps/server orchestration)
Problem or use case
I run agents on a remote server environment; they work on a branch and push when done. To verify locally, I want my laptop's T3 to create a local worktree that checks out that exact branch.
Today, the workspace selector's "New worktree" mode only forks: the branch I pick is used as a base, and T3 always mints a fresh temp branch (buildTemporaryWorktreeBranchName) and runs git worktree add -b t3/<hex> <path> <picked>. There is no way to say "give me a worktree on this branch as-is" — I end up on a new branch, which breaks the verify→instruct loop: my local verification is not on the same ref the server agent is iterating on.
Proposed solution
When the selected branch already resolves to a real branch (local, or remote-only like origin/foo → derive the local name) and is not checked out in another worktree, attach the new worktree to it (git worktree add <path> <branch>) instead of forking a temp branch. Branches that don't exist or are already checked out (e.g. main in the primary checkout) keep today's fork behavior.
Note the server primitive already supports this: VcsCreateWorktreeInput.newRefName is optional, and GitVcsDriverCore.createWorktree runs plain git worktree add <path> <refName> when it's omitted — the composer/bootstrap path just never uses that form (prepareWorktree.branch is always set). The change is contained to the client bootstrap: omit prepareWorktree.branch when attaching and pass the existing branch through.
Details worth covering
- Remote-only branches need the
origin/foo→fooderivation (helper already exists in@t3tools/shared/git). - Skip the
startFromOriginbase-fetch path andgh-merge-baseconfig when attaching (no new branch is created). - The temp-branch rename reactor should be a no-op for attached branches (
isTemporaryWorktreeBranchwon't match) — worth a test. - Edge cases: branch deleted between pick and send, branch checked out in a third worktree, fork remotes.
- Mobile recently gained "start a new thread on an existing branch" (#10359) — semantics should agree across clients.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in the apps/web composer and thread bootstrap, then trace how prepareWorktree.branch reaches the apps/server orchestration, VcsCreateWorktreeInput, and GitVcsDriverCore.createWorktree. Check the existing shared/git helper for deriving foo from origin/foo. Done means existing, available branches attach without a temporary branch, while missing or checked-out branches retain fork behavior; cover the attached-branch rename reactor and relevant edge cases with tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, typescript
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100