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:

/list-worktrees

/list-branches

/branch-status

/compare-branches

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