| name | clean-vm |
| description | Safely clean the local loop VM by reporting and removing stale loop runs, inactive Next.js or Storybook servers, optional browser windows, and unused loop-created worktrees without disturbing active tmux-backed sessions. |
Clean VM
Use this skill when repeated loop, Claude, or Codex runs leave the machine in a bad state.
Start with the bundled script. It does a dry run by default and only mutates the machine with --apply.
Default Workflow
- Run a dry run first:
python3 .agents/skills/clean-vm/scripts/clean_vm.py
- Review the report. The script only targets:
- loop manifests under
~/.loop/runs/<repoId>
- direct
loop __bridge-mcp <runDir> <claude|codex> processes for stale runs
- loop helper processes tied to stale run dirs
- Next.js and Storybook servers running inside stale loop worktrees
- loop-created worktrees from
git worktree list --porcelain
- Apply the cleanup once the plan looks safe:
python3 .agents/skills/clean-vm/scripts/clean_vm.py --apply
- Only close browser windows when the user explicitly wants browser cleanup:
python3 .agents/skills/clean-vm/scripts/clean_vm.py --apply --browsers
Safety Rules
- Always inspect the dry run before using
--apply.
- Treat loop manifests in
~/.loop/runs as the source of truth for paired runs.
- Keep any run whose manifest state is
submitted, working, reviewing, or input-required and whose pid or tmuxSession is still live.
- Never mass-kill
claude, codex, or node. Kill only per PID after the script proves the process belongs to stale loop state.
- Never remove the main worktree, the worktree containing the current
pwd, or a dirty worktree.
- The script does not auto-force worktree removal. If a plain
git worktree remove fails, it reports the failure and leaves escalation to a manual follow-up.
- Treat any live tmux session as in use even if the manifest looks stale.
- Browser cleanup is opt-in and macOS-only.
What the Script Checks
- repo identity via
git rev-parse --git-common-dir, using the same repo id scheme as loop
- run manifests under
~/.loop/runs
- tmux liveness with exact session targets like
tmux has-session -t =<name> plus a live-pane check from tmux list-panes
- helper processes whose command line references a stale run dir
- direct loop bridge MCP server processes whose run dir is stale or orphaned
- dev servers matching
next dev, next-server, storybook, or start-storybook
- worktrees from
git worktree list --porcelain
Manual Fallback
If the script cannot classify something safely, leave it alone and inspect it manually:
tmux ls 2>/dev/null
tmux list-panes -a -F '#{session_name} #{pane_dead} #{pane_current_command} #{pane_current_path}' 2>/dev/null
git worktree list --porcelain
lsof -nP -iTCP -sTCP:LISTEN | grep -E 'next|storybook|node'
ps -axo pid=,tty=,command= | grep -E 'claude|codex|next dev|storybook'
Useful loop states:
- active:
submitted, working, reviewing, input-required
- inactive:
completed, failed, stopped
If a manifest claims to be active but its pid is gone and its exact tmux session is missing or every pane in that exact session is dead, treat it as stale.
Report
End with a short cleanup report that includes:
- processes killed, with PID and reason
- dev servers stopped, with cwd and reason
- browser actions taken or skipped
- worktrees pruned or removed
- anything suspicious you left alone because it was active, dirty, or ambiguous
If any item is ambiguous, prefer skipped over cleaned.
