Overview

Worktree kit provides a script to manage git worktrees under .worktrees (create, list, switch, cleanup) and to copy .env files into a worktree. Use it to run parallel feature work, isolated reviews, and clean, focused workspaces. Safety checks guard against symlinks and unintended deletions.

How This Skill Works

Run the manager script from the repo root: bash ${CLAUDE_PLUGIN_ROOT}/skills/worktree-kit/scripts/worktree.sh <command> [args]. Supported commands are create, list, switch, cleanup, and copy-env. Create and switch do not change the current branch; cleanup removes the worktree directory only if the worktree is clean and does not delete branches. Copy-env copies .env* files with no overwrite and skips symlinks; worktrees live under .worktrees/ and any path component that is a symlink is refused. Fetch from origin is optional and only performed if the base looks like a branch.

When to Use It

• You want to develop a new feature in a separate worktree without touching your main checkout.
• You need an isolated review environment to test changes without switching branches.
• You want to keep your workspace tidy by cleaning up unused worktrees after review.
• You need to bring environment variables into a worktree by copying .env files.
• A user mentions worktrees and you need a quick setup to align with that request.

Quick Start

1. Step 1: Run the manager script: bash ${CLAUDE_PLUGIN_ROOT}/skills/worktree-kit/scripts/worktree.sh <command> [args]
2. Step 2: Create a new worktree, e.g., create feature-auth main
3. Step 3: (Optional) Copy environment files: copy-env feature-auth

Best Practices

• Name each worktree descriptively (e.g., feature-login) and choose a sensible base.
• Run from the repository root and use the provided script path.
• Before cleanup, ensure the worktree is clean; cleanup does not force-remove or delete branches.
• When copying env files, allow no overwrites and skip symlinks.
• Validate that no path components in the worktree are symlinks to avoid safety issues.

Example Use Cases

• Create a worktree named feature-auth from main to implement and test a new auth feature in isolation.
• List all active worktrees to monitor parallel workstreams.
• Switch to a dedicated worktree to review changes without altering current HEAD.
• Cleanup an old feature worktree after a code review and merge.
• Copy .env.production into a worktree to simulate a deployment-like environment for testing.

Frequently Asked Questions