git-worktree-manager

# 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.

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

If you use JSON automation input:

```bash
cat config.json | python scripts/worktree_manager.py --format json
# or
python scripts/worktree_manager.py --input config.json --format json
```

### 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.

```bash
python scripts/worktree_cleanup.py --repo . --stale-days 14 --format text
python scripts/worktree_cleanup.py --repo . --remove-merged --format text
```

### 4. Docker Compose Pattern

Use per-worktree override files mapped from allocated ports. The script outputs a deterministic port map; apply it to `docker-compose.worktree.yml`.

See [docker-compose-patterns.md](references/docker-compose-patterns.md) for concrete templates.

### 5. Port Allocation Strategy

Default strategy is `base + (index * stride)` with collision checks:

- App: `3000`
- Postgres: `5432`
- Redis: `6379`
- Stride: `10`

See [port-allocation-strategy.md](references/port-allocation-strategy.md) for the full strategy and edge cases.

## Script Interfaces

- `python scripts/worktree_manager.py --help`
  - Create/list worktrees
  - Allocate/persist ports
  - Copy `.env*` files
  - Optional dependency installation
- `python scripts/worktree_cleanup.py --help`
  - Stale detection by age
  - Dirty-state detection
  - Merged-branch detection
  - Optional safe removal

Both tools support stdin JSON and `--input` file mode for automation pipelines.

## Common Pitfalls

1. Creating worktrees inside the main repo directory
2. Reusing `localhost:3000` across all branches
3. Sharing one database URL across isolated feature branches
4. Removing a worktree with uncommitted changes
5. Forgetting to prune old metadata after branch deletion
6. Assuming merged status without checking against the target branch

## Best Practices

1. One branch per worktree, one agent per worktree.
2. Keep worktrees short-lived; remove after merge.
3. Use a deterministic naming pattern (`wt-<topic>`).
4. Persist port mappings in file, not memory or terminal notes.
5. Run cleanup scan weekly in active repos.
6. Use `--format json` for machine flows and `--format text` for human review.
7. Never force-remove dirty worktrees unless changes are intentionally discarded.

## Validation Checklist

Before claiming setup complete:

1. `git worktree list` shows expected path + branch.
2. `.worktree-ports.json` exists and contains unique ports.
3. `.env` files copied successfully (if present in source repo).
4. Dependency install command exits with code `0` (if enabled).
5. Cleanup scan reports no unintended stale dirty trees.

## References

- [port-allocation-strategy.md](references/port-allocation-strategy.md)
- [docker-compose-patterns.md](references/docker-compose-patterns.md)
- [README.md](README.md) for quick start and installation details

## Decision Matrix

Use this quick selector before creating a new worktree:

- Need isolated dependencies and server ports -> create a new worktree
- Need only a quick local diff review -> stay on current tree
- Need hotfix while feature branch is dirty -> create dedicated hotfix worktree
- Need ephemeral reproduction branch for bug triage -> create temporary worktree and cleanup same day

## Operational Checklist

### Before Creation

1. Confirm main repo has clean baseline or intentional WIP commits.
2. Confirm target branch naming convention.
3. Confirm required base branch exists (`main`/`develop`).
4. Confirm no reserved local ports are already occupied by non-repo services.

### After Creation

1. Verify `git status` branch matches expected branch.
2. Verify `.worktree-ports.json` exists.
3. Verify app boots on allocated app port.
4. Verify DB and cache endpoints target isolated ports.

### Before Removal

1. Verify branch has upstream and is merged when intended.
2. Verify no uncommitted files remain.
3. Verify no running containers/processes depend on this worktree path.

## CI and Team Integration

- Use worktree path naming that maps to task ID (`wt-1234-auth`).
- Include the worktree path in terminal title to avoid wrong-window commits.
- In automated setups, persist creation metadata in CI artifacts/logs.
- Trigger cleanup report in scheduled jobs and post summary to team channel.

## Failure Recovery

- If `git worktree add` fails due to existing path: inspect path, do not overwrite.
- If dependency install fails: keep worktree created, mark status and continue manual recovery.
- If env copy fails: continue with warning and explicit missing file list.
- If port allocation collides with external service: rerun with adjusted base ports.

