git-worktree-manager

Overview of git-worktree-manager skill

What git-worktree-manager does

git-worktree-manager is an engineering skill for running multiple local Git worktrees without branch, port, environment, or cleanup conflicts. It combines operating guidance with Python helper scripts that create prepared worktrees, assign deterministic ports, copy local environment files, optionally install dependencies, and review stale worktrees before removal.

Use this skill when ordinary git worktree commands are not enough because each branch needs to behave like a separate runnable app.

Best fit for parallel Git workflows

The best-fit user is a developer, tech lead, or coding-agent operator who keeps two or more branches open at the same time: feature work, hotfixes, PR review, migration testing, or multi-agent implementation. git-worktree-manager for Git Workflows is especially useful when each agent or terminal session should own one branch and one isolated runtime instead of sharing a single checkout.

It is less valuable if you only switch branches occasionally, do not run local services, or already have a mature internal worktree wrapper.

Key differentiators before installing

The practical value is not just “create a worktree.” The skill adds repeatable conventions around:

• deterministic worktree naming and branch creation
• non-overlapping app, database, and Redis port allocation
• .env, .env.local, .env.development, and .envrc syncing
• dependency install detection from common lockfiles
• stale, dirty, and merged-branch cleanup checks
• Docker Compose patterns for per-worktree service isolation

That makes the git-worktree-manager skill more operational than a generic prompt about Git worktrees.

How to Use git-worktree-manager skill

git-worktree-manager install options

For a Claude-style skills setup, install from the repository with your skill manager if available:

npx skills add alirezarezvani/claude-skills --skill git-worktree-manager

If installing manually, copy the skill directory from:

engineering/skills/git-worktree-manager

into your local skills folder, such as ~/.claude/skills/git-worktree-manager, ~/.codex/skills/git-worktree-manager, or another compatible agent skill directory. After installation, verify that these files are present: SKILL.md, README.md, scripts/worktree_manager.py, scripts/worktree_cleanup.py, and the two files under references/.

Read these files first

For fast adoption, read in this order:

1. README.md for the command shape and tool list.
2. SKILL.md for the intended workflow and when-to-use guidance.
3. references/port-allocation-strategy.md before changing service ports.
4. references/docker-compose-patterns.md if your app uses Compose.
5. scripts/worktree_manager.py and scripts/worktree_cleanup.py before trusting automation in a production repository.

This matters because the scripts touch real checkouts, copy env files, and may install dependencies. Review the defaults before running them on a large monorepo or a repo with sensitive local configuration.

Practical git-worktree-manager usage

A typical create-and-prepare flow is:

python scripts/worktree_manager.py \
  --repo . \
  --branch feature/api-hardening \
  --name wt-api-hardening \
  --base-branch main \
  --install-deps \
  --format text

A cleanup review flow is:

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

Both tools support JSON input through --input <json-file> or stdin, which is useful for automation. Ask the agent to produce a command plan first, then run the script only after you confirm repo path, branch name, base branch, dependency install behavior, and cleanup policy.

Prompt pattern for better outputs

Weak prompt:

Set up a worktree for my feature.

Stronger prompt:

Use git-worktree-manager to prepare a new worktree for branch feature/billing-webhooks from main in repo /Users/me/app. Name it wt-billing-webhooks. I run app, Postgres, and Redis locally, so allocate non-conflicting ports and write the resulting mapping. Copy env files but do not install dependencies until I approve the command. Show the exact script command and any Docker Compose override I may need.

This gives the skill enough information to choose branch strategy, avoid port collisions, preserve safety around .env* files, and separate planning from execution.

git-worktree-manager skill FAQ

Is git-worktree-manager only for AI agents?

No. The skill is optimized for multi-agent work, but the scripts and conventions are useful for human developers too. The main benefit is repeatability: every worktree gets a predictable branch, directory, ports, copied env files, and cleanup review instead of ad hoc shell history.

How is this different from plain git worktree?

Plain git worktree add creates another checkout. It does not solve local app conflicts. git-worktree-manager adds the surrounding workflow: port blocks, .worktree-ports.json, environment file copying, optional dependency install, Docker Compose isolation advice, and cleanup checks for stale or merged branches.

Can beginners use this safely?

Yes, if they treat it as a guided workflow rather than a blind command runner. Beginners should first run list/review operations, use --format text, avoid automatic removal, and inspect generated commands before execution. The cleanup script checks for dirty worktrees, but you should still understand which branches are safe to delete.

When should I not use this skill?

Do not use it as-is if your repository has unusual environment handling, secrets that must never be copied, nonstandard dependency installation, or service ports managed by an internal platform. In those cases, use the git-worktree-manager guide as a starting pattern and customize the scripts or prompts before adoption.

How to Improve git-worktree-manager skill

Give git-worktree-manager stronger repo context

Better inputs produce safer worktree plans. Include:

• absolute repo path
• target branch and base branch
• desired worktree directory name
• package manager or lockfile expectations
• services that need ports
• whether .env* files may be copied
• whether dependency install is allowed
• cleanup age threshold and base branch for merge checks

This reduces guessing and prevents the agent from assuming defaults that do not match your app.

Tune port and Docker Compose conventions

The reference strategy uses default bases such as app 3000, Postgres 5432, Redis 6379, with a stride of 10 per worktree. If your stack has more services, reserve a larger contiguous block. If you run local infrastructure outside the worktrees, offset the base ports to avoid global collisions.

For Docker Compose, prefer per-worktree overrides, .env-driven ports, and unique project names such as:

docker compose -p myapp_wt_auth up -d

This avoids container, network, volume, and database collisions between branches.

Watch common failure modes

The most common issues are copied secrets, reused default database ports, shared Docker volumes across incompatible migrations, dependency installs in the wrong runtime, and deleting a worktree that still contains uncommitted work. Ask the agent to report dirty status, copied env files, selected ports, and install actions after every run.

For cleanup, start with review-only output. Enable removal only after confirming that a worktree is stale, clean, and merged into the expected base branch.

Iterate after the first output

After the first plan or command, ask for a focused revision instead of starting over:

Revise the git-worktree-manager command to skip dependency installation, use base branch develop, reserve ports for app, Postgres, Redis, and Mailhog, and output JSON for automation.

This keeps the skill anchored to the repository’s real constraints while improving safety and reproducibility.