Skip to content

t1k:worktree

FieldValue
Modulet1k-base
Version5.15.36
Effortlow
Tools—

Keywords: branch, isolation, monorepo, parallel, pinning, rebase, workspace, worktree

/t1k:worktree
<subcommand> [args] — subcommands: create, session, sync, envsync, diff, status, list, remove, sweep, info, merge, cleanup

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.

CommandUsageDescription
createcreate [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).
removeremove <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.
sessionsession <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
syncsync [--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.
envsyncenvsync [--source <path>] [--exclude <name>] [--dry-run]Sync .env files across worktrees
diffdiff [--worktree <name>]Diff status per worktree vs base
statusstatusCombined overview of all worktrees
infoinfoRepo info, worktree location
listlistList all worktrees
mergemerge [--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 --orphanremove --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.
progressprogress <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.
adoptadopt <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 --stalesweep [--apply] --staleAlso 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.
watchwatch --once [--dry-run] | --scheduled | --install | --uninstall | --statusLow-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).
sweepsweep [--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.
cleanupcleanup [--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):

IntentLoad
Create a new worktree (or check if one exists first)references/workflow-create.md
Open or switch to an existing worktree sessionreferences/workflow-session.md
Rebase / merge worktrees onto latest base branchreferences/workflow-sync.md
Sync .env files across worktrees / check compose driftreferences/workflow-envsync.md
Inspect changes, ahead/behind, statusreferences/workflow-diff-status.md
Merge worktree branch back to base via PRreferences/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 commandreferences/reporting-protocol.md
Which root a worktree lands in, what the root census reports, what is quarantined (.t1k-trash) versus report-only, darwin/freebsd occupancydocs/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 -b in the main clone to do your work. checkout -b is blocked too: a new branch cannot collide, but creating it still moves the main worktree’s HEAD and 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 needs cherry-pick + git branch -f. hooks/shared-clone-worktree-guard.cjs blocks this; the audited override is T1K_SHARED_CLONE_CHECKOUT_APPROVED=1.

  • list first (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 with git -C <path> push -u origin <branch>. Without --no-track the branch tracks origin/main: a bare push targets main, and the upstream never goes [gone] for the cleanup sweep to find.

  • remove as 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 clean git status alone — 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 the claude process itself, so one can easily have its cwd inside a worktree you are removing. remove treats your own session’s whole process subtree — not just its direct ancestors — as “self”: it is reported as a warning, never a refusal, so remove on your own worktree does not require --force-in-use just 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-level git status hides uncommitted submodule edits and local-only submodule commits, and removal deletes .git/worktrees/<name>/modules/ with them: first run git -C <wt> submodule foreach --recursive 'git status --porcelain; git log --branches --not --remotes --oneline'. (2) A backup gate fails closed: never 2>/dev/null a git submodule status/foreach in a backup script — a failing command must block the removal, not pass as an empty backup. (3) Submodule gitfiles/core.worktree can be cross-wired between worktrees (e.g. a copied worktree folder points at ANOTHER worktree’s admin dir). Survey core.worktree in every .git/worktrees/*/modules/**/config first; 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: sync brings the base TO the lane by rebase, the default (skills/t1k-git/references/rebase-over-merge.md; --force-with-lease on the lane’s own branch, top-down --onto for any live sub-agent/child branch cut from it — merge is the fallback only when another worktree still has the branch checked out), merge lands 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 authorises remove on 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.
  • create does not pin the creating session — it produces a worktree for a new session or a pinned sub-agent (references/workflow-create.md).

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.

Runs in t1k-git-manager (or inline). Every command is a scripts/worktree.cjs subcommand; a lane session stays pinned to its own worktree.

StepAgent
Run scripts/worktree.cjs create / status / diff / sweept1k-git-manager