{
  "format": "aiskill/v1",
  "skill": {
    "name": "git-worktree-manager",
    "slug": "git-worktree-manager",
    "version": "1.0.0",
    "description": "Run parallel feature work safely with Git worktrees. Standardizes branch isolation, port allocation, environment sync, and cleanup so each worktree behaves like an independent local app. Optimized for multi-agent workflows where each agent or terminal session owns one worktree. Use when running multiple feature branches simultaneously, isolating experimental work, or coordinating multi-agent development across the same repo.",
    "category": "Development",
    "tags": [
      "dev-workflow",
      "git",
      "agents"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Git Worktree Manager\r\n\r\n**Tier:** POWERFUL  \r\n**Category:** Engineering  \r\n**Domain:** Parallel Development & Branch Isolation\r\n\r\n## Overview\r\n\r\nUse 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.\r\n\r\nThis skill is optimized for multi-agent workflows where each agent or terminal session owns one worktree.\r\n\r\n## Core Capabilities\r\n\r\n- Create worktrees from new or existing branches with deterministic naming\r\n- Auto-allocate non-conflicting ports per worktree and persist assignments\r\n- Copy local environment files (`.env*`) from main repo to new worktree\r\n- Optionally install dependencies based on lockfile detection\r\n- Detect stale worktrees and uncommitted changes before cleanup\r\n- Identify merged branches and safely remove outdated worktrees\r\n\r\n## When to Use\r\n\r\n- You need 2+ concurrent branches open locally\r\n- You want isolated dev servers for feature, hotfix, and PR validation\r\n- You are working with multiple agents that must not share a branch\r\n- Your current branch is blocked but you need to ship a quick fix now\r\n- You want repeatable cleanup instead of ad-hoc `rm -rf` operations\r\n\r\n## Key Workflows\r\n\r\n### 1. Create a Fully-Prepared Worktree\r\n\r\n1. Pick a branch name and worktree name.\r\n2. Run the manager script (creates branch if missing).\r\n3. Review generated port map.\r\n4. Start app using allocated ports.\r\n\r\n```bash\r\npython scripts/worktree_manager.py \\\r\n  --repo . \\\r\n  --branch feature/new-auth \\\r\n  --name wt-auth \\\r\n  --base-branch main \\\r\n  --install-deps \\\r\n  --format text\r\n```\r\n\r\nIf you use JSON automation input:\r\n\r\n```bash\r\ncat config.json | python scripts/worktree_manager.py --format json\r\n# or\r\npython scripts/worktree_manager.py --input config.json --format json\r\n```\r\n\r\n### 2. Run Parallel Sessions\r\n\r\nRecommended convention:\r\n\r\n- Main repo: integration branch (`main`/`develop`) on default port\r\n- Worktree A: feature branch + offset ports\r\n- Worktree B: hotfix branch + next offset\r\n\r\nEach worktree contains `.worktree-ports.json` with assigned ports.\r\n\r\n### 3. Cleanup with Safety Checks\r\n\r\n1. Scan all worktrees and stale age.\r\n2. Inspect dirty trees and branch merge status.\r\n3. Remove only merged + clean worktrees, or force explicitly.\r\n\r\n```bash\r\npython scripts/worktree_cleanup.py --repo . --stale-days 14 --format text\r\npython scripts/worktree_cleanup.py --repo . --remove-merged --format text\r\n```\r\n\r\n### 4. Docker Compose Pattern\r\n\r\nUse per-worktree override files mapped from allocated ports. The script outputs a deterministic port map; apply it to `docker-compose.worktree.yml`.\r\n\r\nSee [docker-compose-patterns.md](references/docker-compose-patterns.md) for concrete templates.\r\n\r\n### 5. Port Allocation Strategy\r\n\r\nDefault strategy is `base + (index * stride)` with collision checks:\r\n\r\n- App: `3000`\r\n- Postgres: `5432`\r\n- Redis: `6379`\r\n- Stride: `10`\r\n\r\nSee [port-allocation-strategy.md](references/port-allocation-strategy.md) for the full strategy and edge cases.\r\n\r\n## Script Interfaces\r\n\r\n- `python scripts/worktree_manager.py --help`\r\n  - Create/list worktrees\r\n  - Allocate/persist ports\r\n  - Copy `.env*` files\r\n  - Optional dependency installation\r\n- `python scripts/worktree_cleanup.py --help`\r\n  - Stale detection by age\r\n  - Dirty-state detection\r\n  - Merged-branch detection\r\n  - Optional safe removal\r\n\r\nBoth tools support stdin JSON and `--input` file mode for automation pipelines.\r\n\r\n## Common Pitfalls\r\n\r\n1. Creating worktrees inside the main repo directory\r\n2. Reusing `localhost:3000` across all branches\r\n3. Sharing one database URL across isolated feature branches\r\n4. Removing a worktree with uncommitted changes\r\n5. Forgetting to prune old metadata after branch deletion\r\n6. Assuming merged status without checking against the target branch\r\n\r\n## Best Practices\r\n\r\n1. One branch per worktree, one agent per worktree.\r\n2. Keep worktrees short-lived; remove after merge.\r\n3. Use a deterministic naming pattern (`wt-<topic>`).\r\n4. Persist port mappings in file, not memory or terminal notes.\r\n5. Run cleanup scan weekly in active repos.\r\n6. Use `--format json` for machine flows and `--format text` for human review.\r\n7. Never force-remove dirty worktrees unless changes are intentionally discarded.\r\n\r\n## Validation Checklist\r\n\r\nBefore claiming setup complete:\r\n\r\n1. `git worktree list` shows expected path + branch.\r\n2. `.worktree-ports.json` exists and contains unique ports.\r\n3. `.env` files copied successfully (if present in source repo).\r\n4. Dependency install command exits with code `0` (if enabled).\r\n5. Cleanup scan reports no unintended stale dirty trees.\r\n\r\n## References\r\n\r\n- [port-allocation-strategy.md](references/port-allocation-strategy.md)\r\n- [docker-compose-patterns.md](references/docker-compose-patterns.md)\r\n- [README.md](README.md) for quick start and installation details\r\n\r\n## Decision Matrix\r\n\r\nUse this quick selector before creating a new worktree:\r\n\r\n- Need isolated dependencies and server ports -> create a new worktree\r\n- Need only a quick local diff review -> stay on current tree\r\n- Need hotfix while feature branch is dirty -> create dedicated hotfix worktree\r\n- Need ephemeral reproduction branch for bug triage -> create temporary worktree and cleanup same day\r\n\r\n## Operational Checklist\r\n\r\n### Before Creation\r\n\r\n1. Confirm main repo has clean baseline or intentional WIP commits.\r\n2. Confirm target branch naming convention.\r\n3. Confirm required base branch exists (`main`/`develop`).\r\n4. Confirm no reserved local ports are already occupied by non-repo services.\r\n\r\n### After Creation\r\n\r\n1. Verify `git status` branch matches expected branch.\r\n2. Verify `.worktree-ports.json` exists.\r\n3. Verify app boots on allocated app port.\r\n4. Verify DB and cache endpoints target isolated ports.\r\n\r\n### Before Removal\r\n\r\n1. Verify branch has upstream and is merged when intended.\r\n2. Verify no uncommitted files remain.\r\n3. Verify no running containers/processes depend on this worktree path.\r\n\r\n## CI and Team Integration\r\n\r\n- Use worktree path naming that maps to task ID (`wt-1234-auth`).\r\n- Include the worktree path in terminal title to avoid wrong-window commits.\r\n- In automated setups, persist creation metadata in CI artifacts/logs.\r\n- Trigger cleanup report in scheduled jobs and post summary to team channel.\r\n\r\n## Failure Recovery\r\n\r\n- If `git worktree add` fails due to existing path: inspect path, do not overwrite.\r\n- If dependency install fails: keep worktree created, mark status and continue manual recovery.\r\n- If env copy fails: continue with warning and explicit missing file list.\r\n- If port allocation collides with external service: rerun with adjusted base ports.",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The git-worktree-manager/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/git-worktree-manager",
    "exported_at": "2026-11-03T07:41:20.326Z"
  }
}

format: aiskill/v1
skill:
  name: git-worktree-manager
  slug: git-worktree-manager
  version: 1.0.0
  description: >-
    Run parallel feature work safely with Git worktrees. Standardizes branch isolation, port
    allocation, environment sync, and cleanup so each worktree behaves like an independent local
    app. Optimized for multi-agent workflows where each agent or terminal session owns one worktree.
    Use when running multiple feature branches simultaneously, isolating experimental work, or
    coordinating multi-agent development across the same repo.
  category: Development
  tags:
    - dev-workflow
    - git
    - agents
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Git Worktree Manager\r\n\r\n**Tier:** POWERFUL  \r\n**Category:** Engineering  \r\n**Domain:** Parallel Development & Branch Isolation\r\n\r\n## Overview\r\n\r\nUse 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.\r\n\r\nThis skill is optimized for multi-agent workflows where each agent or terminal session owns one worktree.\r\n\r\n## Core Capabilities\r\n\r\n- Create worktrees from new or existing branches with deterministic naming\r\n- Auto-allocate non-conflicting ports per worktree and persist assignments\r\n- Copy local environment files (`.env*`) from main repo to new worktree\r\n- Optionally install dependencies based on lockfile detection\r\n- Detect stale worktrees and uncommitted changes before cleanup\r\n- Identify merged branches and safely remove outdated worktrees\r\n\r\n## When to Use\r\n\r\n- You need 2+ concurrent branches open locally\r\n- You want isolated dev servers for feature, hotfix, and PR validation\r\n- You are working with multiple agents that must not share a branch\r\n- Your current branch is blocked but you need to ship a quick fix now\r\n- You want repeatable cleanup instead of ad-hoc `rm -rf` operations\r\n\r\n## Key Workflows\r\n\r\n### 1. Create a Fully-Prepared Worktree\r\n\r\n1. Pick a branch name and worktree name.\r\n2. Run the manager script (creates branch if missing).\r\n3. Review generated port map.\r\n4. Start app using allocated ports.\r\n\r\n```bash\r\npython scripts/worktree_manager.py \\\r\n  --repo . \\\r\n  --branch feature/new-auth \\\r\n  --name wt-auth \\\r\n  --base-branch main \\\r\n  --install-deps \\\r\n  --format text\r\n```\r\n\r\nIf you use JSON automation input:\r\n\r\n```bash\r\ncat config.json | python scripts/worktree_manager.py --format json\r\n# or\r\npython scripts/worktree_manager.py --input config.json --format json\r\n```\r\n\r\n### 2. Run Parallel Sessions\r\n\r\nRecommended convention:\r\n\r\n- Main repo: integration branch (`main`/`develop`) on default port\r\n- Worktree A: feature branch + offset ports\r\n- Worktree B: hotfix branch + next offset\r\n\r\nEach worktree contains `.worktree-ports.json` with assigned ports.\r\n\r\n### 3. Cleanup with Safety Checks\r\n\r\n1. Scan all worktrees and stale age.\r\n2. Inspect dirty trees and branch merge status.\r\n3. Remove only merged + clean worktrees, or force explicitly.\r\n\r\n```bash\r\npython scripts/worktree_cleanup.py --repo . --stale-days 14 --format text\r\npython scripts/worktree_cleanup.py --repo . --remove-merged --format text\r\n```\r\n\r\n### 4. Docker Compose Pattern\r\n\r\nUse per-worktree override files mapped from allocated ports. The script outputs a deterministic port map; apply it to `docker-compose.worktree.yml`.\r\n\r\nSee [docker-compose-patterns.md](references/docker-compose-patterns.md) for concrete templates.\r\n\r\n### 5. Port Allocation Strategy\r\n\r\nDefault strategy is `base + (index * stride)` with collision checks:\r\n\r\n- App: `3000`\r\n- Postgres: `5432`\r\n- Redis: `6379`\r\n- Stride: `10`\r\n\r\nSee [port-allocation-strategy.md](references/port-allocation-strategy.md) for the full strategy and edge cases.\r\n\r\n## Script Interfaces\r\n\r\n- `python scripts/worktree_manager.py --help`\r\n  - Create/list worktrees\r\n  - Allocate/persist ports\r\n  - Copy `.env*` files\r\n  - Optional dependency installation\r\n- `python scripts/worktree_cleanup.py --help`\r\n  - Stale detection by age\r\n  - Dirty-state detection\r\n  - Merged-branch detection\r\n  - Optional safe removal\r\n\r\nBoth tools support stdin JSON and `--input` file mode for automation pipelines.\r\n\r\n## Common Pitfalls\r\n\r\n1. Creating worktrees inside the main repo directory\r\n2. Reusing `localhost:3000` across all branches\r\n3. Sharing one database URL across isolated feature branches\r\n4. Removing a worktree with uncommitted changes\r\n5. Forgetting to prune old metadata after branch deletion\r\n6. Assuming merged status without checking against the target branch\r\n\r\n## Best Practices\r\n\r\n1. One branch per worktree, one agent per worktree.\r\n2. Keep worktrees short-lived; remove after merge.\r\n3. Use a deterministic naming pattern (`wt-<topic>`).\r\n4. Persist port mappings in file, not memory or terminal notes.\r\n5. Run cleanup scan weekly in active repos.\r\n6. Use `--format json` for machine flows and `--format text` for human review.\r\n7. Never force-remove dirty worktrees unless changes are intentionally discarded.\r\n\r\n## Validation Checklist\r\n\r\nBefore claiming setup complete:\r\n\r\n1. `git worktree list` shows expected path + branch.\r\n2. `.worktree-ports.json` exists and contains unique ports.\r\n3. `.env` files copied successfully (if present in source repo).\r\n4. Dependency install command exits with code `0` (if enabled).\r\n5. Cleanup scan reports no unintended stale dirty trees.\r\n\r\n## References\r\n\r\n- [port-allocation-strategy.md](references/port-allocation-strategy.md)\r\n- [docker-compose-patterns.md](references/docker-compose-patterns.md)\r\n- [README.md](README.md) for quick start and installation details\r\n\r\n## Decision Matrix\r\n\r\nUse this quick selector before creating a new worktree:\r\n\r\n- Need isolated dependencies and server ports -> create a new worktree\r\n- Need only a quick local diff review -> stay on current tree\r\n- Need hotfix while feature branch is dirty -> create dedicated hotfix worktree\r\n- Need ephemeral reproduction branch for bug triage -> create temporary worktree and cleanup same day\r\n\r\n## Operational Checklist\r\n\r\n### Before Creation\r\n\r\n1. Confirm main repo has clean baseline or intentional WIP commits.\r\n2. Confirm target branch naming convention.\r\n3. Confirm required base branch exists (`main`/`develop`).\r\n4. Confirm no reserved local ports are already occupied by non-repo services.\r\n\r\n### After Creation\r\n\r\n1. Verify `git status` branch matches expected branch.\r\n2. Verify `.worktree-ports.json` exists.\r\n3. Verify app boots on allocated app port.\r\n4. Verify DB and cache endpoints target isolated ports.\r\n\r\n### Before Removal\r\n\r\n1. Verify branch has upstream and is merged when intended.\r\n2. Verify no uncommitted files remain.\r\n3. Verify no running containers/processes depend on this worktree path.\r\n\r\n## CI and Team Integration\r\n\r\n- Use worktree path naming that maps to task ID (`wt-1234-auth`).\r\n- Include the worktree path in terminal title to avoid wrong-window commits.\r\n- In automated setups, persist creation metadata in CI artifacts/logs.\r\n- Trigger cleanup report in scheduled jobs and post summary to team channel.\r\n\r\n## Failure Recovery\r\n\r\n- If `git worktree add` fails due to existing path: inspect path, do not overwrite.\r\n- If dependency install fails: keep worktree created, mark status and continue manual recovery.\r\n- If env copy fails: continue with warning and explicit missing file list.\r\n- If port allocation collides with external service: rerun with adjusted base ports."
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The git-worktree-manager/ folder
        contains SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/git-worktree-manager
  exported_at: "2026-11-03T07:41:20.326Z"