Skip to content
psicomantePublic

About

Find and clean developer clutter on macOS. Beta Quality.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

hanky

Find and clean developer clutter on macOS: package manager caches, old toolchains, stale project build artifacts and app caches. Every item comes with its size, when it was last used and how safe it is to remove, and nothing is touched until you have reviewed the list.

hanky scans the Mac, the user picks stale projects, reviews the list and cleans 21.8 GB

Recorded on a fake home folder.

Features

  • One scan for many tools: npm, Yarn, pnpm, Bun, n, Homebrew, pip, uv, pyenv, Cargo, rustup, Go, Docker, Xcode, browser and editor caches, coding agent scratch folders.
  • Stale projects: walks your home folder for node_modules, Cargo target and Python virtualenvs, showing when each project was last touched.
  • Native commands first: uses the tool's own cleanup (npm cache clean, brew cleanup, go clean, cargo clean, docker ... prune) and moves everything else to the Trash.
  • Safety levels: safe (regenerable cache), caution (costly to download or rebuild) and risky (may lose data or app state; you type yes to confirm). Only safe items start selected.
  • Guard rails: a last check before any removal refuses system folders, your home folder and its top-level folders, and anything inside ~/.ssh, ~/.gnupg, Keychains, Mail, Messages or iCloud Drive, also when reached through a symlink. Running apps are asked to quit before their caches go, and sudo is requested per item.
  • Extensible: add path-based targets as TOML rule files.

What hanky never does

  • Delete your files outright: an item goes through its tool's own cleanup command or into the Trash.
  • Empty the Trash, so anything moved there can be put back until you empty it yourself.
  • Remove something you haven't reviewed: caution and risky items start unselected, and a risky item needs a typed yes.
  • Touch a path outside what it reported.
  • Need to be started with sudo: it asks for root per item, only for a tool's own command, and never moves files to the Trash as root.

Install

macOS 15 or later, on Apple Silicon or Intel.

With Homebrew:

brew install psicomante/tap/hanky

Or build it with Rust 1.88 or later. Every commit on main is a release, so this installs the latest one:

cargo install --git https://github.com/psicomante/hanky --locked hanky-cli

That puts hanky in ~/.cargo/bin; make sure that folder is on your PATH. To build a checkout instead, run cargo install --path crates/hanky-cli --locked in it. hanky --version prints the version it was built from.

Usage

hanky scan       # report only, changes nothing
hanky            # pick items in a checklist, review, then clean
hanky targets    # list known targets and whether they are installed

hanky scan is the dry run: it shows everything hanky would offer and changes nothing.

Option Effect
--only js,rust,... Only these categories: js, homebrew, python, rust, go, docker, xcode, apps, system, projects, downloads
--no-home-scan Skip walking the home folder for project artifacts
--use-cache Show the last scan instead of scanning again (about 12 s on a full Mac); targets it lacks are scanned. Before cleaning, the selected targets are scanned again. Without it, every run scans everything and saves the results to ~/.cache/hanky/scan.json
-v, --verbose scan only: list every path, including unreadable ones

Checklist keys: ↑↓, j k, the mouse wheel or the trackpad move · space toggle (a category or tool toggles all its items) · enter or ← → expand and collapse · a toggle all · s sort by size, last used or scan order · c continue to review · q quit without changes.

Review keys: ↑↓ or the wheel scroll · y or enter clean · b back. With a risky item selected, type yes to confirm (esc goes back).

While the checklist or the review is on screen, the terminal sends mouse events to hanky, so selecting text needs a modifier key (Option in iTerm2).

Some app data lives in sandboxed containers (Teams, Slack from the App Store). To include it, give your terminal Full Disk Access in System Settings › Privacy & Security.

What it cleans

Category Items
JavaScript npm, Yarn, pnpm and Bun caches; Node versions installed with n (keeps the active one)
Homebrew download cache and old versions
Python pip and uv caches, uv-managed Pythons and pyenv versions (keeps the active ones); Hugging Face models and datasets, one per repo (blobs shared with another repo are kept)
Rust Cargo registry and git caches, rustup toolchains (keeps default and active)
Go build and module caches
Docker stopped containers, build cache, dangling and unused images, unused volumes (Docker must be running)
Xcode DerivedData, simulator caches, unavailable simulators, runtimes not matching the installed SDK, DeviceSupport, Archives
Apps Chrome, Firefox, Teams, Slack, Discord, VS Code, Cursor, Spotify, Claude and Unity caches; PlatformIO packages (pio system prune, or the folders when pio does not run); Claude Code scratch folders; opencode temp files, undo snapshots, logs and downloaded tools
System other app caches in ~/Library/Caches and other folders in ~/.cache (50 MB or more each), app logs (10 MB or more)
Projects node_modules, Cargo target and Python virtualenvs anywhere in your home folder
Downloads files and folders in ~/Downloads of 50 MB or more, labelled by kind and the site they came from; only unfinished downloads start selected

Custom rules

A folder that only needs "move these paths to the Trash" can be described in a TOML file in ~/.config/hanky/rules/ (or $XDG_CONFIG_HOME/hanky/rules/). A rule with the same id as a built-in one replaces it.

id = "zoom"
name = "Zoom"
category = "apps"

# Installed when any of these exists (default: when any item path exists).
[detect]
any_path = ["/Applications/zoom.us.app"]

# Ask to quit the app before cleaning.
[app]
bundle_id = "us.zoom.xos"

[[items]]
label = "logs"
paths = ["~/Library/Logs/zoom.us"]
safety = "safe"

Caution and risky items can say why in reason = "…", shown next to the safety level. Items also accept globs, exclude, per_match = true (one item per matched path), min_bytes and app_from_name. Paths must be absolute or start with ~/. A file that fails to parse is skipped with a warning.

Development

Common commands are in the justfile (just lists them):

just scan --only docker   # run `hanky scan` from this checkout
just clean                # the interactive clean from this checkout (release build)
just check                # tests, clippy and format check
just install              # install the CLI to ~/.cargo/bin (same as `cargo inst`)
just version              # the build version of this checkout, e.g. v0.1.0-nightly.3+abc1234

Releases are git tags vX.Y.Z. Every build stamps its version from the checkout: the tag, a nightly after it, dev+<hash> with no tag, dirty with uncommitted changes.

Planned next: hanky doctor (checks that detected tools still work) and a config file for exclusions.

Changes are welcome; CONTRIBUTING.md explains how one gets in. To report a security problem, see SECURITY.md.

Licence

MIT, see LICENSE. hanky comes with no warranty: it removes files, so read the review before you clean.

About

Find and clean developer clutter on macOS. Beta Quality.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages