mac-cleanup-process
Skill14 starsChanged 6 months agoMITView on GitHub
Scan macOS for zombie/stuck processes (orphan MCP servers, leftover Docker cagent, long-running dev servers, old claude sessions, long-lived terminal tabs, large memory over-age) and produce a tiered diagnostic report + suggested kill commands. Trigger words "cleanup zombies", "scan zombies", "system cleanup", "check mcp orphans", "kill stuck processes", "清理僵尸进程", "系统清理", "MCP 孤儿", "kernel_task 高", "内存高", "系统卡", "扫僵尸", "清进程", "清卡死进程". The skill itself never kills — diagnosis + suggestion only. Sister skill mac-cleanup-disk (disk cache cleanup, never touches processes).
In this repository14 other files it gives its agents.
- app-icon-generatorSkill
- break-itSkill
- debug-modeSkill
- dev-launcherSkill
- diagram-proSkill
- image-uploadSkill
- localizeSkill
- mac-app-uninstallSkill
- mac-cleanup-diskSkill
- mac-cleanup-memorySkill
- macos-app-scaffoldSkill
- npm-safetySkill
- root-causeSkill
- skill-scanSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
Never: add candidates from your own ps | grep that the script didn't surface
- Distinctive: line 29
If the script outputs "🎉 no zombies found", just report all-clear and stop
- Distinctive: line 45
After an actual kill:
- Distinctive: line 62
Claude must not kill on its own initiative: Only act when the user has explicitly stated PIDs, said "one-click cleanup", or said "run …
- Very specific: line 63
Claude must not modify the factual data emitted by scan.sh: All PIDs / etime / commands / numbers in the report come strictly from the …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
mac-cleanup-process
A skill for diagnosing macOS zombie processes — pure diagnostic mode. Never proactively kills any process.
Execution Flow After Trigger
Step 1: Run the scan script
bash "${CLAUDE_SKILL_DIR}/scan.sh"The script:
- Prints a full Markdown report to stdout
- Tees it to
~/Downloads/mac-cleanup-process-<timestamp>.md - Exits 0 on success, 1 on failure with diagnostics to stderr
Step 2: Present the report
Paste the stdout Markdown content to the user verbatim. A line or two of contextual observation is OK (e.g. pointing out the "most suspicious"), but:
- Never modify / fabricate / omit factual data in the report (PID, etime, command)
- Never add candidates from your own
ps | grepthat the script didn't surface - If the script outputs "🎉 no zombies found", just report all-clear and stop
Step 3: Wait for user instruction
Handle per this table:
| User reply | Claude action | Second confirmation? |
| No reply / "ok" / "got it" | Do nothing | - |
| "run explicit-orphan cleanup" / "one-click cleanup" | Run all kill commands from the "Explicit Orphans" section of the suggested-commands block | No (the report already labels these as "safe to nuke") |
kill <PID1> <PID2> (space or comma separated) | Kill each one; skip and continue if a PID is missing | No |
| "clean everything" / "clean all suspicious" or other vague instructions | Ask back: "Do you mean including these suspicious items [list]?" | Yes |
| "dry run" / "look only" | Reiterate "the skill is diagnostic-only by design" | - |
Step 4: Post-kill verification
After an actual kill:
sleep 2to let the kernel reapps -p <PID>to confirm the target has exited- Brief report (before/after memory comparison, cite
vm_stat's compressor number) - Don't auto-rescan (the user will say so if they want another scan)
Step 5: Error handling
| Situation | Action |
scan.sh exits 1 | Paste stderr verbatim, don't patch with your own ps |
| Killed PID no longer exists | Report "PID X has exited (possibly reaped along with the parent you just killed)", continue |
| Kill denied (permissions) | Suggest sudo, but don't sudo on the user's behalf |
| Downloads write fails | Report to the conversation as usual, warn "Not persisted this run: <reason>" |
Core Guards (bolded!)
- Claude must not kill on its own initiative. Only act when the user has explicitly stated PIDs, said "one-click cleanup", or said "run explicit-orphan cleanup".
- Claude must not modify the factual data emitted by scan.sh. All PIDs / etime / commands / numbers in the report come strictly from the script.
- Claude must not kill any PID tagged
[current session — DO NOT KILL], even on explicit user request. Ask back: "Are you sure you want to kill the current conversation process? If you really mean it, please run it manually in your terminal."
Related Files
scan.sh— scan engineDESIGN.md— design docREADME.md— user docs (threshold tuning)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

