Git Worktree Manager — Development

This skill standardizes the creation, management, and cleanup of Git worktrees for parallel development. It automates branch isolation, port allocation, environment file copying, and dependency installation, ensuring each worktree behaves like an independent local app. It is optimized for multi-agent workflows where each agent or terminal session owns one worktree.

engineering claude-code

📂 View skill on GitHub ↗ 🚀 How to use

✨ What it does

Creates worktrees from new or existing branches with deterministic naming.
Auto-allocates non-conflicting ports per worktree and persists assignments in .worktree-ports.json.
Copies local environment files (.env*) from the main repo to the new worktree.
Optionally installs dependencies based on lockfile detection.
Detects stale worktrees and uncommitted changes before cleanup.
Identifies merged branches and safely removes outdated worktrees.

🎯 When to use it

When you need to run multiple feature branches concurrently on the same repository.
When you want isolated dev servers for feature, hotfix, or PR validation.
When coordinating multiple agents that must not share a branch.
When your current branch is blocked but you need to ship a quick fix.
When you want repeatable cleanup instead of ad-hoc rm -rf operations.

🚀 How to use

Trigger by running the provided Python scripts (worktree_manager.py and worktree_cleanup.py) with appropriate arguments. The skill expects a repository path, branch name, worktree name, and optional base branch, dependency installation flag, and output format. Example prompts:

python scripts/worktree_manager.py --repo . --branch feature/new-auth --name wt-auth --base-branch main --install-deps --format text

python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text

Both scripts support JSON input via stdin or --input file for automation.

📄 Output: The skill produces worktrees with allocated ports, copied environment files, and optionally installed dependencies, along with a port map file (.worktree-ports.json) and cleanup reports.

📦 Add this skill to Claude Code

# 1. Get the skills repo
git clone --depth 1 https://github.com/alirezarezvani/claude-skills /tmp/claude-skills

# 2. Copy this skill into your project (or ~/.claude/skills for all projects)
mkdir -p .claude/skills
cp -r /tmp/claude-skills/engineering/skills/git-worktree-manager .claude/skills/git-worktree-manager

Skill source: engineering/skills/git-worktree-manager/SKILL.md

⚠️ Good to know

Requires Git and Python; assumes a clean baseline or intentional WIP commits in the main repo, and that no reserved local ports are occupied by non-repo services.

❓ FAQ

How are ports allocated to worktrees?

Ports are allocated using a default strategy of base + (index * stride) with collision checks, and the assignments are persisted in .worktree-ports.json.

What happens if dependency installation fails?

The worktree is still created, but the status is marked and manual recovery is required.

Can I remove a worktree with uncommitted changes?

No, the cleanup script only removes merged and clean worktrees unless you force removal explicitly.

🤖 Overview, features, install steps and FAQ were generated from the project's SKILL.md on Sep 4, 2026. Always check the original source before running commands.