Skip to content
Skills Library
Programming · Automation

worktree

/worktree

Create, inspect, and safely remove git worktrees for repos under the workspace root (WORKSPACE_ROOT, default ~/git), enforcing the worktree-first policy and the no-stale-worktree guarantee. Use whenever you are about to make a change that will be committed, when the user says "make a worktree", "clean up worktrees", "list worktrees", "any stale worktrees?", or when you finish a task that used one and need to tear it down. Also use before ending a session in which you created a worktree.

Repository
dotclaude ↗
Licence
MIT
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/worktree.sh

What it does and when to use it

Create, inspect, and safely remove git worktrees for repos under the workspace root (WORKSPACE_ROOT, default ~/git), enforcing the worktree-first policy and the no-stale-worktree guarantee. Use whenever you are about to make a change that will be committed, when the user says "make a worktree", "clean up worktrees", "list worktrees", "any stale worktrees?", or when you finish a task that used one and need to tear it down. Also use before ending a session in which you created a worktree.

Triggers from the description

make a worktreeclean up worktreeslist worktreesany stale worktrees?
Original author description

Create, inspect, and safely remove git worktrees for repos under the workspace root (WORKSPACE_ROOT, default ~/git), enforcing the worktree-first policy and the no-stale-worktree guarantee. Use whenever you are about to make a change that will be committed, when the user says "make a worktree", "clean up worktrees", "list worktrees", "any stale worktrees?", or when you finish a task that used one and need to tear it down. Also use before ending a session in which you created a worktree.

How it works

  1. When to use
  2. Prerequisites
  3. Configuration
  4. Commands
  5. CodeGraph (optional)
  6. Reporting obligation
  7. Notes
Original SKILL.md headings · 97 lines, 772 words
SKILL.md preview
---
name: worktree
description: >
  Create, inspect, and safely remove git worktrees for repos under the workspace root
  (WORKSPACE_ROOT, default ~/git), enforcing the worktree-first policy and the no-stale-worktree
  guarantee. Use whenever you are about to make a change that will be committed, when the user says
  "make a worktree", "clean up worktrees", "list worktrees", "any stale worktrees?", or when you
  finish a task that used one and need to tear it down. Also use before ending a session in which
  you created a worktree.
---

# Worktree

Worktrees are the default vehicle for changes in any repo under the workspace root, not an
opt-in. The policy in short:

- Every change headed for a commit happens in its own worktree at
  `$WORKTREES_DIR/<repo>--<slug>/`, cut from the repo's up-to-date integration branch.
- Remove a worktree once its PR is merged, the task is abandoned, or the session ends with no
  follow-up pending in it.
- Never remove a worktree that holds uncommitted or unpushed work, and never `rm -rf` one.
- Never remove a worktree you did not create in this session without asking.

This skill is the supported way to act on it.

## When to use

- **Before any edit headed for a commit** in any repo under the workspace root. Create the
  worktree first, then work inside it.
- **When a task finishes** (PR merged, task abandoned, session ending): remove the worktree.
- **When asked about strays**: list them and report, do not mass-delete.

Skip it for read-only work and for files that are not in a repo.

## Prerequisites

Run the `ensure-repo-sync` skill for the repo before creating a worktree. The base branch must be
current against the **remote**. A clone with a narrow fetch refspec can hold a stale
`origin/<branch>`; `git ls-remote --heads origin <branch>` shows what the remote really has.

## Configuration

- `WORKSPACE_ROOT`: folder that holds the repos, default `~/git`. A `<repo>` argument is a folder
  name under it or an absolute path.
- `WORKTREES_DIR`: where worktrees go, default `$WORKSPACE_ROOT/worktrees`.
- Integration branch per repo: `git config harness.integrationBranch <branch>` in that repo, else
  `develop` when origin has it, else the remote default branch (`origin/HEAD`), else `main`.

## Commands

All commands go through `worktree.sh`, bundled with this skill.

