Listing Worktrees

Overview

List all autonomy worktrees in the repository, showing their branch, location, HEAD commit, and lock status. Helps users navigate and manage multiple parallel worktrees.

Core principle: Worktrees are working directories, not branches. This lists checked-out worktrees only, not all autonomy branches.

When to Use

Use this skill when:

• User runs /list-worktrees command
• User wants to see which autonomy branches have active worktrees
• User needs to find worktree paths for navigation
• User wants to identify locked or stale worktrees

DO NOT use for:

• Listing all autonomy branches (use /list-branches instead)
• Analyzing branch status or progress (use /branch-status)
• Comparing branches (use /compare-branches)

Quick Reference

Process

Step 1: Get All Worktrees

Retrieve complete worktree list from git:

# Get porcelain format for machine parsing
worktree_list=$(git worktree list --porcelain)

# Format:
# worktree /path/to/worktree
# HEAD <commit-hash>
# branch refs/heads/<branch-name>
#
# worktree /path/to/another
# ...

Parse porcelain output:

# Extract worktree information
# Each worktree is separated by blank line
# Fields: worktree, HEAD, branch, detached, locked

# Example parsing with awk:
git worktree list --porcelain | awk '
  /^worktree / { path = substr($0, 10) }
  /^HEAD / { head = substr($0, 6); head_short = substr(head, 1, 7) }
  /^branch / { branch = substr($0, 8); gsub("refs/heads/", "", branch) }
  /^locked/ { locked = "yes" }
  /^$/ {
    if (path != "") {
      print path "|" head_short "|" branch "|" locked
      path = ""; head = ""; head_short = ""; branch = ""; locked = "no"
    }
  }
  END {
    if (path != "") {
      print path "|" head_short "|" branch "|" locked
    }
  }
'

Step 2: Filter to Autonomy Worktrees

Keep only worktrees in .worktrees/autonomy/:

# Filter parsed output to autonomy worktrees only
autonomy_worktrees=$(echo "$all_worktrees" | grep "\.worktrees/autonomy/")

# Count autonomy worktrees
count=$(echo "$autonomy_worktrees" | grep -c "^" || echo "0")

if [ "$count" -eq 0 ]; then
  echo "No autonomy worktrees found."
  echo ""
  echo "Autonomy branches exist in main repository or without worktrees."
  echo ""
  echo "To create a worktree:"
  echo "  /fork-worktree <strategy-name>"
  echo ""
  echo "To see all autonomy branches:"
  echo "  /list-branches"
  exit 0
fi

Step 3: Format Output Table

Create readable table with worktree information:

Autonomy Worktrees:

Branch                    Path                                      HEAD       Locked
autonomy/experiment-a     .worktrees/autonomy/experiment-a          a1b2c3d
autonomy/experiment-b     .worktrees/autonomy/experiment-b          d4e5f6g    🔒
autonomy/cdn-optimize     .worktrees/autonomy/cdn-optimize          h7i8j9k

Total: 3 autonomy worktrees

Column specifications:

• Branch: Full branch name (autonomy/<strategy-name>)
• Path: Relative path from repository root
• HEAD: Short commit hash (7 chars)
• Locked: 🔒 if locked, empty otherwise

Implementation:

# Print header
printf "%-25s %-41s %-10s %s\n" "Branch" "Path" "HEAD" "Locked"

# Print each worktree
echo "$autonomy_worktrees" | while IFS='|' read -r path head branch locked; do
  # Make path relative to repo root if absolute
  rel_path=$(realpath --relative-to="$repo_root" "$path" 2>/dev/null || echo "$path")

  # Lock indicator
  lock_icon=""
  if [ "$locked" = "yes" ]; then
    lock_icon="🔒"
  fi

  # Print row
  printf "%-25s %-41s %-10s %s\n" "$branch" "$rel_path" "$head" "$lock_icon"
done

Step 4: Provide Guidance

Add helpful navigation and management instructions:

To navigate to a worktree:
  cd .worktrees/autonomy/<strategy-name>

To remove a worktree:
  /remove-worktree <strategy-name>

To create a new worktree:
  /fork-worktree <strategy-name>

Note: This lists worktrees only. To see all autonomy branches (including those without worktrees):
  /list-branches

Additional context:

Locked worktrees (🔒):
- Cannot be removed without unlocking
- To unlock: git worktree unlock .worktrees/autonomy/<strategy-name>

Important Notes

Worktrees vs Branches

This command shows worktrees, not branches:

• A branch may exist without a worktree (created via /fork-iteration)
• A branch with worktree can also be checked out in main repo (though git prevents this)
• Use /list-branches to see all autonomy branches regardless of worktrees

Example scenario:

Branches in repo:
- autonomy/experiment-a (has worktree)
- autonomy/experiment-b (has worktree)
- autonomy/experiment-c (no worktree, created via /fork-iteration)

/list-worktrees shows: experiment-a, experiment-b
/list-branches shows: experiment-a, experiment-b, experiment-c

Main Worktree

The main repository working directory is technically a worktree, but NOT listed here:

• We filter to .worktrees/autonomy/ only
• Main repo worktree is not part of parallel agent workflow
• Focus on dedicated worktrees for clarity

Locked Worktrees

Worktrees can be locked to prevent accidental removal:

# Lock a worktree
git worktree lock .worktrees/autonomy/<strategy-name>

# Lock with reason
git worktree lock --reason "Long-running experiment" .worktrees/autonomy/<strategy-name>

# Unlock
git worktree unlock .worktrees/autonomy/<strategy-name>

When locked:

• /remove-worktree fails
• Must unlock manually before removal
• Useful for protecting important worktrees

Relative Paths

Paths displayed are relative to repository root:

• .worktrees/autonomy/experiment-a (not absolute /home/user/repo/.worktrees/...)
• Easier to copy-paste for cd commands
• Consistent regardless of where command invoked

Common Mistakes

After Listing Worktrees

User can:

• Navigate to worktree: cd .worktrees/autonomy/<strategy-name>
• Remove worktree: /remove-worktree <strategy-name>
• View branch status: /branch-status <strategy-name>
• Compare worktrees: /compare-branches <strategy-a> <strategy-b>

Integration with Other Commands

Relationship to other autonomy commands:

Typical workflow:

# See which worktrees exist
/list-worktrees

# Navigate to one
cd .worktrees/autonomy/experiment-a

# Work on iteration
/start-iteration
# ... work ...
/end-iteration

# Check all branches (including ones without worktrees)
/list-branches

# Clean up worktree when done
cd <repo-root>
/remove-worktree experiment-a

Empty State

When no autonomy worktrees exist:

No autonomy worktrees found.

Autonomy branches may exist in main repository or without worktrees.

To create a worktree:
  /fork-worktree <strategy-name>

To see all autonomy branches:
  /list-branches

To work on autonomy branch in main repo:
  /fork-iteration <strategy-name>
  /start-iteration