Find your next open-source project

Search by name, purpose, or keyword — or paste a GitHub repository URL

govijr/fix-storage

System Tools

A terminal tool for macOS and Linux that finds what is filling your disk and safely clears caches, junk and unused files.

178
14
TypeScript
MIT
6 days old

What it does

fix-storage scans a macOS or Linux disk the way Finder's storage panel does, then goes further: it drills into the largest subfolder to show where space is actually going, labels items as junk, unused, system or unlabelled, and attaches a short reason such as "rebuilds with npm install" or "not touched in 7 months". Last-opened dates come from Spotlight on macOS and file access times on Linux.

The interactive view is keyboard-driven and renders through the kitty graphics protocol; terminals without it fall back to a character-only view. On Linux, each mounted filesystem is treated as one drive, dual-boot Windows partitions and other Linux installs are shown read-only, and unmounted partitions can be listed for mounting read-only.

Install

The recommended install downloads and pipes a shell script into sh:

curl -fsSL https://raw.githubusercontent.com/govijr/fix-storage/main/install.sh | sh

The script places the app in ~/.fix-storage and links the fix-storage command into ~/.local/bin, without sudo. A specific version can be requested with sh -s -- --version 0.2.0.

Requirements: macOS (Apple silicon or Intel) or Linux (x86_64 or arm64), Node.js 20.11 or newer, and on Linux unzip for the Electron-based graphics runtime. The graphical view needs a terminal supporting the kitty graphics protocol, such as Ghostty, kitty or WezTerm; on a bare server use --plain.

Run it

After installation, fix-storage scans the disk and opens the interactive view. Useful starting points:

fix-storage --demo       # a made-up disk, reads and deletes nothing
fix-storage --dry-run    # real scan, deleting only pretends
fix-storage --plain      # text summary and exit
fix-storage --json       # summary as JSON and exit
fix-storage --drives     # Linux: list mounted drives and unmounted partitions

Inside the interface, arrow keys or j/k move, →/Enter opens a folder, g jumps to the culprit, f filters to junk and unused items, and d/⌫ moves an item to the Trash; clearing caches or the Trash requires a second keypress. Every element is also clickable.

On macOS, grant the terminal Full Disk Access so protected folders such as Mail and Safari are counted correctly; otherwise their contents are lumped into System data. On Linux, run as your normal user rather than with sudo, for the same reason.

Deletion behaviour and limits

Caches and Trash items are deleted permanently; everything else goes to the system Trash so it can be restored, and the space returns only after emptying the Trash. System data, /System, /private, Keychains, Preferences, Mail, Messages, Photos, Safari data, the top-level measured folders and anything outside them are never removed. On Linux, /usr, /etc, /var, /opt, /boot, Flatpak's own folders, active swap files, ~/.ssh, ~/.gnupg, keyrings, browser profiles and items on Windows or other-OS partitions are also excluded. --dry-run and --demo never modify the disk. The classification rules are deliberately conservative and live in src/core/classify.ts; the project is MIT-licensed.

HotRepo's take

HotRepo recorded the repository on the TypeScript new-project list for 2026-11-20, at 178 stars with 50 gained across a 24-hour window ending that day. The hourly samples show the count rising from 103 to 178 between 2026-11-16 and 2026-11-20, with most of that gain concentrated on the final day. There is no all-language daily rank recorded and no Hacker News discussion to draw on, so the ranking is the only popularity signal available. What stands out technically is the breadth of the safety model: explicit never-delete lists, a dry-run mode, and a demo disk make a destructive terminal tool plausible to evaluate before pointing it at real data.

Written by AI from the project's README, updated . The project's own docs are the source of truth.