```bash
# create: path, base branch, and naming are enforced for you
"${CLAUDE_PLUGIN_ROOT}/skills/worktree/scripts/worktree.sh" new <repo> <branch>
#   e.g. worktree.sh new api feature/products-get-pagination
#   -> $WORKTREES_DIR/api--products-get-pagination on feature/products-get-pagination,
#      branched from the repo's integration branch
#   hotfix/* branches are the exception: they branch from current origin/main, or from the
#   remote default branch when origin has no main.

# inspect: every worktree under $WORKTREES_DIR with dirty / unpushed / age
"${CLAUDE_PLUGIN_ROOT}/skills/worktree/scripts/worktree.sh" list

# remove: refuses when there is uncommitted or unpushed work
"${CLAUDE_PLUGIN_ROOT}/skills/worktree/scripts/worktree.sh" remove <repo>--<slug>
"${CLAUDE_PLUGIN_ROOT}/skills/worktree/scripts/worktree.sh" remove <repo>--<slug> --keep-branch   # explicit no-op flag, branch is always kept
```

`new` refuses to clobber an existing path and requires a branch name with a prefix and literal
`/` separator. Any prefix is accepted; `hotfix/*` still branches from `origin/main`.

`remove` exits non-zero and changes nothing when the worktree has a dirty tree or commits that
are not on the remote. **Do not work around that refusal.** Push the work, or report it to the
developer and stop. It also refuses anything that is not a bare worktree name under
`$WORKTREES_DIR`. A branch with no remote counterpart passes only when `gh` confirms its HEAD is
the head of a merged PR.

## CodeGraph (optional)

When `codegraph` is on PATH and the primary checkout has a `.codegraph/codegraph.db` index, a
worktree of that repo gets its own index, because an index only describes the tree it sits in.
`new` copies the primary index and runs `codegraph sync`, which takes seconds; a rebuild from
scratch would take minutes. `remove` deletes it, but only once the dirty and unpushed checks have
passed, so a refused removal never costs you the index.

- Query it with `projectPath` (or `-p`) set to the **worktree** path. Pointing at the primary
  checkout while working in a worktree answers from the wrong branch.
- Provisioning is best effort. It is skipped silently when the repo has no index or `codegraph` is
  missing, and any failure warns and leaves the worktree usable.
- `new` also adds `.codegraph/` to the repo's `.git/info/exclude` when the repo does not already
  gitignore it, so the index can never be the untracked file that blocks `remove`.

## Reporting obligation

If a worktree you created has to outlive the session, name it in your final response: which one,
why it survives, and what has to happen before it can go. A worktree you did not create is not
yours to delete. Report it, with what `list` says about its state, and let the developer decide.

## Notes

- Removing a worktree never deletes its branch. Leave the branch alone. Never delete `main`,
  `master`, `develop` or the repo's integration branch.
- The script is POSIX/bash-3 safe so it runs on macOS and Linux.
- Do not run these commands against a worktree from inside a sandbox that mounts the workspace at
  a different path. Git records absolute paths, so the registry looks "prunable" when it is fine.
Files in this package (2)
  • SKILL.md 5 KB
  • scripts/worktree.sh 14 KB

Versions

RepositoryScoreLicence
This page · PranamRDoshi/dotclaude100MIT
vanducng/skills100MIT
tony/skills100MIT
zts212653/clowder-ai100MIT
duronext/jig100MIT
guangshinhaha/shinstack100MIT
kronael/tools100Unlicense
rhesis-ai/rhesis100MIT
zipstack/unstract100AGPL-3.0

Database snapshot: 13.11.2026 · package version eec3ecfab47d (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:finish
    Use when completing work in a worktree. Handles PR creation or direct merge, worktree removal, and branch cleanup. Invoke with "/worktrees:finish" or when user mentions "finish worktree", "clean up worktree", "merge worktree", "done with worktree", or "complete worktree work".
  • 100worktree-sweep
    Find and remove stale git worktrees across one or many repositories. Classifies each extra worktree as clean / dirty / locked, measures reclaimable space, then removes the safe ones after approval. TRIGGER when the user wants to clean up, prune, or audit git worktrees ("remove…
  • 100remove-worktree
    Use when user wants to safely remove an autonomy worktree while preserving the branch
  • 100git-worktree-finish
    Use when the user asks to finish, land, or merge back a feature worktree created with /git-worktree.
  • 100zap
    Find stale git worktrees (merged, empty, gone, missing) and remove them safely with the zap CLI. Use when the user asks to clean up, list or free disk space from git worktrees, including ones left behind by coding agents in .claude/worktrees, ~/.codex/worktrees and similar folders.
  • 100wt
    This skill should be used when the user asks about 'wt', 'worktree', 'worktrees', 'wt create', 'wt checkout', 'wt list', 'wt remove', 'wt pr', 'wt mr', or mentions managing git worktrees with wt. Also use when the user asks how wt works, how to use wt commands, or how to…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.