cleanup

name

cleanup

description

Tear down the ephemeral dev artifacts an agent session created in the Rabbithole repo — stop background dev servers, delete throwaway test users / secrets from the shared dev deployment, remove scratch files, and (on request) remove the git worktree + merged branches and delete that worktree's own private dev deployment. Use when the user says "clean up", "cleanup", "teardown", "tear it down", "clean up after yourself", or when wrapping up a worktree session. NEVER touches production.

Cleanup

Almost all of cleanup is now ONE deterministic script — scripts/worktree-down.sh (the inverse of worktree-up.sh), run via pnpm worktree:down. It does the mechanical, token-heavy work (find/stop this worktree's dev servers, capture the deployment slug, remove the worktree + merged branch, delete the private dev deployment) in a single call, with every safety guard enforced in code rather than as prose you have to follow by hand. Don't re-derive these steps with individual shell commands — call the script.

🚫 Safety (the script enforces all of this)

• NEVER touches production (fantastic-dotterel-572), the shared default dev (perceptive-husky-735), or the dedicated Slack-bot debug dev (nautical-wolf-687 — the Rabbithole Dev Slack app's permanent request URL; see rabbithole-slack-bot.md). Cleanup is dev-only.
• Only stops dev servers belonging to THIS worktree — never master's port 1041, never another worktree's server (matched by this worktree's persisted PORT / cwd).
• Only deletes THIS worktree's own private dev deployment, and refuses if the slug is empty, protected, local/anonymous, or still referenced by another live worktree.
• Never deletes master, nor an unmerged branch (without --force-branch).

All paths are derived from git, so it works regardless of worktree layout (.claude/worktrees/…, copilot-worktrees/…, …).

The flow

1. Run the safe pass (always) — stops servers + reports the plan

pnpm worktree:down

This stops this worktree's dev servers, reports any untracked scratch files, and prints the teardown plan (which worktree / branch / deployment a full teardown would remove, and whether the branch is merged). Nothing destructive happens. Read the output — it's the whole picture in one shot.

2. Remove leftover scratch (judgment — only if NOT doing a full teardown)

If you're keeping the worktree but tidying up, delete any throwaway files the script listed under "Untracked scratch files" that you created this session (ad-hoc rt_*.mjs, fetch_*.mjs, screenshots, /tmp/*-shots, …). Never delete tracked files. If you're doing the full teardown in step 3, skip this — the files vanish with the worktree.

3. Tear down the worktree (CONFIRM FIRST — destructive)

Only when the user wants the worktree gone. Confirm with them, then:

pnpm worktree:down --yes

This removes the worktree, deletes the merged branch (local + remote), and deletes the worktree's private dev deployment — no further confirmation needed between those sub-steps (they're one teardown). Useful flags:

• --keep-deployment — remove the worktree/branch but keep the dev deployment.
• --keep-remote — don't delete the remote branch.
• --force-branch — tear down even though the branch isn't merged (discards it).

If the branch isn't merged, the script refuses by default (so you don't strand work) and tells you to ship/merge first or pass --force-branch. A trailing shell getcwd/uv_cwd warning after teardown is expected and harmless — you were standing in the directory that just got removed.

Working against the SHARED dev deployment? (rare, judgment)

The above covers worktree sessions, where test users / DEV_TEST_LOGIN_SECRET live on the worktree's private deployment and die with it. If THIS session instead created throwaway data directly on the shared dev (perceptive-husky-735) — e.g. you ran from the master checkout — clean only what this session made:

# throwaway test users this session created (rtcheck*/sweep*/test-*/qa-*):
CONVEX_DEPLOYMENT=dev:perceptive-husky-735 npx convex run users:internalListUsers '{}' \
  | grep -iE "rtcheck|sweep|test-|qa-"
CONVEX_DEPLOYMENT=dev:perceptive-husky-735 npx convex run users:internalDeleteUser '{"userId":"<id>"}'

When unsure whether something is yours, list it and ask — don't guess-delete real-looking data.

Pruning OTHER sessions' orphan deployments (separate, opt-in chore)

pnpm worktree:down only deletes this worktree's deployment. Cleaning the backlog of orphans left by past sessions is a different, explicitly-requested task. Use pnpm worktrees:gc for the safe dry-run sweep across BOTH worktree trees (.claude/worktrees/ + Copilot CLI worktrees); add --yes only when intentionally removing stale merged-PR worktrees and orphan dev deployments. See .claude/rules/rabbithole-deployment-cleanup.md.

Finish

Report a short checklist of what was cleaned (servers stopped, scratch removed, worktree + branch torn down, this worktree's private deployment deleted) and what was intentionally left (e.g. other sessions' orphan deployments), so the user can see the session is tidy.