clean-vm

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 .