Repository navigation
Conversation
New worktrees can be cloned from a template (tracked files at a commit plus node_modules) captured after a worktree's setup script succeeds, keyed by the lockfiles. Off by default; a one-time clone probe per worktrees folder gates it, and any failure falls back to the stock checkout. Implemented by Claude Opus 5.5 via the Hermes ACP harness in T3 Code.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
A new worktree of a pnpm monorepo pays for a full checkout and then a full
vp iin its setup script. On t3code itself that is most of the time between "new thread in a worktree" and "agent can start", and it grows when several worktrees are launched at once.Change
An opt-in server setting,
enableWorktreeTemplates(default off; Settings → Worktrees → Advanced → Clone new worktrees from templates), same shape asenableWorktreeFastin upstream PR28727.cp --reflink=always(Linux: FICLONE) orcp -c(macOS: clonefile) on a scratch file. Unsupported filesystems and Windows never touch the template path and leave nothing behind.ThreadLaunchServiceforks a capture off the launch path: tracked files at the worktree's commit plusnode_modules, stored in.t3-templates/beside the worktrees, keyed by the hash of the lockfiles at that commit. Two templates kept per repository; older ones are evicted.createWorktreelooks up a template for the start ref's lockfile hash. On a hit it runsgit worktree add --no-checkout, clones the template with copy-on-writecp(batched, 4 at a time, one semaphore shared by every clone on the server), writes an index whose stat data matches the clones so the firstgit statusdoes not re-hash, checks out only what differs from the template's commit, and rewrites pnpm's.pnpm-workspace-state-v1.jsonto the new path sovp iin setup is a no-op check. Clone progress reports through the existing checkout progress stage.reset --hardcheckout. Turning the setting off deletes the repository's templates the next time it gets a worktree.Lines (
git diff --numstat, +/-):worktreeTemplates.ts+409,worktreeTemplates.test.ts+243,GitVcsDriverCore.ts+48/-1,WorktreesSettings.tsx+38/-1,ThreadLaunchService.ts+14,docs/user/project-settings.md+12,settingsSearch.ts+9,GitManager.ts+8/-6,GitVcsDriver.ts+4,contracts/settings.ts+3,GitWorkflowService.ts+2. Total +790/-8; +547 without the test. That is above the ~500 target. Split for upstream: (1) contracts setting +worktreeTemplates.ts+createWorktree/capture wiring + tests (server only, setting reachable only through settings.json); (2) Settings UI + search + user docs.Against Julius's bar (upstream PR
12631review)GitVcsDriverCore.createWorktreeplusscripts/setup-worktree.ts(vp i --frozen-lockfile -- --yes), not a separate referee.vp i: thesetup/wscolumn is the setup script (vp i) per worktree, stock vs opt-in.Measurements
Host: Linux 7.2.9 (CachyOS), 24 GB RAM plus zram, shared with other heavy jobs (2–7 GB available, ~12–14 GB swap in use). The kernel's global OOM killer fired during several N=4 attempts (order-3 allocations failing in the compositor, reclaimable slab ~4.8 GB); killed attempts were cleaned up and retried, and only complete runs with every gate green are counted. Of the 6 killed measured attempts, 5 were opt-in N=4 (btrfs 2, xfs 3) and 1 stock N=4 (btrfs +
26996): creating ~840k cloned inodes in ~15–25 s looks like it adds to that pressure. Not established as the cause, but a risk to check before recommending this on memory-tight hosts. Pin57cd05904d. Each root is an isolatedgit clone --sharedof t3code with its own pnpm store/cache/state on the same filesystem, warm store. Arms interleaved per round, N=3 rounds; "all ready" = wall time until every worktree is created and its setup script exited 0.Each bench run (one arm, one N) holds a host-wide
flockand waits for ≥1 GB available memory; order per round alternates (stock/opt-in, opt-in/stock). One warm-up stock run fills the store; one opt-in "first use" run has no template yet and captures it.(driver:
bench_template_clone.ts, run with node fromapps/server, callsmakeGitVcsDriverCore().createWorktreewith{ worktreeTemplates: true|false }then the setup script.)vp i) per ws stock → opt-in26996config26996configFirst use (no template yet) runs the stock path; capture then runs in the background (btrfs 8.7 s, xfs 10.1 s, btrfs+
269962.5 s).Reading: the template removes
vp ifrom setup everywhere, but it moves the cost into the clone. On btrfs that is a clear win (N=4 roughly halves). On XFS with a warm same-filesystem store, stock pnpm is already fast and cloning node_modules file by file (create/ws24 s at N=4) is slower than installing, so opt-in loses on XFS. Probe success alone is therefore not a reason to turn it on; a follow-up could compare a clone against the last stock install per root and stop using templates where they lose. With26996's virtual store, node_modules is mostly symlinks, the clone is cheap, and the two compose to the best numbers here.Relation to upstream PRs
28727and2699628727(git-worktree-fast on macOS) clones tracked files only, sovp istill runs after it. Both sit increateWorktree; they compose as: template hit → this path; elseenableWorktreeFaston macOS → git-worktree-fast; else stock. The setting is shaped the same way so both can live under Settings → Worktrees → Advanced.26996(shared pnpm virtual store) is not included here. It composes: with it the template's node_modules is mostly links and the clone cost drops (last two rows).Not checked
cp -cpath): no macOS host available; only the probe/flag selection is written for it.node_modules; tracked files come from the commit, but an agent writing intonode_modulesduring the ~3–10 s capture would land in the template. Not exercised.Checks run:
vp test run src/vcs/worktreeTemplates.test.ts(5 passed: clone with stat-clean index and resolving symlinks; probe off → stock and no templates; reuse for a newer commit and rebuild on lockfile change with eviction; fallback on clone failure; teardown removes the worktree and turning off removes templates),tsc --noEmitfor apps/server, packages/contracts and apps/web,vp linton the touched paths, pre-commit fmt/lint/knip.Implemented by Claude Opus 5.5 via the Hermes ACP harness in T3 Code.