Agent skill · software engineering · alirezarezvani
git-worktree-manager
Use when running several branches or agents in parallel on one repo. Creates worktrees with isolated ports and env via worktree_manager.py and removes stale ones with worktree_cleanup.py.
Why this skill is useful
Adds executable scripts for managing Git worktrees, including automated port allocation and cleanup processes that enhance parallel development workflows.
What it needs
Requires python installed locally. About 4k tokens when loaded. Last updated 2026-08-05. 23,939 stars on the source repository.
What this skill does
Git Worktree Manager Tier: POWERFUL Category: Engineering Domain: Parallel Development & Branch Isolation Overview Use this skill to run parallel feature work safely with Git worktrees. It standardizes branch isolation, port allocation, environment sync, and cleanup so each worktree behaves like an independent local app without stepping on another branch. This skill is optimized for multi-agent workflows where each agent or terminal session owns one worktree. Core Capabilities Create worktrees from new or existing branches with deterministic naming Auto-allocate non-conflicting ports per worktree and persist assignments Copy local environment files (.env) from main repo to new worktree Optionally install dependencies based on lockfile detection Detect stale worktrees and uncommitted changes before cleanup Identify merged branches and safely remove outdated worktrees When to Use You need 2+ concurrent branches open locally You want isolated dev servers for feature, hotfix, and PR validation You are working with multiple agents that must not share a branch Your current branch is blocked but you need to ship a quick fix now You want repeatable cleanup instead of ad-hoc rm -rf operations Key Workflows 1. Create a Fully-Prepared Worktree 1. Pick a branch name and worktree name. 2. Run the manager script (creates branch if missing). 3. Review generated port map. 4. Start app using allocated ports. If you use JSON automation input: 2. Run Parallel Sessions Recommended convention: Main repo: integration branch (main/develop) on default port Worktree A: feature branch + offset ports Worktree B: hotfix branch + next offset Each worktree contains .worktree-ports.json with assigned ports. 3. Cleanup with Safety Checks 1. Scan all worktrees and stale age. 2. Inspect dirty trees and branch merge status. 3. Remove only merged + clean worktrees, or force explicitly. 4. Docker Compose Pattern Use per-worktree override files mapped from allocated ports. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills alirezarezvani/git-worktree-manager--3bb592