Home / mac-maintenance

Mac Maintenance

Mac cleanup skills: survey what takes space and memory without changing anything, remove only the caches and leftovers that programs recreate, find byte-identical duplicate files and park the obvious copies in the Trash, and find data, login items and launch agents left by uninstalled apps. Every deletion of user data is a decision the user makes from a written list.

Plugin mac-maintenance, version 0.2.0, 3 skills, MIT licence. Source: mac-maintenance-skills. Synced .

Install

In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add basitalisandhu/claude-skills
/plugin install mac-maintenance@claude-skills

Or copy the skill files into ~/.claude/skills/ from a clone:

git clone https://github.com/basitalisandhu/claude-skills
cd claude-skills
python3 install.py --user --only mac-maintenance

Skills

SkillWhat it doesScripts
mac-app-leftoversFind what uninstalled apps left behind on a Mac (Application Support and container folders, caches, preferences, saved state, logs, and login items or launch agents that point at nothing), deciding what is installed from app bundles, PATH, Homebrew and Spotlight, and move only the candidates you name into a dated Trash folder.yes
mac-cleanupFree disk space and speed up a Mac safely: survey it read-only, clear only what programs recreate (npm, Xcode and other package and build caches, Docker build cache, old logs), and write a decision list for everything else.yes
mac-duplicate-finderFind byte-for-byte duplicate files in a Mac's user folders, report the largest groups and folders that mirror each other, and move verified suffix copies, the (1) copies of videos and photos (IMG_1 (1).MOV next to an identical IMG_1.MOV), to a dated Trash folder after a second hash check.yes

Plugin README

Mac maintenance skills for Claude Code: a survey that only measures, a safe tier that removes only the caches programs recreate, and a written list for every decision that is yours. For people whose Mac has filled up with build caches, duplicate phone exports, leftovers of uninstalled apps and a few gigabytes pinned in memory, and who do not want a cleaner that guesses.

Install with /plugin marketplace add basitalisandhu/mac-maintenance-skills and then /plugin install mac-maintenance@mac-maintenance-skills, or add it from Anthropic's directory. Skills appear as /mac-maintenance:<skill>, and Claude also invokes them on its own when a request matches a skill's description. Ask "look at my Mac and clean up the garbage" to start.

Use it when "System Data is huge" in Storage settings (the survey shows the caches, Docker and developer folders that usually make it up), or when Docker.raw has grown (the survey reports its size on disk, and the safe tier prunes Docker build cache). Time Machine local snapshots are not measured or removed by these skills; tmutil listlocalsnapshots / lists them.

Skills

SkillScriptUse it to
mac-cleanupskills/mac-cleanup/scripts/mac_survey.py, skills/mac-cleanup/scripts/safe_clean.pysurvey what takes space and memory without changing anything, then remove only the caches and leftovers programs recreate (dry run by default), then write the decision list for everything else
mac-duplicate-finderskills/mac-duplicate-finder/scripts/find_dupes.pyfind byte-identical files in the user folders, see which folders mirror each other, and move verified " (1)" copies to a dated Trash folder
mac-app-leftoversskills/mac-app-leftovers/scripts/app_leftovers.pylist data, preferences, login items and launch agents left by uninstalled apps, and move the ones the user names to a dated Trash folder

How it treats your Mac

What the scripts run

The survey (mac_survey.py) is read-only. It runs du -sk, docker system df, docker volume ls, docker buildx ls, brew cleanup -n, brew outdated, brew list, brew uses, brew services list, mdls (Spotlight last-used dates of apps), ps, sysctl, uptime, and one osascript call to System Events to read login items. It writes a report only where you pass --out.

The cleaner (safe_clean.py) prints a plan by default. With --apply it removes these locations and runs these commands, each only when its condition holds: ~/.npm/_cacache (unless npm is installing), stale ~/.npm/_npx entries, ~/Library/Caches/go-build, uv cache prune, pip3 cache purge, brew cleanup --prune=all -s, docker builder prune -af, docker image prune -f (dangling images), docker volume prune -f (anonymous unused volumes), docker volume rm of buildx state volumes whose builder no longer exists, Docker Desktop update downloads under Application Support and the temp folder (after hdiutil detach of a mounted installer image), ~/Library/Caches/*-updater folders, ~/Library/Developer/Xcode/DerivedData (unless Xcode is running), xcrun simctl delete unavailable, files in ~/Library/Logs older than seven days, ~/Library/Caches/Google/Chrome/*/Cache (unless Chrome is running), and osascript to delete login items whose app no longer exists. It refuses symbolic links and any path outside your home and temp folders. safe_clean.py --list-actions prints each action id with what it removes and when it is skipped, for choosing --only and --skip.

The duplicate finder (find_dupes.py) reads files to hash them and moves files only with --trash-suffix-copies. The leftover finder (app_leftovers.py) runs du -sk, mdfind and one osascript call, reads brew list, and moves entries only with --trash.

Where it works

The scripts need to run on the Mac being cleaned, so use the skills from Claude Code on that machine (the terminal, an IDE extension or the desktop app's Code tab). In claude.ai chat and Cowork the skill text loads but the scripts cannot reach your Mac's file system. Requirements: macOS with Python 3.11 or newer on PATH as python3. No third-party packages. Optional tools (docker, brew, uv, pip3, xcrun, mdls, osascript) are used when present and reported as unverified when not.

Licence

MIT. See LICENSE. Privacy: PRIVACY.md (nothing is collected or sent). Source, tests and issues: github.com/basitalisandhu/mac-maintenance-skills.