worktree-cli
Git worktree management with worktree.py CLI. Use for creating worktrees, teardown, merging PRs, syncing branches, and Docker service management.
When & Why to Use This Skill
The worktree-cli skill is a powerful Git worktree management utility designed to streamline complex development workflows. It automates the creation, synchronization, and teardown of isolated environments, integrating Git operations with Docker service management and GitHub PR lifecycles to ensure developer productivity and environment consistency.
Use Cases
- Isolated Feature Development: Rapidly initialize new Git worktrees for specific issues, including automatic Docker service startup and database seeding for a ready-to-code environment.
- Full PR Lifecycle Automation: Use the 'complete' command to atomically merge pull requests, close linked tasks, synchronize branches, and remove temporary worktrees in a single operation.
- Multi-Environment Docker Management: Orchestrate and monitor Docker containers across different worktrees, allowing developers to check health status and view logs for specific feature branches.
- Branch Maintenance and Cleanup: Automatically rebase active feature branches onto the main branch after merges and prune stale registry entries or merged local branches to keep the repository clean.
- Environment Troubleshooting: Validate local configurations and detect divergence between feature branches and the main branch to prevent integration issues early in the development cycle.
| 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 + claim beads | --no-seed, --no-start, --build |
complete <pr> |
RECOMMENDED: Full lifecycle completion | - |
teardown <name> |
Remove worktree only | -f/--force, --keep-branch |
list |
Show all worktrees | -c/--compact |
merge-pr <num> |
Merge PR + teardown (no beads) | --skip-sync, --skip-teardown |
cleanup |
Remove merged branches | -f/--force (required to execute) |
logs |
View Docker logs | -n <lines>, -f/--follow |
Prefer complete over merge-pr - it handles beads task closure and sync automatically.
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 created (orchestrator calls this):
./worktree.py complete 123 # Merge + close beads + sync + teardown
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.
complete
RECOMMENDED: Complete a PR lifecycle atomically (merge + close beads + sync + teardown).
Usage: worktree.py complete PR_NUMBER
Arguments:
PR_NUMBER PR number to complete [required]
What it does:
- Verifies/merges the PR (skips if already merged)
- Closes the linked GitHub issue
- Finds and closes the beads task
- Syncs beads to remote (with retries)
- Tears down the worktree (Docker, files, branch)
Use this instead of merge-pr for orchestrator-managed workflows.
merge-pr
Merge a PR and sync worktrees (legacy - use complete instead).
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
Note: Does NOT handle beads. Use complete for full lifecycle.
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-syncuninstall- Remove post-commit hookstatus- 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 |