name	worktree-cli
description	Git worktree management with worktree.py CLI. Use for creating worktrees, teardown, merging PRs, syncing branches, and Docker service management.

worktree-cli Skill

Auto-generated reference for ./worktree.py commands.

This is the SOURCE OF TRUTH for worktree.py flags and options. Regenerate with: .claude/scripts/generate-cli-docs.sh

When to Use This Skill

Setting up new worktrees for issues
Tearing down worktrees after PR merge
Managing Docker services across worktrees
Syncing worktrees after merges
Troubleshooting worktree issues

Quick Reference

Command	Purpose	Key Flags
`setup <issue>`	Create worktree	`--no-seed`, `--no-start`, `--build`
`teardown <name>`	Remove worktree	`-f/--force`, `--keep-branch`
`list`	Show all worktrees	`-c/--compact`
`merge-pr <num>`	Merge PR + teardown + sync	`--skip-sync`, `--skip-teardown`
`cleanup`	Remove merged branches	`-f/--force` (required to execute)
`logs`	View Docker logs	`-n <lines>`, `-f/--follow`

Common Workflows

Start New Work

./worktree.py setup 42              # From issue number
cd ../42-feature-name
./worktree.py health                # Verify services

Complete Work

# After PR is approved:
./worktree.py merge-pr 123          # Merges, syncs, tears down

Maintenance

./worktree.py cleanup               # Dry-run: show what would be cleaned
./worktree.py cleanup --force       # Actually clean up merged branches
./worktree.py prune                 # Remove stale registry entries

Command Reference

setup

Create a new git worktree with isolated Docker environment.

Usage: worktree.py setup [OPTIONS] ISSUE_OR_BRANCH

Arguments:
  ISSUE_OR_BRANCH  Issue number, branch name, or GitHub issue URL [required]

Options:
  --no-seed    Skip database seeding
  --no-start   Don't start Docker services after setup
  --build      Build Docker images before starting
  --help       Show this message and exit

Examples:

./worktree.py setup 42                              # From issue number
./worktree.py setup 42/feature-audio-analysis       # Explicit branch name
./worktree.py setup main                            # Register main worktree
./worktree.py setup https://github.com/.../issues/42  # From GitHub URL

teardown

Remove a worktree and clean up all resources.

Usage: worktree.py teardown [OPTIONS] NAME_OR_BRANCH

Arguments:
  NAME_OR_BRANCH  Worktree name or branch to tear down [required]

Options:
  -f, --force      Force teardown even if branch not merged
  --keep-branch    Keep the git branch after teardown
  --help           Show this message and exit

What it does:

Stops Docker containers
Removes Docker volumes
Deletes git worktree
Optionally deletes branches (local and remote)

list

List all registered worktrees with full details.

Usage: worktree.py list [OPTIONS]

Options:
  -c, --compact  Show compact table view
  --help         Show this message and exit

Default: Expanded view with containers, ports, and credentials.

status

Show detailed status of current worktree.

Usage: worktree.py status [OPTIONS]

Options:
  --help  Show this message and exit

health

Check health of current worktree.

Usage: worktree.py health [OPTIONS]

Options:
  --help  Show this message and exit

ports

Show port allocations for all worktrees.

Usage: worktree.py ports [OPTIONS]

Options:
  --help  Show this message and exit

prune

Remove stale registry entries for non-existent worktrees.

Usage: worktree.py prune [OPTIONS]

Options:
  --help  Show this message and exit

Note: This command has NO --force flag. It runs immediately. For cleaning merged branches, use cleanup --force instead.

seed

Re-run database seeding from seed.sql.

Usage: worktree.py seed [OPTIONS]

Options:
  --help  Show this message and exit

start

Start Docker services for current worktree.

Usage: worktree.py start [OPTIONS]

Options:
  --help  Show this message and exit

stop

Stop Docker services for current worktree.

Usage: worktree.py stop [OPTIONS]

Options:
  --help  Show this message and exit

sync

Sync all worktrees with main (fetch, update main, rebase feature branches).

Usage: worktree.py sync [OPTIONS]

Options:
  --help  Show this message and exit

CRITICAL: Run this after any PR is merged to prevent divergence.

merge-pr

Merge a PR and sync all worktrees (RECOMMENDED workflow).

Usage: worktree.py merge-pr [OPTIONS] PR_NUMBER

Arguments:
  PR_NUMBER  PR number to merge [required]

Options:
  --skip-sync      Skip syncing other worktrees
  --skip-teardown  Skip auto-teardown of merged worktree
  --help           Show this message and exit

What it does:

Checks if PR is already merged (handles gracefully if so)
Merges the PR via gh CLI (squash merge) if not yet merged
Auto-tears down the merged worktree (prevents rebase issues)
Updates main branch
Rebases all active feature worktrees onto new main

validate

Validate environment and check for divergence.

Usage: worktree.py validate [OPTIONS]

Options:
  --help  Show this message and exit

Performs comprehensive checks:

Git configuration
Docker status
Port allocations
Main branch sync status
Feature branch divergence

cleanup

Clean up merged branches and orphaned Docker resources.

Usage: worktree.py cleanup [OPTIONS]

Options:
  -f, --force  Actually perform cleanup (default: dry-run)
  --help       Show this message and exit

IMPORTANT: By default runs in dry-run mode. Use --force to actually clean up.

logs

Show Docker compose logs for current worktree.

Usage: worktree.py logs [OPTIONS]

Options:
  -n, --lines INTEGER  Number of lines to show [default: 50]
  -f, --follow         Follow log output
  --help               Show this message and exit

hooks

Manage git hooks for automatic sync.

Usage: worktree.py hooks [OPTIONS] ACTION

Arguments:
  ACTION  Action: install, uninstall, or status [required]

Options:
  --help  Show this message and exit

Actions:

install - Install post-commit hook for auto-sync
uninstall - Remove post-commit hook
status - Check if hooks are installed

Disable auto-sync temporarily:

GTS_NO_AUTO_SYNC=1 git commit -m "message"

Common Mistakes to Avoid

Wrong	Right	Why
`prune --force`	`prune`	prune has no --force flag
`cleanup` alone	`cleanup --force`	cleanup is dry-run by default
`teardown` on main	Never teardown main	main is the base worktree
Manual `git pull` after merge	`merge-pr <num>`	merge-pr handles sync

worktree-cli

Install Skill

SKILL.md