git-worktree-manager

Create git worktrees with deterministic ports and isolated environments.

Updated Mar 5, 2026
One-click install
npx skills add https://github.com/theandyalvarez7-ruby/claude-skills --skill git-worktree-manager-theandyalvarez7-ruby
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: git-worktree-manager
Source: https://github.com/theandyalvarez7-ruby/claude-skills/tree/main/engineering/git-worktree-manager
Command: npx skills add https://github.com/theandyalvarez7-ruby/claude-skills --skill git-worktree-manager-theandyalvarez7-ruby

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Git Worktree Manager standardizes branch isolation, port allocation, environment sync, and cleanup so each worktree behaves like an independent local app without stepping on another branch.

Core Features & Use Cases

  • 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 Use Cases:
  • 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

Quick Start

Run the worktree_manager script to create and prepare a new worktree by specifying the repository path, target branch, and worktree name.

Frequently Asked Questions about git-worktree-manager

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I manage git worktrees for parallel branches without port conflicts?

Git worktrees for parallel branches are managed by automating worktree creation, assigning non-conflicting ports using a deterministic base/stride scheme, and persisting assignments to isolate concurrent local development environments safely.

Why does my dev server break when I switch to another git worktree?

Dev servers break across git worktrees when multiple branches attempt to bind the same port or share environment files. Automating port allocation and syncing .env files isolates each worktree so concurrent branches run independently.

How do I automatically copy .env files when creating a new git worktree?

To automatically copy .env files when creating a git worktree, use tooling that detects local environment files in the main repository and replicates them into the new worktree directory during the setup process.

Can I detect stale and merged branches before cleaning up git worktrees?

Yes, stale and merged branches can be detected before cleaning up git worktrees by running a script that checks for uncommitted changes and identifies merged branches, ensuring outdated worktrees are safely removed without data loss.

Does git worktree automation work for agents that must not share a branch?

Git worktree automation works for multiple agents that must not share a branch by creating isolated worktrees with deterministic naming and separate environments, allowing agents to operate concurrently on independent branches without interference.

What is the best way to remove outdated git worktrees after a merge?

The best way to remove outdated git worktrees after a merge is to automate cleanup by identifying merged branches, detecting stale worktrees, and safely deleting the isolated directories instead of relying on ad-hoc rm -rf commands.