Workspace providers: pluggable create/remove commands (rift, CoW clones, Worktrunk), with support for non-git directories and cleanup on settle

[evbuildsnet]

Problem

T3 Code has one way to isolate a thread: git worktree add into ~/.t3/worktrees. That path is hardcoded in GitVcsDriverCore.createWorktree, and everything around it assumes git:

• A project that is not a git repository can never get an isolated workspace. It silently falls back to local, so every thread on that project shares one directory.
• A fresh worktree is a cold checkout. node_modules, .env, build caches and generated files are gone, and the runOnWorktreeCreate action has to rebuild them for every thread.
• The workspace is never released. Settling a thread leaves the directory on disk ([Feature]: Clean up worktrees for settled threads without deleting history #6856), and removal only happens on thread delete, as a client-side checkbox.

Several discussions already ask for a piece of this: copy-on-write clones instead of worktrees (#10853), driving worktrees through Worktrunk (#8953), and cleaning up when a thread settles (#6856, #6999, #6864). They are all the same missing abstraction.

Proposal: workspace providers

Make the git worktree a provider, and let a project pick a different one. A provider is three things, configured in t3.json or project settings:

{
  "workspace": {
    "create": "rift create --copy-all",   // runs in the project dir, prints the workspace path
    "remove": "rift remove --force",      // runs inside the workspace
    "requiresGit": false                  // default true; false lets plain directories use it
  }
}

Lifecycle:

1. New thread → run create in the project directory, take the printed path as the thread's worktreePath, start the session there. Existing runOnWorktreeCreate actions keep working since they only need the path.
2. Thread settled / archived → run remove inside the workspace. Same guards the team named when closing feat(server): clean worktree build artifacts when threads settle #8771: skip while a session is running, while terminals are open, or while another thread references the path.
3. Thread unsettled → run create again, exactly like the current "recreate a missing worktree on the next turn" behaviour.

The built-in git provider is git worktree add / git worktree remove with requiresGit: true, so nothing changes for anyone who does not opt in.

Motivating example: rift

rift makes copy-on-write clones of a directory using APFS clonefile. It does not care whether the directory is a git repo, or whether it holds several repos side by side. rift create --copy-all gives a full clone in well under a second, including node_modules and build output, so the agent starts warm. rift remove moves it to trash and unregisters it. It already has a .rift.toml postcreate hook and exposes RIFT_SOURCE / RIFT_DESTINATION to it.

I run this today by hand for every thread. The only thing missing is T3 Code calling it, and pointing the thread at the result.

Worktrunk (#8953) fits the same contract: wt switch --create --json <branch> prints a path, wt remove tears it down. A plain cp -c CoW clone (#10853) fits too.

Smallest useful scope

• workspace.create and workspace.remove in t3.json, requiresGit flag.
• Server runs create where git worktree add runs today and stores the path on the thread.
• A reactor on thread.settled that runs remove with the guards above.
• Non-git projects are allowed to use worktree mode when the provider does not require git.

No UI beyond what project settings already have for actions. Happy to contribute the implementation if this shape is welcome, and to fold it into the post-Orchestrator-V2 worktree lifecycle work the team mentioned in #8771.

[lingolooper-simon]

+1, from a game-dev monorepo, with a different reason than copy-on-write.

Our repo is a Unity game plus backend, web admin and services: 85k tracked files and 3.1 GB of Git LFS. 85% of the files and 2.8 GB of the LFS data are in the Unity project, which most agent tasks never touch. Every T3 worktree is a full checkout with every LFS object downloaded, and we run several at once. We've also had a delegate_task with worktree isolation fail outright during worktree creation (#25367).

We need a sparse cone and a worktree-local lfs.fetchexclude in place before the first checkout. runOnWorktreeCreate can't do that, because by the time it runs, git has already written every file and downloaded every binary. We already have a script that does it (worktree add --no-checkout, sparse-checkout set, config --worktree, then checkout). Right now our agents run it themselves and attach the thread as an existing worktree. That doesn't help with UI-created threads, delegate_task isolation or handoff, which all call git worktree add directly.

A workspace.create hook as proposed here would cover all of that. For this case it would need two things:

• create gets told what to make: the base ref, the branch name, and the path T3 would otherwise use (environment variables are fine).
• It runs on every path that creates a worktree today: a new thread from the UI, t3_thread_launch, delegate_task isolation, handoff and PR checkouts.

Our create still produces a real git worktree, so checkpoints and diffs keep working (requiresGit: true).

[Arzaroth]

I have a working Worktrunk-specific version of this on my fork, based on current main. Here is the comparison against main, and the branch is feature/wt-worktrees.

It adds an opt-in setting per machine, Settings → Worktrees → Worktree manager, with Git as the default and Worktrunk as the alternative. With Worktrunk selected, T3 still picks the branch name and start point and creates the branch. Then it runs wt switch <branch> --no-cd --format json, so wt decides the location and runs its hooks. Removal runs wt remove --foreground --no-delete-branch, so remove hooks run too. Nothing changes for anyone who stays on Git.

While building it, I ran into five problems that a generic create / remove contract would also have to solve.

Ownership after creation. Automatic cleanup, the rebuild of a missing worktree at turn start, and checkpoint rollback only trust worktrees inside T3's worktrees folder. A worktree that a provider created outside that folder needs its own record that T3 manages it. Without one, T3 never cleans it up or rebuilds it. I store the record in the repo's git config, keyed by path, as t3-worktree.<path>.manager = worktrunk. The record outlives the worktree, so a rebuild still works after removal, and it needs no database migration. The downside is that nothing ever deletes these records.

Rebuilding at an exact path. A thread keeps its worktreePath, so recreating the workspace means create has to accept a target path. wt allows this with a worktree-path config override, and its hooks still run. A generic contract would need a {path} input or something similar.

Removal by the creator. Whatever created a workspace should also remove it, even if the user has changed the setting since. So the ownership record should also name the provider.

Targets that aren't branches. wt switch turns any target into a new branch, so a checkout of a detached commit still has to use plain git. A generic provider would need to declare which targets it accepts.

Hook approval. Without a terminal, wt refuses repo hooks the user hasn't approved. I pass --yes, which runs the hooks in any repo's .config/wt.toml without review. The alternative is to fail and show wt's message, which tells the user to run wt config approvals add. I think maintainers should decide whether T3 auto-approves repo hooks.

The branch has tests for create, the ownership record, remove, and rebuilding at a given path. They use a stand-in for wt, so CI doesn't need Worktrunk installed. I also added a row to the existing table test for rebuilding a missing worktree at turn start. I ran the branch against the real wt binary on Linux, including a repo with an unapproved hook. I haven't tested Windows or macOS.

Which shape would maintainers accept, a focused Git / Worktrunk setting like this one or the generic workspace provider proposed here? I can reshape the branch either way, or send the Worktrunk setting first as a step toward providers.

[owpac]

+1, with Worktrunk as the main use case.

I want one global setting for each machine, not a script in each project. The "Worktree manager" setting on Arzaroth's branch matches this need.

My Worktrunk user config already prepares each worktree. It copies gitignored files (.env) with wt step copy-ignored, and it prunes merged worktrees. Today, T3 worktrees skip these hooks. They also go to ~/.t3/worktrees, and not to the path of my worktree-path template.

About hook approval: I prefer that T3 does not pass --yes. If a repo hook has no approval, show the wt message, and let the user run wt config approvals add. Repo hooks are arbitrary shell code, so the user must review them.