# Worktree Status

> Audit all git worktrees in the current project. Use when the user asks about worktree status, which branches are merged, which have uncommitted changes, or which worktrees can be safely cleaned up.

- Skill: `moonshotai/worktree-status` (Agent Skill)
- Install (CLI): `npx skillmds@latest add moonshotai/worktree-status`
- Raw SKILL.md: https://api.skillmd.com/api/skills/moonshotai/worktree-status/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: moonshotai (https://skillmd.com/u/moonshotai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/moonshotai/worktree-status

---


# worktree-status

Report the status of every git worktree for the current project, covering
dirty state and merge status.

## When to use

- User asks "which worktrees can I clean up?"
- User asks "what's the status of my worktrees / branches?"
- Before batch-cleaning worktrees, to avoid losing uncommitted work

## Procedure

### 1. Pull latest main (MANDATORY)

You MUST pull latest main before any status checks. Without this, merge
detection (both ancestry and content diff) will produce stale results and
you may mistakenly conclude a branch is not merged.

```bash
cd "$(git rev-parse --show-toplevel)" && git pull origin main
```

### 2. Collect worktree info

```bash
PROJECT_DIR="$(git rev-parse --show-toplevel)"

for wt in $(git worktree list --porcelain | grep "^worktree " | sed 's/^worktree //' | grep -v "$PROJECT_DIR$"); do
  branch=$(git -C "$wt" branch --show-current 2>/dev/null)
  [ -z "$branch" ] && branch="(detached)"
  name=$(basename "$wt")

  # dirty?
  if [ -z "$(git -C "$wt" status --short 2>/dev/null)" ]; then
    dirty="clean"
  else
    dirty="DIRTY"
  fi

  # merged into origin/main?
  # NOTE: This project uses squash merges exclusively. `git merge-base
  # --is-ancestor` does NOT detect squash-merged branches. Always follow
  # up with a content diff (step 3) for branches that appear "not merged".
  if [ "$branch" != "(detached)" ]; then
    if git merge-base --is-ancestor "$branch" origin/main 2>/dev/null; then
      merged="merged"
    else
      merged="not merged (verify with content diff)"
    fi
  else
    merged="n/a"
  fi

  echo ""
  echo "[$name]  branch=$branch  $dirty  $merged"
  if [ "$dirty" = "DIRTY" ]; then
    git -C "$wt" status --short 2>/dev/null | sed 's/^/  /'
  fi
done
```

### 3. Detect squash-merged branches (content diff)

For any branch that shows "not merged", check whether the branch's
changes are already in main. The correct method is:

1. Find the files the branch actually changed (relative to merge-base).
2. For each changed file, compare the branch version with main.
   If all files are identical, the branch was squash-merged.

**⚠️ Do NOT use `git diff origin/main <branch>`** — that compares the
two tips directly, so commits added to main *after* the branch diverged
will show up as false differences.

```bash
BRANCH="<branch>"
BASE=$(git merge-base origin/main "$BRANCH")

# List files the branch touched
FILES=$(git diff --name-only "$BASE" "$BRANCH")

# Compare each file between branch and current main
for f in $FILES; do
  d=$(git diff "$BRANCH" origin/main -- "$f" | wc -l)
  if [ "$d" != "0" ]; then
    echo "❌ $f — differs"
  else
    echo "✅ $f — identical in main"
  fi
done
# All ✅ = squash-merged
```

### 4. (Optional) Check for associated tmux sessions

Only run this if `tmux` is available and relevant (e.g. worktrees were
created by codex-worker or similar tooling). Skip if not applicable.

```bash
tmux ls 2>/dev/null | grep -E 'codex-worker|<other-pattern>' || true
```

### 5. Present results

**Always present results as a Markdown table.** Every worktree must appear
as a row. Never use abbreviated or prose-only summaries.

| Worktree | Branch | Dirty | Merged | Can clean? |
|---|---|---|---|---|
| `example-wt` | `feat-foo` | ✅ clean | ✅ squash-merged | ✅ |
| `another-wt` | `fix-bar` | ⚠️ 3 files | ❌ not merged | ❌ dirty + not merged |
| `detached-wt` | (detached) | ⚠️ 14 files | n/a | ❌ has uncommitted changes |

Column definitions:

- **Dirty**: `✅ clean` or `⚠️ N files`
- **Merged**: `✅ merged` / `✅ squash-merged` (confirmed via content diff) / `❌ not merged` / `n/a`
- **Can clean?**: `✅` only when merged (or squash-merged) AND clean

Add extra columns (e.g. tmux session, notes) only when relevant.

### 6. Cleanup (only when asked)

Only clean worktrees the user explicitly approves. For each:

```bash
NAME="<worktree-name>"
git worktree remove "/path/to/$NAME"
git branch -D "<branch>"  # only if the branch is no longer needed
```