uncruft

sweep the cruft, reclaim your disk

Interactive Linux space recovery tool. Find what's eating your disk, preview what's safe to delete, clean with confidence.

  ██╗   ██╗███╗  ██╗ ██████╗██████╗ ██╗   ██╗███████╗████████╗
  ██║   ██║████╗ ██║██╔════╝██╔══██╗██║   ██║██╔════╝╚══██╔══╝
  ██║   ██║██╔██╗██║██║     ██████╔╝██║   ██║█████╗     ██║
  ██║   ██║██║╚████║██║     ██╔══██╗██║   ██║██╔══╝     ██║
  ╚██████╔╝██║ ╚███║╚██████╗██║  ██║╚██████╔╝██║        ██║
   ╚═════╝ ╚═╝  ╚══╝ ╚═════╝╚═╝  ╚═╝ ╚═════╝╚═╝        ╚═╝

Install

npm install -g uncruft

Usage

uncruft

Launches an interactive TUI. Type / to see all available commands.

Commands

| Command | Description | |---|---| | /scan | Scan known hotspots for space usage | | /scan large-files [size] | Find big files in home (default >100MB, e.g. /scan large-files 500m) | | /scan node_modules [path] [depth] | Find node_modules under a path (default ~, depth 4) | | /scan docker | Inspect Docker images, containers, volumes, build cache | | /details [id] | Show exactly what will be deleted and what is preserved | | /select [id\|all\|none] | Toggle a category for batch cleaning | | /clean [id] | Preview and clean a category | | /clean all | Preview and clean all selected categories | | /reserved | Analyze filesystem reserved space (advanced) | | /clear | Clear the screen and output | | /info | About uncruft and the developer | | /help | Show all commands | | /exit | Quit |

Interaction

After a scan the results list is focused — drive it with the keyboard:

| Key | Action | |---|---| | ↑ / ↓ | Move the highlight | | space | Select / deselect the highlighted item | | a | Select / deselect all | | d | Toggle inline details (what gets deleted) | | Enter | Clean / delete the selection (always previewed first) | | / | Jump to the command bar | | Esc | Return from the command bar to the list |

In the command bar, ↑ recalls previous commands and Tab completes the highlighted suggestion. Running containers in /scan docker are shown read-only and can't be selected.

What it scans

| Category | What | |---|---| | Dev | npm cache, pip cache, Gradle build cache, Maven repository, node_modules | | IDE | VS Code (cache, workspace storage), JetBrains (all IDEs), Android emulator snapshots, Android SDK system images | | System | apt package cache, system journal logs, snap cache, crash reports, temp files, thumbnails | | Browser | Chrome, Chromium, Firefox (cache only — bookmarks/passwords untouched) | | Docker | Unused images, stopped containers, unused volumes, build cache | | Large Files | On-demand scan for big files anywhere in home | | node_modules | On-demand scan for project dependency folders under a path |

Safety

• Every clean operation shows a preview before deleting anything
• Categorized as safe (regenerates automatically) or ⚠ review (manual verification recommended)
• Large files, node_modules, and Docker items are permanent deletes — clearly flagged "not recoverable" in the preview
• Items that need sudo are clearly flagged
• Bookmarks, passwords, extensions, source code — never touched

Requirements

• Linux (tested on Ubuntu 22.04 / 24.04)
• Node.js 18.20+

Developer

M. Yousuf — yousuf-dev.com · LinkedIn · GitHub

License

MIT