Manage Git worktrees for isolated parallel development. Use when creating, listing, switching, or cleaning up git worktrees, or when needing isolated branches for concurrent reviews or feature work.
From compound-engineeringnpx claudepluginhub iliaal/compound-engineering-plugin --plugin compound-engineeringThis skill uses the workspace's default tool permissions.
references/troubleshooting.mdreferences/workflow-examples.mdscripts/worktree-manager.shSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Never call git worktree add directly -- always use the worktree-manager.sh script.
The script handles critical setup that raw git commands don't:
.env, .env.local, .env.test, etc. from main repo.worktrees is in .gitignorepackage.json → npm install, composer.json → composer install, pyproject.toml → pip install -e ., go.mod → go mod downloadBefore creating a worktree, verify the worktree directory is gitignored:
# Verify .worktrees is ignored (should output ".worktrees")
git check-ignore .worktrees || echo "WARNING: .worktrees not in .gitignore"
If not ignored, add it to .gitignore before proceeding. The manager script handles this, but verify when troubleshooting.
After creating a worktree, run the project's test suite to establish a clean baseline. Pre-existing failures in the worktree should be caught before starting new work -- not discovered mid-implementation.
# CORRECT - Always use the script
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-name
# WRONG - Never do this directly
git worktree add .worktrees/feature-name -b feature-name main
| Command | Description | Example |
|---|---|---|
create <branch> [from] | Create worktree + branch (default: from main) | ...worktree-manager.sh create feature-login |
list / ls | List all worktrees with status | ...worktree-manager.sh list |
switch <name> / go | Switch to existing worktree | ...worktree-manager.sh switch feature-login |
copy-env <name> | Copy .env files to existing worktree | ...worktree-manager.sh copy-env feature-login |
cleanup / clean | Interactively remove inactive worktrees | ...worktree-manager.sh cleanup |
After cleanup, run git worktree prune to remove any orphaned worktree metadata from manually deleted directories.
All commands use: bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh <command>
Before creating worktrees, detect the execution context:
git rev-parse --show-toplevel against git worktree list. If the current directory is already a linked worktree, skip creation -- work directly in the existing worktree.$CODEX_SANDBOX is set or the repo is at a non-standard path (e.g., /tmp/, /workspace/), worktrees may not be supported. Fall back to regular branch switching.git rev-parse --is-bare-repository returns true, worktrees are the only way to have a working directory. Adjust paths accordingly.Adapt the workflow to the detected context rather than failing with a generic error.
/workflows:review/workflows:workAlways offer choice:
git worktree list shows the new entry.worktrees directory confirmed in .gitignore