Git Worktree Manager

Manage git worktrees for AI agent workflows where Claude creates isolated working directories for tickets, features, or bug fixes.

Overview

This skill provides scripts to:

• •Create worktrees in .worktrees/ with branches from a base branch
• •List all worktrees with their status
• •Remove specific worktrees by path or branch name
• •Prune stale worktrees that no longer exist on disk

Directory Structure

Worktrees are organized in a project-based subdirectory pattern:

my-project/
├── .git/
├── src/
├── .worktrees/
│   ├── feature-add-auth/      # Created for feature/add-auth
│   ├── feature-fix-bug-123/   # Created for feature/fix-bug-123
│   └── hotfix-security/       # Created for hotfix/security
└── ...

Branch names are sanitized for directory names (e.g., feature/add-auth → feature-add-auth).

Typical Agent Workflow

1. •Receive ticket - Agent is asked to work on a feature or bug
2. •Create worktree - Create isolated workspace for the ticket
3. •Do work - Make changes, test, commit
4. •Clean up - Remove worktree when done or prune stale ones

Scripts

All scripts are in the scripts/ directory and should be run with Python 3.

create_worktree.py

Create a new worktree with a branch from a base branch.

Usage:

python3 scripts/create_worktree.py <branch-name> [base-branch] [repo-path]

Parameters:

• •branch-name (required): Name of the branch (e.g., feature/add-auth)
• •base-branch (optional): Base branch to branch from (default: main)
• •repo-path (optional): Path to repository (default: current directory)

Behavior:

• •Creates .worktrees/ directory if it doesn't exist
• •If branch exists: checks it out in the worktree
• •If branch doesn't exist: creates it from base branch and checks out in worktree
• •If base branch doesn't exist locally: attempts to fetch from origin
• •Sanitizes branch name for directory (replaces / with -)

Examples:

# Create worktree for feature/add-auth from main
python3 scripts/create_worktree.py feature/add-auth

# Create worktree from develop branch
python3 scripts/create_worktree.py feature/new-ui develop

# Create worktree in specific repo
python3 scripts/create_worktree.py feature/fix-bug main /path/to/repo

Output:

• •Prints status messages during creation
• •Returns worktree path on success
• •Exits with error code 1 on failure

list_worktrees.py

List all worktrees with their current status.

Usage:

python3 scripts/list_worktrees.py [--json] [repo-path]

Parameters:

• •--json (optional): Output as JSON instead of formatted text
• •repo-path (optional): Path to repository (default: current directory)

Output includes:

• •Worktree path
• •Branch name
• •Status (clean, uncommitted changes, stale)
• •Last commit info
• •Count of changed files (if any)
• •Warning about stale worktrees

Examples:

# List worktrees in current repo
python3 scripts/list_worktrees.py

# List worktrees as JSON
python3 scripts/list_worktrees.py --json

# List worktrees in specific repo
python3 scripts/list_worktrees.py /path/to/repo

remove_worktree.py

Remove a specific worktree by path or branch name.

Usage:

python3 scripts/remove_worktree.py <path-or-branch> [--force] [--delete-branch] [repo-path]

Parameters:

• •path-or-branch (required): Worktree path or branch name
• •--force or -f (optional): Force removal even with uncommitted changes
• •--delete-branch or -d (optional): Also delete the associated branch
• •repo-path (optional): Path to repository (default: current directory)

Safety features:

• •Prevents removal of main worktree
• •Checks for uncommitted changes (unless --force)
• •Falls back to manual removal if git command fails
• •Automatically prunes stale references

Examples:

# Remove by branch name
python3 scripts/remove_worktree.py feature/add-auth

# Remove by path
python3 scripts/remove_worktree.py /path/to/repo/.worktrees/feature-add-auth

# Force remove with uncommitted changes
python3 scripts/remove_worktree.py feature/old-feature --force

# Remove worktree and delete branch
python3 scripts/remove_worktree.py feature/completed --delete-branch

# Combine flags
python3 scripts/remove_worktree.py feature/abandoned --force --delete-branch

prune_worktrees.py

Prune stale worktrees (where directory no longer exists).

Usage:

python3 scripts/prune_worktrees.py [--dry-run] [repo-path]

Parameters:

• •--dry-run or -n (optional): Show what would be pruned without making changes
• •repo-path (optional): Path to repository (default: current directory)

Behavior:

• •Scans all registered worktrees
• •Identifies worktrees where directory doesn't exist
• •Removes stale worktree references from git's records
• •Does not delete branches (only removes worktree references)

Examples:

# Preview stale worktrees
python3 scripts/prune_worktrees.py --dry-run

# Prune stale worktrees
python3 scripts/prune_worktrees.py

# Prune in specific repo
python3 scripts/prune_worktrees.py /path/to/repo

Best Practices for AI Agents

When to Create a Worktree

Create a worktree when:

• •Starting work on a new feature or bug fix
• •Need isolated workspace separate from main development
• •Working on multiple tickets simultaneously
• •Need to preserve uncommitted work while switching contexts

When to Remove a Worktree

Remove a worktree when:

• •Work is complete and merged
• •Ticket is closed or abandoned
• •Need to free up disk space
• •Switching to work on different ticket

When to Prune

Run prune regularly to:

• •Clean up after manual directory deletions
• •Maintain accurate worktree listings
• •Free up git's internal worktree references
• •Keep workspace organized

Recommended Agent Pattern

# 1. Start work on ticket
worktree_path = create_worktree("feature/ticket-123")

# 2. Do work in worktree
os.chdir(worktree_path)
# ... make changes, commit, etc.

# 3. Clean up when done
remove_worktree("feature/ticket-123", delete_branch=True)

# 4. Periodically prune stale worktrees
prune_worktrees()

Error Handling

All scripts:

• •Return exit code 0 on success
• •Return exit code 1 on error
• •Print error messages to stderr
• •Provide descriptive error messages

Common errors:

• •Not in a git repository
• •Worktree already exists
• •Branch already exists (when expected to create new)
• •Uncommitted changes (when removing without --force)
• •Permission issues

Integration with Agent Workflows

Example: Feature Development

# Agent receives ticket: "Add user authentication"
python3 scripts/create_worktree.py feature/add-auth

# Work in the worktree
cd .worktrees/feature-add-auth
# ... implement feature, test, commit ...

# When done
cd ../..
python3 scripts/remove_worktree.py feature/add-auth --delete-branch

Example: Bug Fix

# Agent receives bug report: "Fix login crash"
python3 scripts/create_worktree.py feature/fix-login-crash

# Fix the bug
cd .worktrees/feature-fix-login-crash
# ... fix bug, test, commit ...

# Create PR, then cleanup
cd ../..
python3 scripts/remove_worktree.py feature/fix-login-crash
# Keep branch for PR, so don't use --delete-branch

Example: Multiple Tickets

# List current worktrees to see what's in progress
python3 scripts/list_worktrees.py

# Switch between tickets by changing directory
cd .worktrees/feature-ticket-123
# ... work on ticket 123 ...

cd ../feature-ticket-456
# ... work on ticket 456 ...

# Clean up completed tickets
cd ../..
python3 scripts/remove_worktree.py feature/ticket-123 --delete-branch

Notes

• •Worktrees share the same git repository, so fetches and branches are shared
• •Each worktree can have uncommitted changes independent of others
• •Disk space: each worktree is a full working directory (but shares .git)
• •Performance: worktrees are much faster than cloning for multiple workspaces