/worktree

Manage git worktrees for parallel agent work.

Usage

/worktree              # List all worktrees
/worktree new          # Create next agents/N
/worktree new bitkub   # Create agents/N-bitkub (named)
/worktree <N>          # Show path to agents/N
/worktree remove <N>   # Remove agents/N worktree

---

Step 0: Parse Arguments

ARGUMENTS: $ARGUMENTS

• No args, list, or status → List with Status
• new → Create New (unnamed)
• new <name> → Create New Named (e.g., new bitkub → agents/N-bitkub)
• Number (1, 2, 3...) → Show Path
• remove N → Remove

---

List Worktrees (default)

Aliases: /worktree, /worktree list, /worktree status

Just run:

git worktree list

Output is already clean and readable:

/path/to/repo         abc1234 [main]
/path/to/repo.wt-1    def5678 [agents/1]
/path/to/repo.wt-2    ghi9012 [agents/2]

---

Create New Agent Worktree

When user says /worktree new or /worktree new <name>:

Worktrees are created as siblings (not nested) to avoid VS Code indexing issues.

Parse the optional name from ARGUMENTS (everything after new):

# Get repo name and parent dir
REPO_NAME=$(basename $(pwd))
PARENT_DIR=$(dirname $(pwd))

# Parse name from arguments: "new bitkub" → NAME="bitkub", "new" → NAME=""
NAME=""  # Set from ARGUMENTS if present (e.g., "new bitkub" → NAME="bitkub")

# Find next available number
NEXT=1
while [ -d "$PARENT_DIR/$REPO_NAME.wt-$NEXT" ] || [ -d "$PARENT_DIR/$REPO_NAME.wt-$NEXT-"* ]; do
  NEXT=$((NEXT + 1))
done

# Build path and branch with optional name suffix
if [ -n "$NAME" ]; then
  WT_PATH="$PARENT_DIR/$REPO_NAME.wt-$NEXT-$NAME"
  BRANCH="agents/$NEXT-$NAME"
else
  WT_PATH="$PARENT_DIR/$REPO_NAME.wt-$NEXT"
  BRANCH="agents/$NEXT"
fi

# Create worktree with new branch
git worktree add "$WT_PATH" -b "$BRANCH"

# Report
echo "Created: $WT_PATH"
echo "Branch: $BRANCH"

After creating, display prominently:

Worktree Created

  Path:   /path/to/repo.wt-1-bitkub
  Branch: agents/1-bitkub

Open in VS Code: code /path/to/repo.wt-1-bitkub

Structure (named):

parent/
├── repo/                  # main (this workspace)
├── repo.wt-1-bitkub/      # branch: agents/1-bitkub
└── repo.wt-2-psru/        # branch: agents/2-psru

Structure (unnamed):

parent/
├── repo/           # main (this workspace)
├── repo.wt-1/      # branch: agents/1
└── repo.wt-2/      # branch: agents/2

---

Show Agent Path

When user says /worktree N (where N is a number):

REPO_NAME=$(basename $(pwd))
PARENT_DIR=$(dirname $(pwd))
WT_PATH="$PARENT_DIR/$REPO_NAME.wt-$N"

if [ -d "$WT_PATH" ]; then
  echo "Path: $WT_PATH"
  echo "Branch: agents/$N"
  echo ""
  echo "Open: code $WT_PATH"
else
  echo "Worktree $N not found. Use /worktree new to create."
fi

---

Remove Agent Worktree

When user says /worktree remove N:

REPO_NAME=$(basename $(pwd))
PARENT_DIR=$(dirname $(pwd))
WT_PATH="$PARENT_DIR/$REPO_NAME.wt-$N"

# Remove the worktree
git worktree remove "$WT_PATH"

# Optionally delete the branch
git branch -d agents/$N

Confirm before removing - ask user if they want to also delete the branch.

---

Philosophy

• Flat sibling worktrees - repo.wt-1, repo.wt-2 as direct siblings
• Each agent = own branch + directory - Open as separate workspace
• Use git -C path not cd - respect worktree boundaries
• Sync via PR to main - never force push
• Nothing is deleted - branches can be recovered

---

Quick Reference

Command	Result
/worktree	List all worktrees
/worktree new	Create repo.wt-N with branch agents/N
/worktree new bitkub	Create repo.wt-N-bitkub with branch agents/N-bitkub
/worktree 1	Show path to repo.wt-1
/worktree remove 2	Remove repo.wt-2

---

Self-Validation

After completing any action, verify your work:

After /worktree new

# 1. Check directory exists
ls -la "$WT_PATH"

# 2. Check branch exists
git branch --list "agents/$NEXT"

# 3. Check git worktree registered
git worktree list | grep "wt-$NEXT"

Expected:

• Directory repo.wt-N exists as sibling (not nested)
• Branch agents/N was created
• git worktree list shows the new entry
• Displayed path + VS Code command to user

After /worktree remove N

# 1. Check directory removed
[ ! -d "$WT_PATH" ] && echo "✓ Directory removed"

# 2. Check worktree unregistered
git worktree list | grep -v "wt-$N"

Expected:

• Directory no longer exists
• git worktree list no longer shows entry
• Asked user about branch deletion

Dry-Run Test (without creating)

# Preview what would happen
REPO_NAME=$(basename $(pwd))
PARENT_DIR=$(dirname $(pwd))
NEXT=1
while [ -d "$PARENT_DIR/$REPO_NAME.wt-$NEXT" ]; do
  NEXT=$((NEXT + 1))
done
echo "Would create: $PARENT_DIR/$REPO_NAME.wt-$NEXT"
echo "Would branch: agents/$NEXT"
git worktree list

Use this to validate logic before actual execution.