worktree
/worktree
Starts, checks and cleans up per-session git worktrees under the rule one session = one worktree = one branch. Use at the start of any task that will edit files, whenever you find yourself in the main checkout, when the session-start notice warns about memory, divergence or a .env, when asked about session or worktree status, stale worktrees or orphaned dev servers, and before deleting any branch or worktree.
- Author
- antoniarco ↗
- Repository
- agentic-coding-swarm-protocol ↗
- Licence
- MIT
- Last repository change
- 29.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Starts, checks and cleans up per-session git worktrees under the rule one session = one worktree = one branch. Use at the start of any task that will edit files, whenever you find yourself in the main checkout, when the session-start notice warns about memory, divergence or a .env, when asked about session or worktree status, stale worktrees or orphaned dev servers, and before deleting any branch or worktree.
Arguments
/worktree [start <task> | status | clean]
Original author description
Starts, checks and cleans up per-session git worktrees under the rule one session = one worktree = one branch. Use at the start of any task that will edit files, whenever you find yourself in the main checkout, when the session-start notice warns about memory, divergence or a .env, when asked about session or worktree status, stale worktrees or orphaned dev servers, and before deleting any branch or worktree.
How it works
- The gates
- Where am I?
- start
- status
- clean
- Without the reference tooling
- Red flags
- Report
SKILL.md preview
---
name: worktree
description: Starts, checks and cleans up per-session git worktrees under the rule one session = one worktree = one branch. Use at the start of any task that will edit files, whenever you find yourself in the main checkout, when the session-start notice warns about memory, divergence or a .env, when asked about session or worktree status, stale worktrees or orphaned dev servers, and before deleting any branch or worktree.
argument-hint: "[start <task> | status | clean]"
allowed-tools: Bash(git rev-parse *) Bash(git branch *) Bash(git status *) Bash(git worktree list *) Bash(git check-ignore *) Bash(pnpm wt:status *) Bash(pnpm wt:gc --dry-run) Bash(pnpm wt:reap --dry-run) Bash(node scripts/dev/leases.ts *) Bash(node scripts/dev/overlap.ts *) Bash(uptime)
---
# worktree
Say at the start: "Using worktree (<start|status|clean>)."
**Resolve the commands first.** Read `swarm.json` at the repo root: `{status}`, `{commit}`, `{verifyQuick}` and
`{leases}` and `{overlap}` are its `commands.*` keys; fall back to `pnpm wt:status`, `pnpm wt:commit`, `pnpm verify --quick` and
`node scripts/dev/leases.ts` / `node scripts/dev/overlap.ts` only when the file or a key is missing. Contract: [INTEGRATION.md](../../INTEGRATION.md). The cleanup commands (`pnpm wt:gc`,
`pnpm wt:reap`, `pnpm wt:archive`) belong to the reference tooling of level 2; if the repo does not have them, use
the plain-git path at the end.
## The gates
1. **Nobody edits or commits in the main checkout.** Only `land` moves it.
2. **Nothing is deleted without a published archive.** A worktree or branch with unintegrated work is removed only
by `wt:archive`, which publishes an `archive/<date>-<branch>` tag and checks it on the remote first. `wt:gc`
removes only worktrees that are integrated, clean and have no live session.
3. **A process belongs to the worktree that contains its cwd.** Never stop a process in another live worktree, and
never a `claude` process.
Why: a shared working tree produced commits with other sessions' work, overwritten files and lost work; "cleaning
up" deleted unintegrated branches; orphaned dev servers drove swap to 99 % (chapters 01 and 11).
## Where am I?
```bash
git rev-parse --show-toplevel
git rev-parse --git-dir --git-common-dir # the same path twice → you are in the main checkout
git branch --show-current # empty → detached HEAD
```
## start
1. In the main checkout or on `main`: do not edit. Enter a worktree with the `EnterWorktree` tool, or ask the human
to start the session with `claude -w <task>` (kebab-case task name; branch `worktree-<task>`).
2. Read the session-start notice (the `SessionStart` hook prints it) and act on each warning:
| Warning | Do |
| --- | --- |
| memory pressure warn or critical, swap high | do not start another verify; stop dev servers you no longer need; tell the human |
| `.env` in the worktree | tell the human; real spend happens only from the main checkout and `land` will refuse |
| divergence from the remote | tell the human; do not pull or merge (single-publisher rule) |
| last audit older than 14 days | mention it once; the `audit-repo` skill runs it |
| too many dev servers or one above 3 GB | stop yours when you are done looking at it |
| `leases ·` exclusive zones held by others, other sessions' leases | plan around them; if the task needs a held zone, tell the human now, not after half the work |
| other active sessions and their areas (`overlap ·`) | plan around them; if the task needs one of those files, say so before editing |
| `✗` conflict predicted, or `✗`/`⚠` behind on files you touch | stop and tell the human which branch to land first; rebase now if you are the one behind |
3. **Declare.** Once you have a plan, `{leases} claim "<glob>" … --intent "<one line>"`. A `✗` means an exclusive
zone is held by a live session: do the parts that do not need it, or ask the human. A refused edit later (`swarm
lease: … held by …`) means the same; never work around it (another path, a copy, a shell write).
4. **Baseline.** Run `{verifyQuick}` before your first edit. Red already → report what was red before you started;
do not fix unrelated failures silently.
5. Use the ports in `.claude/worktree.env` for dev servers, so parallel sessions do not collide.
6. Commit with `{commit} "<message>"`. The `Stop` hook keeps at most one rolling `wip:` commit so nothing is lost;
`{commit}` absorbs it.
7. **Overlap notices.** After an edit, a `swarm overlap` reminder may appear: a new pair of branches touching the same
files, or a predicted conflict. Read what the other branch changes (`git diff main...<branch> -- <file>`) before
continuing; a clean textual merge can still be a semantic clash. Without the hook, run `{overlap}` every few commits.
8. Finish with the `land` skill; it releases your leases. The worktree stays after a land; the next `land` or session start collects it.
## status
`{status}` (add `--all` for remote branches with unintegrated work). Report per worktree: branch, ahead/behind,
dirty, wip, integrated, age, processes and memory. Then `{overlap} --all`: every pair of active branches that touch
the same files, with predicted conflicts first. Flag branches older than three days without a land: long-lived
branches are where semantic conflicts grow.
## clean
Only when the human asks, or when the session notice says integrated worktrees or orphaned processes are piling up.
1. Dry run first, always: `pnpm wt:gc --dry-run` and `pnpm wt:reap --dry-run`. Show the lists.
2. Then `pnpm wt:gc` and `pnpm wt:reap`.
3. Unintegrated work the human wants gone: `pnpm wt:archive <branch>`, only on their explicit request. It refuses
if the branch diverged, is dirty or is locked; do not work around a refusal, report it.
## Without the reference tooling
Plain git keeps the same rules:
```bash
git check-ignore -q .claude/worktrees || echo "add .claude/worktrees/ to .gitignore first"
git worktree add .claude/worktrees/<task> -b worktree-<task> main
```
Install dependencies inside the new worktree; it has no `node_modules` and no `.env`, and that is deliberate.
Remove a worktree only after its branch is merged (`git branch --merged main`), with `git worktree remove <path>`;
never `--force` on a dirty one.
## Red flags
| Thought | Reality |
| --- | --- |
| "It is a one-line fix; I will do it in the main checkout." | Another session's land will find a dirty tree and fail. Use a worktree. |
| "These old worktrees are clutter; delete them." | Some hold unintegrated work. `gc` for integrated ones, `archive` for the rest, on request. |
| "That dev server is eating memory; kill it." | Check its cwd. If it is in another live worktree, it is not yours. |
| "I will `git stash` to switch context." | The stash stack is shared by every worktree; another session can pop your entry. Commit instead. |
| "My branch is a week old but still fine." | Rebase now and land in small steps; long branches breed conflicts git cannot see. |
| "The baseline is red, I will fix it while I am here." | Report it. Unrelated fixes belong in their own worktree and branch. |
## Report
```
worktree: <path> · branch <name> · ahead 3 / behind 0 · clean
baseline: <verifyQuick command> → ✓ | ✗ (pre-existing: <step>)
warnings: <none | what the session notice said and what you did>
```
Depth: [chapter 01](../../manual/01-sessions-and-worktrees.md) (lifecycle, hygiene, single workstation).
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · antoniarco/agentic-coding-swarm-protocol | 100 | MIT |
| vanducng/skills | 100 | MIT |
| tony/skills | 100 | MIT |
| zts212653/clowder-ai | 100 | MIT |
| duronext/jig | 100 | MIT |
| guangshinhaha/shinstack | 100 | MIT |
| PranamRDoshi/dotclaude | 100 | MIT |
| kronael/tools | 100 | Unlicense |
| rhesis-ai/rhesis | 100 | MIT |
Database snapshot: 13.11.2026 · package version 110e2e597387 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90worktrees
Use when creating, entering, checking, repairing or removing a git worktree, or when a worktree lacks dependencies, git hooks, skills or ignored files such as .env that the main checkout has. - 100marcgit
Use when the user wants to manage git worktrees with marcgit (a.k.a. `mg`) — creating a worktree for a feature/branch/PR, switching to trunk, listing or pruning worktrees, or moving in-progress edits into a fresh worktree. Triggers on phrases like "marcgit", "mg work", "create a… - 93dev-server
Manage Next.js dev servers across worktrees, and the worktrees themselves — create one (`wt new`), find finished ones (`wt stale`), remove them (`wt rm`). Start, stop, and read logs from dev servers. Agents can access logs from any running session, regardless of who started it.… - 100remove-worktree
Cleans up a git worktree after its branch has been merged. Runs git worktree remove, deletes the local branch and prunes remote refs. It stops without changing anything when the worktree has uncommitted changes, unpushed commits or a PR that is not merged. Use it when a feature… - 100worktree-main-sync
Create and sync git worktrees from the latest remote main branch. Use when asked to create a new worktree, branch from remote main, fix a worktree that is behind origin/main, or verify worktree and main parity before starting work. - 100unworktree
Use when the user wants to undo, absorb, collapse, or reverse a git worktree — "undo worktree", "absorb worktree", "move worktree branch back to main repo", "remove worktree and checkout in main", "get rid of this worktree", or finish work in a ~/worktrees.nosync worktree and…