t1k:worktree
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | low |
| Tools | — |
Keywords: branch, isolation, monorepo, parallel, pinning, rebase, workspace, worktree
How to invoke
Section titled “How to invoke”/t1k:worktree<subcommand> [args] — subcommands: create, session, sync, envsync, diff, status, list, remove, sweep, info, merge, cleanupGit Worktree Manager
Section titled “Git Worktree Manager”Manage git worktrees across the full lifecycle: create, session, sync, envsync, diff, status, remove, merge, cleanup.
All commands: bun $HOME/.claude/skills/t1k-worktree/scripts/worktree.cjs <command> [args] [--json] [--dry-run]
--help / -h / help (at any level, e.g. create --help) prints usage, exits 0 and changes nothing — probe with it instead of guessing a subcommand.
Commands
Section titled “Commands”| Command | Usage | Description |
|---|---|---|
create | create [project] <feature> --prefix <type> | Create worktree with branch. Anchored on the MAIN worktree: invoked from a secondary worktree it still lands in the ONE root: worktrees.root when configured (central: ~/.cache/t1k/worktrees/<repo>/<feature>), else <parent-of-clone>/<repo>-worktrees/<feature> (precedence --worktree-root > $WORKTREE_ROOT > worktrees.root > sibling; a raw git worktree add / herdr worktree create outside the root is BLOCKED by worktree-root-guard, override T1K_WORKTREE_ROOT_OVERRIDE=1 for the user’s explicit instruction only; every created worktree also gets its .t1k-progress record; one resolver scripts/lib/worktree-root.cjs shared with t1k-tree.cjs; legacy shared worktrees/, wt/, .claude/worktrees and scratchpad wt-* are migrate-only, never created into), and the created branch carries no upstream (first push -u sets it). The base (--base <branch> or auto-detected) is fetched first and the branch starts from origin/<base>, so a stale local base never wins; an explicit --base whose local branch holds unpushed commits is kept (BASE_LOCAL_AHEAD warning), and a failed fetch warns BASE_FETCH_FAILED instead of failing. Atomic per name: of two sessions creating the same worktree one wins, the other gets WORKTREE_EXISTS (owner session + liveness + next command) or WORKTREE_CREATING, never a raw git error or a half-made dir. Opt-in --copy-ignored Library,... clones named gitignored folders (a Unity Library) with a copy-on-write reflink; where the filesystem cannot reflink they are reported in ignoredSkipped, never fully copied (details and refusals: references/workflow-create.md). Submodules are initialized recursively by default (submodulesInitialized), so a tool that imports the tree (a Unity Editor) never opens empty submodule dirs; an unreachable one is a named warning plus submodulesFailed, never a failed create; --no-init-submodules skips it. Opt-in light profile (--profile light, default full; worktrees.profile): no submodule unless named (--init-submodules a,b), an optional cone-mode --sparse Dir,..., and an optional reflink seed --seed-from <worktree> --seed-dirs Library,... from a named sibling worktree (worktrees.light.seedFrom: main = the main worktree, or a worktree name; empty = no seed; applies to light only, --seed-from wins; an unresolvable source is a named warning, never a failed create) Never a Library/ by default; a light tree that holds an engine-project marker is warned about, and an engine tool needs a full worktree (see docs/scratch-and-worktree-hygiene.md § Light worktree profile). |
remove | remove <name-or-path> [--force] [--force-in-use] [--auto] | Remove worktree + branch. The argument resolves by rank: full path (symlink and trailing slash normalized), directory name, branch, then a bare fragment by prefix and contains; an argument with a separator never matches by fragment, so a stale path is WORKTREE_NOT_FOUND, not its sibling. On a pinned lane’s worktree this needs the user’s explicit cleanup instruction — see “Session pinning” below. Safe by default: aborts if the worktree has uncommitted changes, and never force-deletes an unmerged branch (it is kept). Also refuses (Linux and Windows) if a foreign live process has its cwd inside the worktree — git worktree remove has no concept of “in use”, and deleting one out from under a running session (another Claude Code session, a dev server) kills that process’s cwd with no warning. The caller’s OWN session subtree — including its own MCP server processes, which Claude Code spawns as children of claude itself, not of this script — is reported as a warning and never blocks removal; only a genuinely foreign pid does. --force discards uncommitted changes; --force-in-use overrides the foreign-process refusal — they are separate flags on purpose, so cleaning up your own dirty worktree never silently also evicts someone else’s live session. On Windows the in-use check is a rename probe: Windows will not rename a directory a process stands in, so a held tree is refused (the holder is not named). On darwin/freebsd the in-use check cannot run at all and removal proceeds with a warning that it was skipped, never a silent “nothing found”. Neither flag ever force-deletes a branch. --auto marks a NON-INTERACTIVE (sweep/automated) removal: it refuses (WORKTREE_HOLDS_WORK) any worktree that still holds work — uncommitted changes OR commits its upstream does not have — and refuses with NO override, because --force is a discard decision an interactive owner makes about their own worktree and a sweep has no owner (core#2745). It only ever refuses MORE than the interactive path; a refusal is a skip to report, not a retry. |
session | session <name-or-path> | Open a session in the worktree (runs T1K_SESSION_LAUNCHER when set; else, inside herdr, a linked herdr worktree workspace via herdr worktree open — never workspace create — plus a lazygit pane beside the agent, on by default (features.herdrLazygitPane; T1K_SKIP_HERDR_LAZYGIT=1 opts out; `lazygit: started |
sync | sync [--worktree <name>] | Bring worktrees to the base branch — rebase is the default for a throwaway worktree AND a pinned lane’s home branch; merge is only the fallback when another worktree has the branch checked out (references/workflow-sync.md). Does not move any session off its worktree. |
envsync | envsync [--source <path>] [--exclude <name>] [--dry-run] | Sync .env files across worktrees |
diff | diff [--worktree <name>] | Diff status per worktree vs base |
status | status | Combined overview of all worktrees |
info | info | Repo info, worktree location |
list | list | List all worktrees |
merge | merge [--target <branch>] [--delete] [--no-reset] | Merge a sub-agent’s topic branch to base via PR. Never the lane’s home branch, and the lane receives the base back by merge (references/workflow-merge.md). |
remove --orphan | remove --orphan <dir> [--dry-run] [--json] | Guarded quarantine of a directory under a worktree root that git does not know (phase 09). Re-derives the census class NOW and acts only on: empty dir (rmdir), no-git dir or loose file idle >= worktrees.idleDays (14) with no live process cwd (rename into <root>/.t1k-trash/<yymmdd-hhmm>-<name>, purged after trashRetentionDays 7), idle node_modules. Anything with a .git, every archive dir and anything outside a known worktree root is REPORT ONLY (exit 3). --dry-run prints class, action and the recovery command. Exit: 0 done or dry-run, 1 failed or busy, 2 usage, 3 refused. Restore: the mv line in telemetry/orphan-recovery.log. worktrees.reapMode: report turns the automatic pass off. |
progress | progress <set|done|show> [path] [--task <text>] [--steps d/t] [--session <id>] [--json]; progress backfill [path|--all] [--dry-run] [--json] [--limit N] (exit 0 done, 1 failed, 2 usage) | Mandatory per-worktree tracking. .t1k-progress (task, steps, session, updatedAt, state in-progress|done) lives in the worktree’s git dir, so it never dirties the tree. Written at creation; update it as you go and run progress done when merged: done + merged branch => the sweep removes the worktree and local branch. A worktree with no record (raw git worktree add, older tooling) is repaired by progress backfill and by the stale pass (in-progress, updatedAt = real activity, never touching a live owner or session; needs the Linux cwd probe, so on Windows/macOS it refuses with ‘process cwd scan unavailable’). The board shows it (untracked when missing); the Stop nudge reminds an owner session. |
adopt | adopt <wt> [--as-finisher [--agent <id>]] [--session <id>] [--json] [--dry-run] (exit 0 adopted, 1 refused with the code in the JSON, 2 usage) | Take over a worktree whose owner session is gone (the SessionStart [t1k:worktree-owner-gone] line names it with the exact command). Metadata only: re-stamps branch.<b>.t1k-owner-* (previous owner kept as t1k-adopted-from), records adoptedBy in .t1k-progress, clears the owner-gone marker; never touches HEAD, the index or files. Per-worktree lock, so of two concurrent adopters one wins. Refusals have NO override flag: ADOPT_MAIN, ADOPT_NOT_FOUND, ADOPT_NO_BRANCH, ADOPT_LIVE_PROCESS, ADOPT_LIVE_SESSION, ADOPT_OWNER_LIVE, ADOPT_LOCKED, ADOPT_UNKNOWN (a probe could not answer: cannot see is not nobody there). --as-finisher (the SessionStart [t1k:worktree-finisher-dispatch] frame runs it) also needs a usable recorded task, an unused attempt and a free slot under the machine-wide cap: ADOPT_NO_TASK, ADOPT_ATTEMPTS, ADOPT_CAP; it returns {adopted, attempt, cap:{active,max}}. An adopted worktree with a live adopter is skipped by the idle abandoned sweep. |
sweep --stale | sweep [--apply] --stale | Also runs the stale-work reaper (worktree-reap-stale.cjs): done+merged removal, abandoned work pushed to wip/<branch> then removed, idle Unity Library/ dropped. Same code the auto-prune runs; gated by worktrees.idleDays / reapMode. |
watch | watch --once [--dry-run] | --scheduled | --install | --uninstall | --status | Low-impact background watcher (nice/ionice, skips under IO pressure, lockfile): applies the reaper to every repo’s worktrees and deletes/slims idle main Unity repos (classes A/B/C in docs/scratch-and-worktree-hygiene.md). --install adds a systemd --user timer (Linux). |
sweep | sweep [--apply] [--no-fetch] [--json] | PR-keyed orphan sweep. Lists every linked worktree whose branch’s PR is MERGED or CLOSED (via gh pr list --repo <origin's owner/repo> --head), and why each other one is kept. Dry-run by default; --apply removes the worktree, local branch and remote branch. --no-fetch skips git fetch --prune origin; a lane judged not-landed against unfetched refs is listed as unresolved, never dropped. Squash-safe and never touches the main worktree, a dirty tree, a branch with no PR, an open PR, a home branch, or a tree whose occupancy probe cannot answer (non-Linux) — same policy as t1k-pr-watch.cjs --cleanup-worktree (scripts/lib/pr-worktree-cleanup.cjs). Runs automatically with --apply semantics from hooks/worktree-auto-prune.cjs (SessionStart + Stop, throttled) while features.autoPruneMergedWorktrees is on (default) — over the session’s repo AND every clone a worktree was ever created in on this machine (worktree create AND any raw git worktree add seen by the worktree-owner-identity PostToolUse hook record it in session-state/worktree-clones.json, detached and submodule worktrees included) plus gitCleanup.clones, deduped by git common dir. It also deletes a local branch with no worktree and no PR once its tip is an ancestor of origin/<default> and it has been idle 24h (tip logged for recovery), and rmdirs the empty directory a removal leaves behind (never recursive). Kill switch T1K_SKIP_WORKTREE_PRUNE=1. |
cleanup | cleanup [--min-idle-min <n>] [--finished-agent <id>]... | Fleet-wide reclamation sweep — a different entry point, not a worktree.cjs subcommand. Answers “which worktrees and branches is nobody standing in any more” across the whole repo, including branches that have no worktree at all. Facts come from bun .claude/scripts/worktree-cleanup-facts.cjs [--json] (read-only — it has no write path, so the sweep is preview-first by construction); the policy, the five REMOVABLE conditions and the liveness trap are owned by /t1k:git cleanup — load skills/t1k-git/references/worktree-cleanup.md as the SSOT rather than re-deriving them here. Sibling kit clones, where no session starts, join the sweep with --clone <path> (repeatable) or config gitCleanup.clones; the script runs git fetch --prune origin in each clone first, and --no-fetch skips it. Removal itself is still done by remove (per worktree) and git branch -D (per merged branch), so every safety gate on those rows still applies. |
Decision tree — which reference do I load?
Section titled “Decision tree — which reference do I load?”Load only the reference you need (each is self-contained):
| Intent | Load |
|---|---|
| Create a new worktree (or check if one exists first) | references/workflow-create.md |
| Open or switch to an existing worktree session | references/workflow-session.md |
| Rebase / merge worktrees onto latest base branch | references/workflow-sync.md |
| Sync .env files across worktrees / check compose drift | references/workflow-envsync.md |
| Inspect changes, ahead/behind, status | references/workflow-diff-status.md |
| Merge worktree branch back to base via PR | references/workflow-merge.md |
| Sweep the repo for finished worktrees/branches to reclaim (incl. branches with no worktree) | skills/t1k-git/references/worktree-cleanup.md (SSOT, shared with /t1k:git cleanup) |
| Before/after reporting format for any command | references/reporting-protocol.md |
Which root a worktree lands in, what the root census reports, what is quarantined (.t1k-trash) versus report-only, darwin/freebsd occupancy | docs/scratch-and-worktree-hygiene.md (SSOT) |
Shared clones — when another session is in the same repo
Section titled “Shared clones — when another session is in the same repo”A kit clone on a developer machine is shared infrastructure: several Claude sessions routinely work
in one theonekit-* clone at once, and every session standing in the MAIN worktree shares that
clone’s one HEAD. A linked worktree is not affected — it has its own HEAD at
.git/worktrees/<name>/HEAD, which is exactly why taking one is the remedy.
-
Never
git checkout/switch/branch -f/checkout -bin the main clone to do your work.checkout -bis blocked too: a new branch cannot collide, but creating it still moves the main worktree’sHEADand leaves a local branch nothing ever deletes. It yanks whichever session owns the other worktrees out from under itself — its next commit lands on your branch, and recovery needscherry-pick+git branch -f.hooks/shared-clone-worktree-guard.cjsblocks this; the audited override isT1K_SHARED_CLONE_CHECKOUT_APPROVED=1. -
listfirst (already MANDATORY below) tells you which branches other sessions hold — before git refuses you, not after. -
A branch already checked out elsewhere cannot be claimed twice, and that worktree belongs to another session, so do not work inside it. Take a detached worktree and publish explicitly:
Terminal window git -C <clone> worktree add --detach <path> origin/<branch>git -C <path> push origin HEAD:<branch> -
Read without moving
HEAD:git -C <clone> show <ref>:<path>,log,diff. -
Create the branch with
--no-track(git -C <clone> worktree add --no-track -b <branch> <path> origin/main) and publish withgit -C <path> push -u origin <branch>. Without--no-trackthe branch tracksorigin/main: a barepushtargets main, and the upstream never goes[gone]for the cleanup sweep to find. -
removeas soon as your work is pushed. A stale worktree keeps its branch claimed against every other session. Once the PR merges, the session that created the worktree reaps it (skills/t1k-git/references/owner-reap-on-merge.md). -
Never remove a worktree ANOTHER session might be standing in.
remove(Linux only) already refuses when a foreign live process has its cwd inside the target and names the offending pid(s) — but the check cannot run on every platform, and it cannot see a session that is between tool calls in a way that momentarily changed its shell’s cwd elsewhere. Before removing a worktree you did not just finish working in yourself, confirm with the user or check for recent activity rather than trusting a cleangit statusalone — a worktree can be fully clean and merged and its removal still be destructive to whatever live session is standing in it (theonekit-core#2009). -
Your OWN session’s MCP server processes never block your own
remove. Claude Code spawns MCP servers as children of theclaudeprocess itself, so one can easily have its cwd inside a worktree you are removing.removetreats your own session’s whole process subtree — not just its direct ancestors — as “self”: it is reported as a warning, never a refusal, soremoveon your own worktree does not require--force-in-usejust because one of your own MCP servers happens to be sitting in it. -
Gotcha: a repo with submodules — survey before any
git worktree remove(plain or--force). (1) Parent-levelgit statushides uncommitted submodule edits and local-only submodule commits, and removal deletes.git/worktrees/<name>/modules/with them: first rungit -C <wt> submodule foreach --recursive 'git status --porcelain; git log --branches --not --remotes --oneline'. (2) A backup gate fails closed: never2>/dev/nullagit submodule status/foreachin a backup script — a failing command must block the removal, not pass as an empty backup. (3) Submodule gitfiles/core.worktreecan be cross-wired between worktrees (e.g. a copied worktree folder points at ANOTHER worktree’s admin dir). Surveycore.worktreein every.git/worktrees/*/modules/**/configfirst; removing the target breaks every worktree wired to it (fatal: cannot chdir to .../<other>/...). Remove wired-to trees last, or re-point first.
Session pinning — a lane session stays on its worktree
Section titled “Session pinning — a lane session stays on its worktree”rules/worktree-session-pinning.md is the SSOT for this; the points a t1k-worktree command needs:
- A session that OPENS a worktree is PINNED to it for its whole life, on that worktree’s home
branch — like a main-clone session stays on the main branch. Nothing in this skill moves it off:
syncbrings the base TO the lane by rebase, the default (skills/t1k-git/references/rebase-over-merge.md;--force-with-leaseon the lane’s own branch, top-down--ontofor any live sub-agent/child branch cut from it — merge is the fallback only when another worktree still has the branch checked out),mergelands a sub-agent’s topic branch, and neither relocates the session. The session leaves only on an explicit user cleanup instruction — which is also the only thing that authorisesremoveon a live or unmerged pinned lane (a MERGED one is reaped by the pruner or the merging agent:rules/worktree-session-pinning.md). - Several pinned lanes run in parallel precisely so one does not wait on the main-branch session. Work is carried out by sub-agents, each with its own worktree/branch, merging into the base (CI/CD ships it) or into the lane’s home branch.
createdoes not pin the creating session — it produces a worktree for a new session or a pinned sub-agent (references/workflow-create.md).
Operational notes
Section titled “Operational notes”Intent routing (MANDATORY): Always run list --json before asking the user anything — a matching worktree name means jump straight to the session workflow.
Safety: Rebase auto-aborts on conflict to prevent data loss.
GitHub quota: sweep runs a gh pr list per worktree; on a rate-limit 403 stop and report, never loop (skills/t1k-git/references/github-api-limits.md).
Reporting: Every command MUST show before/after state. End with a summary line. Full format: references/reporting-protocol.md.
Executed by
Section titled “Executed by”Runs in t1k-git-manager (or inline). Every command is a scripts/worktree.cjs subcommand; a lane session stays pinned to its own worktree.
| Step | Agent |
|---|---|
Run scripts/worktree.cjs create / status / diff / sweep | t1k-git-manager |