agentleFS
lifedeverlifedever/skills-plugin/skills/mac-app-uninstall/SKILL.md

mac-app-uninstall

Skill14 starsChanged 6 months agoMITView on GitHub

Browse installed macOS applications and uninstall any of them together with every leftover they left behind — a scriptable replacement for AppCleaner / CleanMyMac. Also use this to simply LIST what is installed, since choosing what to remove usually starts with browsing the full inventory. Scans ~/Library, /Library, launchd jobs, privileged helpers, system extensions and installer receipts, then tiers each finding into safe / review / shared-do-not-touch before moving anything to the Trash. Trigger words for listing "list installed apps", "list all apps", "list my apps", "what apps do I have", "what's installed", "show installed applications", "app inventory", "installed applications", "which apps are installed", "列出所有应用", "列出所有 app", "列一下我装的软件", "我装了哪些软件", "有哪些应用", "应用列表", "已安装的应用", "看看装了什么", "所有已安装的 app". Trigger words for removal "uninstall app", "remove app", "delete app", "uninstall cleanly", "remove leftovers", "app leftovers", "appcleaner", "app cleaner", "cleanmymac", "get rid of this app", "purge app", "卸载应用", "卸载软件", "删除应用", "删除软件", "彻底卸载", "卸载干净", "干净卸载", "清理残留", "应用残留", "残留文件", "卸载不干净". Everything goes to the Trash and stays recoverable; the skill never runs sudo and never runs rm. Sister skills mac-cleanup-disk (system-wide cache cleanup), mac-cleanup-process (processes).

  • Deletes or force-pushes

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read-only. It writes the table to ~/Downloads/mac-app-uninstall/apps-<ts>.md, opens it in Typora, and prints the path.

    line 72
  2. Very specific:

    Read-only. Writes a Markdown report and a TSV manifest to ~/Downloads/.

    line 110
  3. Distinctive:

    Never: add paths the script did not find (except via step 4, explicitly)

    line 130
  4. Distinctive:

    If there's a 🛑 Blocked section, stop and explain.

    line 140
  5. Very specific:

    Append to the manifest scan.sh wrote: If you ever hand-write one instead (sweeping up several apps' leftovers in one pass, say), the two …

    line 176
  6. Distinctive:

    Always dry run first, even after the user says go:

    line 190
  7. Very specific:

    If it prints ❌ VERIFICATION FAILED, or any MISSING DIRECTORY line, stop immediately and show the user.

    line 214
  8. Very specific:

    If some items were not found there under the same name, that's inconclusive, not loss — Finder renames on collision.

    line 216
  9. Distinctive:

    Never run these. Hand them over:

    line 220
  10. Very specific:

    Trash only: Never rm a user file to "finish the job", never offer a permanent delete, never offer to empty the Trash.

    line 237
  11. Distinctive:

    Never touch the 🚫 shared tier: If the user insists, name the app that owns it and let them do it by hand.

    line 241

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

mac-app-uninstall

Removes a macOS app and its leftovers, the way AppCleaner does — but with the reasoning visible and auditable at every step.

The bottom line: everything goes to the Trash, so any mistake can be undone. There is no permanent-delete path in this skill, by design. Never work around that with your own rm.

Iron rule: identify → scan → show the report → confirm → dry run → execute → verify.

Division of labour

You do the judgement, the scripts do the enforcement:

You (the agent)The scripts
Work out which app the user means — ask, never guessInventory installed apps and enumerate leftovers
Optionally hunt for extra leftovers by name (step 4)Decide ownership when apps nest in each other's namespaces
Explain, summarise, get consentEnforce the path allow-list, Apple/Setapp protection, Trash-only

scan.sh deliberately does no fuzzy matching — it takes an exact bundle id, exact app name, or a path. Guessing is your job, because you can ask a clarifying question and it cannot.

Where output goes

Everything lands under ~/Downloads/mac-app-uninstall/:

apps-<ts>.md              the installed-app inventory
<App>-<ts>/report.md      scan report for one app
<App>-<ts>/manifest.tsv   what uninstall.sh acts on
<App>-<ts>/result.md      what was trashed + verification

One folder per uninstall, so a run's report, manifest and result stay together.

The generated files are written in Chinese and open automatically in Typora (falling back to the system default). Set MAU_NO_OPEN=1 or pass --no-open to suppress opening — do that when running several scans in a row, so the user isn't buried in windows.

0. Pre-flight

/usr/bin/trash ships with macOS 14+. The scripts are pure base-system bash; nothing to install.

mole is optional — mo uninstall --list gives a JSON app inventory with a Homebrew/Setapp/App source field. Never use mo uninstall to remove anything: with an app argument it doesn't list what it will delete and it blocks on a [y/N] prompt, so there is nothing to audit.

1. Identify the app

The user often does not know the app's name, or has not said which one they mean. Never guess, and never narrow the field for them.

If they named something specific, resolve it before scanning:

ls /Applications ~/Applications 2>/dev/null | grep -i "<what they said>"

More than one plausible match? Ask which one.

If they want to see what's installed — "列出所有 app", "what do I have", "我看看有哪些", or anything else short of naming one — show the whole inventory:

bash "${CLAUDE_SKILL_DIR}/list-apps.sh"                  # every app, A–Z
bash "${CLAUDE_SKILL_DIR}/list-apps.sh" --sort used      # by last used, oldest first
bash "${CLAUDE_SKILL_DIR}/list-apps.sh" --sort size      # by size, largest first

Read-only. It writes the table to ~/Downloads/mac-app-uninstall/apps-<ts>.md, opens it in Typora, and prints the path.

Give the user that file path — do not paste the table into chat. A 90-row Markdown table wraps and misaligns in a terminal, and the Bash tool's output is collapsed anyway (… +103 lines). The file renders properly and they can keep it. Say how many apps there are, mention it has opened, and stop.

The table has a 类别 column from LSApplicationCategoryType (~70% of apps declare it; the rest show -). It is a category, not a description — macOS has no per-app description field. Don't present it as one, and don't invent descriptions for the apps that show -.

  • Never --limit. The file holds everything; the user is browsing for an app they may not be able to name. Truncating hides the one they wanted.
  • --size is the .app bundle only — not what uninstalling would free. Never present it as reclaimable space. Computing the real figure for every app means du over ~700 leftover paths (~50s), which is why it isn't offered; the precise number for a single app comes from scan.sh, tier by tier.
  • Never summarise it into "the interesting ones" in place of the path.
  • Do not nominate candidates. Not "these look unused", not "you could remove these". Sorting by last-used is a view, not a recommendation. The user decides what goes; you are the inventory, not the advisor.
  • Only sort by last-used if they ask for it. Alphabetical is the default precisely because it implies nothing.
  • no record means Spotlight has no last-used date — not that the app is unused. Xcode and the Office apps land there on machines where they're in daily use. A date marked ~ is inferred from the preferences file, not a usage record. State this accurately if the column comes up.

Then wait. Act on the app the user names, not the one you would have picked.

2. Scan

bash "${CLAUDE_SKILL_DIR}/scan.sh" "<exact app name | bundle id | /path/to/App.app>"

Read-only. Writes a Markdown report and a TSV manifest to ~/Downloads/.

If it reports not installed, that's fine for leftover-only cleanup — pass the bundle id to sweep up orphans of an app that's already gone. But if you expected it to be installed, you probably passed a name it couldn't match: go back to step 1 rather than trying variations.

3. Present the report

The report goes to ~/Downloads/mac-app-uninstall/<App>-<ts>/report.md (in Chinese, opened in Typora), next to the manifest.

Give the path, and in chat list the ✅ safe paths as a plain bullet list — not as a table, which misaligns in a terminal:

- ~/Library/Application Support/com.foo.bar   (7.6 MB)
- ~/Library/Caches/com.foo.bar                (18.9 MB)

Then state the totals: how much the safe tier frees, and whether anything landed in the shared or sudo sections.

The user must be able to see what they are approving. Never ask them to confirm a deletion on the strength of a file they haven't opened — bullets in chat plus the file for detail. If the safe tier is large (say over 25 paths), give counts and the path, and tell them to open the report before confirming.

  • Never move an item between tiers on your own judgement
  • Never add paths the script did not find (except via step 4, explicitly)
  • Never describe the ⚠️ review tier as safe
TierMeaningAction
✅ SafeExact bundle-id match, no other installed app claims itRemovable
⚠️ ReviewBundle-id match, but a second copy of the app is still installedUser confirms each
🚫 SharedBelongs to an app that is still installedNever removable — scripts refuse
🔐 SystemNeeds sudoUser runs it themselves

If there's a 🛑 Blocked section, stop and explain. No manifest was written.

Setapp is conditional. The block exists because the Setapp client reinstalls what disappears behind its back, so both scripts check whether that client is still here — Setapp.app, com.setapp.* LaunchAgents/Daemons, loaded launchd jobs. With none of them present the app under /Applications/Setapp/ is treated as an ordinary app (the report says so), which is what makes cleaning up after a removed Setapp possible at all. If the client is still installed but broken enough that you cannot uninstall from inside it, --allow-setapp on both scripts overrides the block — tell the user Setapp's records will go inconsistent, and only pass it when they have said to.

Blocked becauseTell the user
Apple system appRefused. Removing it can break the OS.
Setapp-managedUninstall from the Setapp client, or it reinstalls. Only blocked while the client is actually installed — see below.
Homebrew caskRecommend brew uninstall --zap --cask <name> first — keeps brew consistent.
App runningAsk them to quit it; a running app rewrites prefs on exit.

4. Optional: hunt for name-based leftovers

scan.sh only matches bundle ids, so files named after the app (crash logs, some support folders) won't appear. If the app is likely to have them, look yourself:

find ~/Library -maxdepth 3 -iname "*<AppName>*" 2>/dev/null | head -40

Judge each hit — most are noise, and a generic name will match things belonging to other apps. For the ones you and the user agree on, append them to the manifest as review rows rather than deleting them by hand:

printf 'REVIEW\t%s\tName match, user confirmed\n' "<path>" >> "<manifest>"

They then go through every safety gate like anything else. Deleting them yourself with trash would bypass the allow-list and the Apple/Setapp protection.

Append to the manifest scan.sh wrote. If you ever hand-write one instead (sweeping up several apps' leftovers in one pass, say), the two header fields are inputs to the scripts, not decoration:

FieldRuleWhy
# bundle_ida real bundle id (com.vendor.app), or literally unknownit identifies the running processes that must be quit first. A placeholder (multi, -, an app title) is rejected by the shape check and the script says so — but only the id form gets you a real running-process check
# appone token, no spacesit is the report title, the output folder name, and the key for ~/.<name> leftovers. SetappLeftoversFinal, not Setapp apps (final leftovers)

Both are TAB-separated: printf '# bundle_id\t%s\n' "com.vendor.app". A header written with spaces instead of tabs parses as empty.

5. Dry run, then execute

Always dry run first, even after the user says go:

bash "${CLAUDE_SKILL_DIR}/uninstall.sh" --manifest "<path>" --tier safe

Then, only after they confirm the target list:

bash "${CLAUDE_SKILL_DIR}/uninstall.sh" --manifest "<path>" --tier safe --execute

--tier takes safe, review, bundle (the .app itself), or all.

Verbal consent is required; silence is not consent. "go ahead" / "删吧" counts. Use review or all only when the user has accepted those items by name.

6. Report the verification

--execute writes result.md into the same folder and ends with a verification block. That block is a few narrow lines, so copy it into your reply verbatim (tool output is collapsed otherwise) — don't just say "done":

  • all N target(s) gone from their original locations
  • all N parent and system directories intact — proof nothing above the targets was touched
  • all N item(s) confirmed in ~/.Trash — recoverable

If it prints ❌ VERIFICATION FAILED, or any MISSING DIRECTORY line, stop immediately and show the user. Do not run anything else, do not retry.

If some items were not found there under the same name, that's inconclusive, not loss — Finder renames on collision. Say so accurately.

7. The sudo tier is the user's job

Never run these. Hand them over:

sudo launchctl bootout system/<label>          # BEFORE deleting the plist
sudo rm /Library/LaunchDaemons/<label>.plist
sudo rm -rf /Library/PrivilegedHelperTools/<label>
sudo pkgutil --forget <receipt-id>

Order matters: bootout before deleting the plist, or launchd keeps the job alive and some apps rewrite the file.

System extensions can't be removed with rm — the app must deactivate them, or the user does it in System Settings → General → Login Items & Extensions.

Anything the report marked 🚫 in this section is shared (Microsoft AutoUpdate serves all of Office); deleting it breaks the other apps.

Core guards

  1. Trash only. Never rm a user file to "finish the job", never offer a permanent delete, never offer to empty the Trash. Recoverability is the entire point.
  2. Never say "above" about tool output — it is collapsed in the UI. Wide tables (the inventory, the report) go to a file: give the path. Narrow content (verification block, a handful of paths) goes in your reply text as bullets. Either way the user must be able to actually see what they are approving; running a command and commenting on it does not count.
  3. Never delete outside the two scripts. The allow-list and Apple/Setapp protection live in uninstall.sh; a hand-written trash command has neither.
  4. Never run sudo, even if asked. Give the command instead.
  5. Never touch the 🚫 shared tier. If the user insists, name the app that owns it and let them do it by hand.
  6. Never present a blocked app's leftovers as removable, even though the scan still lists them for information.
  7. Stop on verification failure. A failed verification means the machine is in an unexpected state; further commands make it harder to diagnose.

Related files

  • list-apps.sh — read-only inventory, written to ~/Downloads/mac-app-uninstall/
  • scan.sh — read-only scanner and tiering engine
  • lib.sh — shared helpers + the app census, sourced by both
  • uninstall.sh — Trash executor, path allow-list, post-delete verification
  • DESIGN.md — why the tiering and the division of labour work this way
  • README.md — user-facing docs

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.