Free up disk space on macOS by clearing regenerable caches only: Homebrew, npm, pip, Go, Google Chrome caches, macOS wallpaper payloads, optional Docker / Xcode junk—and not your passwords, bookmarks, or extension code.

Search hits: disk space, storage full, clear cache mac, free space macOS, Homebrew cleanup, Chrome cache mac, Go modcache, DerivedData, Docker prune, Claude vm_bundles.

• Why this repo
• Quick start
• What it cleans (by profile)
• The algorithm
• Optional: GitHub CLI login helper
• Repository layout
• Suggested GitHub topics
• Disclaimer

macOS “System Data” and developer tooling can grow for years. This project is a documented, reviewable Bash tool that:

• prefers vendor commands (brew, go clean, docker) where possible;
• applies explicit invariants (only delete what can be rebuilt);
• supports --dry-run so you can see intent before deleting anything.

git clone https://github.com/ianalloway/macos-disk-cleanup.git
cd macos-disk-cleanup
chmod +x bin/macos-disk-cleanup bin/gh-auth

# Always preview first
./bin/macos-disk-cleanup --dry-run

# Then run (default profile)
./bin/macos-disk-cleanup

Install on your PATH (optional):

ln -sf "$(pwd)/bin/macos-disk-cleanup" /usr/local/bin/macos-disk-cleanup
# or: mkdir -p ~/bin && ln -sf "$(pwd)/bin/macos-disk-cleanup" ~/bin/

Flags: --dry-run, --minimal, --full, -h.

The full specification (invariants I1–I4, phases P1–P11, profiles) lives in the header of bin/macos-disk-cleanup. Read that block before extending paths or adding new delete rules.

bin/gh-auth wraps gh auth for local browser login (credentials stay in Keychain / gh config).

./bin/gh-auth login
./bin/gh-auth setup-git   # optional: gh as git credential helper
./bin/gh-auth status

Requires: brew install gh — GitHub CLI.

macos-disk-cleanup/
├── bin/
│   ├── macos-disk-cleanup   # main cleanup CLI + documented algorithm
│   └── gh-auth              # optional GitHub CLI auth helper
├── .github/
│   └── workflows/
│       └── ci.yml           # ShellCheck on push/PR
├── LICENSE                  # MIT
└── README.md

Add these in Repository → ⚙ Settings → General → Topics to improve discovery:

macos · bash · shell · disk-space · storage · cache · homebrew · google-chrome · golang · docker · xcode · cleanup · cli · automation

Software is provided as-is under the MIT License. You are responsible for backups and for understanding what gets deleted. Preview with --dry-run. This is not affiliated with Apple, Google, Anthropic, or GitHub.