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.
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
| Skill | What it does | Scripts |
|---|---|---|
| mac-app-leftovers | Find 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-cleanup | Free 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-finder | Find 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
| Skill | Script | Use it to |
|---|---|---|
mac-cleanup | skills/mac-cleanup/scripts/mac_survey.py, skills/mac-cleanup/scripts/safe_clean.py | survey 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-finder | skills/mac-duplicate-finder/scripts/find_dupes.py | find 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-leftovers | skills/mac-app-leftovers/scripts/app_leftovers.py | list 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
- Nothing of yours is deleted. The cleaner removes only the cache and leftover locations listed below, and only when you pass
--apply. Duplicate files and app leftovers are moved into a dated folder under~/.Trashwith their relative paths kept, so Finder can put them back, and only after you say which ones. - Every size is measured, by
duor file metadata, and anything a tool could not check is reported as unverified rather than estimated. - No network, no telemetry, no sudo. Nothing leaves the machine. Launch daemons that need administrator rights are listed with the command for you to run yourself.
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.