README.md
September 5, 2026 · View on GitHub
██████╗████████╗ ██████╗ ██████╗ █████╗ ██████╗ ███████╗
██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗██╔══██╗██╔════╝ ██╔════╝
╚█████╗ ██║ ██║ ██║██████╔╝███████║██║ ███╗█████╗
╚═══██╗ ██║ ██║ ██║██╔══██╗██╔══██║██║ ██║██╔══╝
██████╔╝ ██║ ╚██████╔╝██║ ██║██║ ██║╚██████╔╝███████╗
╚═════╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚══════╝
███████╗██╗ ██╗ ██████╗ ██╗ ██╗███████╗██████╗
██╔════╝██║ ██║██╔═══██╗██║ ██║██╔════╝██╔══██╗
╚█████╗ ███████║██║ ██║██║ █╗ ██║█████╗ ██████╔╝
╚═══██╗██╔══██║██║ ██║██║███╗██║██╔══╝ ██╔══██╗
███████║██║ ██║╚██████╔╝╚███╔███╔╝███████╗██║ ██║
╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚══╝╚══╝ ╚══════╝╚═╝ ╚═╝
[ SYSTEM://DISK_MATRIX ]
⟦ JACKING INTO YOUR FILESYSTEM ⟧
A neon-drenched terminal UI for monitoring disk usage
Built in Rust with ratatui + crossterm
created by MenkeTechnologies
brew tap MenkeTechnologies/menketech # one-time
brew install storageshower # via Homebrew tap (recommended)
cargo install storageshower # via crates.io
Read the Docs · Engineering Report
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ >> INITIALIZING FEATURE MATRIX... █
█ >> STATUS: ALL SYSTEMS NOMINAL █
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
> FEATURE_DUMP.exe
[RENDER_ENGINE]
├── Live disk usage display ─── color-coded progress bars
│ ├── gradient ████▓▓▒▒░░
│ ├── solid █████████
│ ├── thin ▬▬▬▬▬▬▬▬▬
│ └── ascii #########
│
[TELEMETRY_CORE]
├── Real-time system stats ─── load avg / memory / CPU
│ ├── swap / process count / uptime
│ ├── network IP / battery / TTY
│ └── background thread @ 3s via Arc<Mutex<>>
│
[ALERT_SUBSYSTEM]
├── Threshold alerts
│ ├── ◈ NOMINAL ── all clear, choomba
│ ├── ⚠ WARNING ── approaching redline
│ └── ✖ CRITICAL ── flatlined
│
[INTERFACE_DECK]
├── Sort ─── name / usage% / size / asc / desc
├── Filter ─── case-insensitive substring match
├── Units ─── human / GiB / MiB / raw bytes
├── Themes ─── 30 builtin + custom user themes (TOML)
├── Theme chooser ─── live preview with mouse click + keyboard nav
├── Theme editor ─── live color picker with per-channel control
└── Persistent config ─── ~/.storageshower.conf (TOML)
│
[DRILL_DOWN]
├── Directory explorer ─── Enter on any mount to drill in
│ ├── recursive size calculation per directory
│ ├── background scanning via Arc<Mutex<>>
│ ├── breadcrumb navigation (Enter/Backspace/Esc)
│ ├── sort by size or name (s/n/r keys)
│ ├── progress bar with item count during scan
│ └── gradient size bars relative to largest entry
│
[NET_LATENCY]
├── Network filesystem latency ─── NFS/SMB/CIFS/SSHFS
│ ├── timed read_dir with 2s timeout (no root needed)
│ ├── color-coded badge: green(<50ms) / warn / red
│ └── detects: nfs, nfs4, cifs, smbfs, afp, ncp, sshfs, rclone, s3fs, 9p, afs
│
[DISK_IO]
├── Live disk I/O throughput ─── per-mount read/write rates
│ ├── macOS: IOKit IOBlockStorageDriver byte counters
│ ├── Linux: /proc/diskstats sector counters
│ ├── auto device→mount mapping via getmntinfo / /proc/mounts
│ └── overlay on bar: ▲1.2M/s ▼500K/s (shown when active)
│
[ALERT_ENGINE]
├── Disk free space alerts ─── threshold crossing detection
│ ├── terminal bell (\x07) on newly crossed thresholds
│ ├── pulsing red border flash for 2 seconds
│ ├── dark red row highlight on alerting disks
│ ├── status bar message: ⚠ ALERT: /mount 90%
│ └── auto-clears when disk drops below threshold
│
[SMART_HEALTH]
├── SMART drive health status ─── per-device monitoring
│ ├── macOS: diskutil info SMART Status (Verified/Failing)
│ ├── Linux: /sys/block/*/device/state
│ ├── ✔ green for healthy, ✘ red for failing
│ └── cached per base device, mapped to all mounts
│
[PLATFORM_COMPAT]
├── macOS ── SUPPORTED
├── Linux ── SUPPORTED
└── auto-detects battery, memory, TTY, local IP
> RENDER_PREVIEW.dat
// DEFAULT_THEME
// GREEN_THEME
// HELP_OVERLAY
> REQUIRED_IMPLANTS.cfg
RUST_VERSION >= 1.85 [2024 edition]
TARGET_OS == macOS || Linux
IMPLANT | PURPOSE |
|---|---|
ratatui | TUI rendering framework |
crossterm | Terminal events + manipulation |
sysinfo | Disk / memory / CPU / proc intel |
clap | CLI argument parsing |
dirs | Home directory detection |
serde | Config serialization |
toml | Config file format |
libc | Unix syscalls (time, TTY) |
> COMPILE_SEQUENCE.sh
# ── JACK IN ──────────────────────────────────
cargo build --release
# LTO enabled ── symbols stripped ── lean binary
# ── BOOT THE MATRIX ─────────────────────────
cargo run --release
# or go direct:
./target/release/storageshower
> CLI_OPTIONS.exe
┌──────────────────────────────────────────────────┐
│ ◈◈◈ COMMAND LINE DECK ◈◈◈ │
└──────────────────────────────────────────────────┘
CLI flags override config file settings. Every --flag has a --no-flag inverse
to force-override in either direction.
// SORTING
FLAG | DESCRIPTION |
|---|---|
-s, --sort MODE | Sort disk entries — name, pct, size |
-R, --reverse / --no-reverse | Reverse sort order |
-l, --local-only / --no-local | Show only local disks (HDD/SSD) |
--no-virtual / --virtual | Hide/show virtual filesystems (tmpfs, devfs, etc.) |
// DISPLAY
FLAG | DESCRIPTION |
|---|---|
-b, --bar-style STYLE | Bar visualization — gradient, solid, thin, ascii |
--color PALETTE | Color palette — 30 builtins: default, green, blue, purple, amber, cyan, red, sakura, matrix, sunset, neon-noir, chrome-heart, blade-runner, void-walker, toxic-waste, cyber-frost, plasma-core, steel-nerve, dark-signal, glitch-pop, holo-shift, night-city, deep-net, laser-grid, quantum-flux, bio-hazard, darkwave, overlock, megacorp, zaibatsu |
--theme NAME | Activate a custom theme by name (defined in config) |
--list-colors | List all builtin color schemes with a swatch preview; each row prints the exact value --color accepts |
--export-theme | Export current palette as TOML (combine with --color or --theme) |
-u, --units MODE | Unit display — human, gib, mib, bytes |
-k, --compact / --no-compact | Compact mount names |
-f, --full-mount / --no-full-mount | Show full mount paths |
--bars / --no-bars | Show/hide usage bars |
--border / --no-border | Show/hide border chrome |
--header / --no-header | Show/hide column headers |
--used / --no-used | Show/hide used/total size display |
--tooltips / --no-tooltips | Show/hide hover tooltips (right-click still works) |
// THRESHOLDS
FLAG | DESCRIPTION |
|---|---|
-w, --warn PCT | Warning threshold (default: 70%) |
-C, --crit PCT | Critical threshold (default: 90%) |
// COLUMNS
FLAG | DESCRIPTION |
|---|---|
--col-mount WIDTH | Mount column width (0 = auto) |
--col-bar-end WIDTH | Bar-end column width (0 = auto) |
--col-pct WIDTH | Percentage column width (0 = auto) |
// SYSTEM
FLAG | DESCRIPTION |
|---|---|
-r, --refresh SECS | Data refresh interval (default: 1s) |
-c, --config PATH | Config file path (default: ~/.storageshower.conf) |
-h, --help | Display help transmission |
-V, --version | Display version information |
// RECLAIM_MAP (build feature: reclaim)
Estimated-reclaimable-space overlay for drill-down. During the scan, each file's
first 64 KiB is sampled and run through a fast compressibility proxy (Shannon
entropy plus a single lz4 block ratio); the estimate is aggregated up the
directory tree in parallel. Every row then gains a second dimension — not just
40 GB, but ~28 GB reclaimable (est. 3.3x) — and a heat overlay ranks subtrees
by recoverable bytes rather than raw size. Whole files are never compressed;
sampling is bounded to the prefix. This is opt-in and pulls in zero extra
dependencies unless built with --features reclaim.
FLAG | DESCRIPTION |
|---|---|
--reclaim | Enable the RECLAIM_MAP overlay at startup (drill-down); in-app, toggle with c |
Build/run with the feature:
cargo build --features reclaim
cargo run --features reclaim -- --reclaim
In drill-down, press c to toggle the overlay live; when on, the reclaim sort
mode ranks entries by estimated recoverable bytes (footer shows sort:reclaim).
// EXAMPLES
storageshower --color purple -b ascii # purple palette with ascii bars
storageshower -s pct -R # sort by usage%, reversed
storageshower -l --no-virtual # local physical disks only
storageshower -u gib -w 60 -C 85 # GiB units, custom thresholds
storageshower --theme neonpink # activate custom theme
storageshower --list-colors # preview all builtin palettes
storageshower --export-theme --color blue # export blue palette as TOML
storageshower --config /tmp/ss.conf # use alternate config
> KEYBIND_MATRIX.dat
┌──────────────────────────────────────────────────┐
│ ◈◈◈ COMMAND INTERFACE ◈◈◈ │
└──────────────────────────────────────────────────┘
// GENERAL_OPS
KEY | ACTION |
|---|---|
q Q | Disconnect — including from inside the help overlay |
h H ? | Open the help HUD (h H Esc j k close it) |
p P | Pause / resume data stream |
Esc | Deselect current disk |
// NAVIGATION
KEY | ACTION |
|---|---|
j Down | Select next disk |
k Up | Select previous disk |
G End | Jump to last disk |
Home Ctrl+g | Jump to first disk |
Ctrl+d | Half-page down (half the visible rows) |
Ctrl+u | Half-page up (half the visible rows) |
// SORT_PROTOCOL
KEY | ACTION |
|---|---|
n N | Sort by mount name (again to reverse) |
u U | Sort by usage % (again to reverse) |
s S | Sort by size (again to reverse) |
r R | Reverse sort vector |
// DISPLAY_MODS
KEY | ACTION |
|---|---|
b | Cycle bar style — gradient / solid / thin / ascii |
c | Theme chooser popup — live preview, mouse click, scroll |
C | Theme editor — live per-channel color picker |
v V | Toggle usage bars |
d D | Toggle used/size columns |
g | Toggle column headers |
x X | Toggle border chrome |
m M | Compact mount names |
w W | Full mount paths |
i I | Cycle units — human / GiB / MiB / bytes |
f F | Cycle refresh rate — 1s / 2s / 5s / 10s |
t | Cycle warn threshold — 50 / 60 / 70 / 80% |
T | Toggle hover tooltips (right-click still works) |
z Z | Cycle crit threshold — 80 / 85 / 90 / 95% |
// FILTER_OPS
KEY | ACTION |
|---|---|
l L | Local disks only |
a A | Show all filesystems (incl. virtual) |
/ | Enter filter mode |
0 | Purge filter |
// FILTER_EDIT_MODE
KEY | ACTION |
|---|---|
Enter | Confirm filter |
Esc | Cancel filter |
Backspace Ctrl+h | Delete char before cursor |
Delete | Delete char at cursor |
Ctrl+w | Delete word backward |
Ctrl+u | Clear line before cursor |
Ctrl+k | Delete to end of line |
Ctrl+a Home | Cursor to start |
Ctrl+e End | Cursor to end |
Ctrl+b Left | Cursor left |
Ctrl+f Right | Cursor right |
// DISK_OPS
KEY | ACTION |
|---|---|
Enter | Drill down into selected mount |
o O | Open selected mount in file manager |
y Y | Copy mount path to clipboard (pbcopy/wl-copy/xclip/xsel, falling back to the OSC 52 terminal escape over ssh) |
e E | Export disk matrix to ~/.storageshower.export.txt |
B | Toggle bookmark (pin to top) |
// DRILL_DOWN_MODE
KEY | ACTION |
|---|---|
j k | Navigate entries |
Enter | Drill into selected directory |
Backspace | Go up one level |
Esc | Return to disk list |
s S | Sort by size (again to reverse) |
n N | Sort by name (again to reverse) |
r R | Reverse sort direction |
c C | Toggle RECLAIM_MAP overlay (est. reclaimable space + sort) — requires the reclaim build feature |
o O | Open current directory in file manager |
y Y | Copy the selected entry's path to clipboard (the listed directory when the listing is empty) |
e E | Export the current listing to ~/.storageshower.drill-export.txt |
g G | Jump to first / last entry |
Home Ctrl+g | Jump to first entry |
End | Jump to last entry |
Ctrl+d | Half-page down (half the visible rows) |
Ctrl+u | Half-page up (half the visible rows) |
Ctrl chords are routed before the plain keys in drill-down, so Ctrl+q does not
quit and Ctrl+c does not toggle the reclaim overlay — same as in the disk list.
// THEME_EDITOR (C)
KEY | ACTION |
|---|---|
j k | Select color channel |
h l | Adjust value ±1 |
H L | Adjust value ±10 |
Enter s | Save (prompts for name) |
Esc q | Cancel |
// MOUSE_INPUT
ACTION | EFFECT |
|---|---|
Left-click disk row | Select disk |
Left-click selected disk | Drill down into mount |
Left-click drill-down entry | Select entry (click again to descend into a directory) |
Left-click column header | Cycle sort on that column |
Left-click theme chooser row | Select and preview theme |
Left-click outside theme popup | Cancel and revert theme |
Left-drag column separator | Resize mount / pct / right columns |
Right-click disk row | Verbose tooltip: capacity, rank, headroom, SMART, I/O |
Right-click drill-down entry | Verbose tooltip: size, rank, share bar, depth, sort |
Hover title segment | Per-segment tooltip: node, date, load, mem, cpu, etc. (auto-hides after 3s) |
Hover footer segment | Per-segment tooltip: sort, theme, units, uptime, etc. (auto-hides after 3s) |
Scroll wheel | Select next/prev disk (or drill-down / theme entry) |
> BENCHMARK_TELEMETRY.dat
┌──────────────────────────────────────────────────┐
│ ◈◈◈ PERFORMANCE MATRIX ◈◈◈ │
└──────────────────────────────────────────────────┘
Measured with Criterion.rs on Apple Silicon (M-series).
// CORE_FORMATTING
BENCHMARK | TIME |
|---|---|
format_bytes (Human, 1 GiB) | ~67 ns |
format_bytes (GiB, 1 GiB) | ~69 ns |
format_bytes (Bytes, zero) | ~20 ns |
format_uptime (45m) | ~21 ns |
format_uptime (2d14h) | ~39 ns |
truncate_mount (w=8) | ~27 ns |
truncate_mount (w=32) | ~97 ns |
// LAYOUT_ENGINE
BENCHMARK | TIME |
|---|---|
mount_col_width | ~590 ps |
right_col_width_static | ~540 ps |
// COLOR_PIPELINE
BENCHMARK | TIME |
|---|---|
palette | ~2.4 ns |
gradient_color_at | ~0.7–1.1 ns |
// TIME_OPS
BENCHMARK | TIME |
|---|---|
epoch_to_local | ~300 ns |
chrono_now | ~427 ns |
// DATA_COLLECTION
BENCHMARK | TIME |
|---|---|
collect_disk_entries | ~3.2 µs |
collect_sys_stats | ~3.8 µs |
// CONFIG_SERDE
BENCHMARK | TIME |
|---|---|
prefs serialize (TOML) | ~4.6 µs |
prefs deserialize (TOML) | ~5.3 µs |
// SORT_DISKS
BENCHMARK | 10 | 50 | 200 |
|---|---|---|---|
by_name | 270 ns | 1.7 µs | 7.9 µs |
by_pct | 242 ns | 1.2 µs | 4.3 µs |
by_size | 250 ns | 1.2 µs | 4.2 µs |
// FILTER_DISKS
BENCHMARK | 10 | 50 | 200 |
|---|---|---|---|
substring_match | 291 ns | 1.6 µs | 5.9 µs |
no_match | 151 ns | 746 ns | 3.0 µs |
// RENDER_PIPELINE
BENCHMARK | TIME |
|---|---|
format_all_disks (10) | ~1.5 µs |
format_all_disks (50) | ~4.4 µs |
format_all_disks (200) | ~15.7 µs |
# ── RUN TESTS ──────────────────────────────────
cargo test
# ── RUN BENCHMARKS ─────────────────────────────
cargo bench
# results in target/criterion/
// CI_PIPELINE
GitHub Actions runs on every push and pull request to main, on merge queue batches (when enabled), and can be run manually via Actions → CI → Run workflow (workflow_dispatch).
| Job | What it runs |
|---|---|
| Check | cargo check --locked --all-targets on Ubuntu and macOS |
| Test | cargo test --locked --lib, then --tests (one integration binary per tests/*.rs), then --doc on Ubuntu and macOS |
| Format | cargo fmt --all --check on Ubuntu |
| Clippy | cargo clippy --locked --all-targets -- -D warnings on Ubuntu |
| Doc | cargo doc --locked --no-deps with RUSTDOCFLAGS=-D warnings on Ubuntu |
The --locked flag fails the job if Cargo.lock is out of sync with Cargo.toml, so CI always resolves the same dependency graph as a fresh clone with a committed lockfile. The lockfile is checked into this repository; if your machine’s global gitignore ignores Cargo.lock, run git add -f Cargo.lock after changing dependencies so updates are not missed.
Concurrent runs for the same branch are cancelled when a newer commit is pushed (concurrency.cancel-in-progress). The workflow uses least-privilege contents: read permissions.
Matrix jobs (Check, Test) use fail-fast: false so a failure on one OS still runs the other. Each job has a wall-clock timeout (30 minutes for build/test/clippy, 10 minutes for format and doc) so hung runners cannot burn minutes indefinitely.
The Test job sets RUST_BACKTRACE=1 so panics print a full stack trace in the Actions log (useful when a test fails only on one OS).
All jobs inherit CARGO_NET_RETRY=2 so Cargo retries failed network fetches (crates.io / git dependencies) when the network or registry is slow.
Disk enumeration (collect_disk_entries) omits rows with an empty mount path so the TUI never shows blank mounts (this also avoids flaky tests on macOS CI when the OS reports odd mount table entries).
To match CI locally before pushing:
cargo fmt --all --check && cargo clippy --locked --all-targets -- -D warnings && cargo test --locked --lib && cargo test --locked --tests && cargo test --locked --doc
To run all tests (library + integration + doc) in one command: cargo test --locked.
> CONFIG_PERSISTENCE.log
┌──────────────────────────────────────────────────────┐
│ ALL PREFS AUTO-SAVED TO ~/.storageshower.conf │
│ FORMAT: TOML ── RESTORED ON BOOT ── ZERO EDIT │
│ │
│ >> sort mode >> sort direction >> show all │
│ >> refresh rate >> bar style >> color mode │
│ >> warn/crit >> bar visibility >> border │
│ >> col headers >> compact mode >> mount paths │
│ >> show used >> show local >> custom widths │
│ >> mount col w >> right col w >> pct col w │
│ >> custom themes (HashMap) >> active theme │
│ >> bookmarks (Vec<String>) │
└──────────────────────────────────────────────────────┘
> CUSTOM_THEMES.cfg
┌──────────────────────────────────────────────────┐
│ ◈◈◈ THEME SYSTEM ◈◈◈ │
└──────────────────────────────────────────────────┘
30 builtin palettes including: Neon Sprawl · Acid Rain · Ice Breaker · Synth Wave · Rust Belt · Ghost Wire · Red Sector · Sakura Den · Data Stream · Solar Flare · Neon Noir · Chrome Heart · Blade Runner · Void Walker · Toxic Waste · Cyber Frost · Plasma Core · Steel Nerve · Dark Signal · Glitch Pop + 10 more
Create your own by adding to ~/.storageshower.conf:
[custom_themes.neonpink]
blue = 199
green = 46
purple = 201
light_purple = 213
royal = 196
dark_purple = 161
active_theme = "neonpink"
Or use the in-app theme editor (C key) to tweak colors live and save.
See themes/ for the first 10 builtin palettes as ready-to-copy TOML files.
⟦ END OF LINE ⟧
// THE STREET FINDS ITS OWN USES FOR DISK SPACE //