Ruum
Fast cross-platform disk space analyzer & treemap explorer built in Rust with GPUI. Scan local & SSH disks, monitor free space with an AI watchdog, and safely clean files via GUI or MCP.
Install / Use
claude mcp add JsonLee12138 -- npx -y github:JsonLee12138/RuumIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
OperationsSupported Platforms
Our assessment of Ruum
Ruum scores 84/100 on our quality scale, 555th of 763 Operations skills we index.
Its MCP Server is 30 KB long, well organised into 33 sections with 8 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 2 days ago, so Ruum is actively maintained.
- It is released under GPL-3.0, a copyleft license: you can use it, but modified versions you distribute must carry the same license.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (3 minor notes below).
- noteInstalls by piping a downloaded script into a shellline 36
curl -fsSL https://ruum-updates.jsonlee12138.com/install.sh | sh - noteInstalls by piping a downloaded script into a shellline 38
curl -fsSL https://ruum-updates.jsonlee12138.com/install.sh | sh -s -- --cli-only - noteInstalls by piping a downloaded script into a shellline 42
irm https://ruum-updates.jsonlee12138.com/install.ps1 | iex
Automated pattern scan on 2026-11-22. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
Ruum compared with similar skills
All 4 of these similar skills score higher than Ruum; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| Ruum (this skill)by JsonLee12138 | 84 | 10 | 2d ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| hyperframesby heygen-com | 100 | 88.2k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.3k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 80.5k | today | CLAUDE.md |
Frequently asked questions
- How do I install Ruum?
- Run
claude mcp add JsonLee12138 -- npx -y github:JsonLee12138/Ruum. The install tabs above show the steps for each supported agent. - Which AI agents does Ruum work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is Ruum safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (3 minor notes below). It is GPL-3.0-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is Ruum still maintained?
- The repository was last updated 2 days ago, so Ruum is actively maintained.
Skill content
View source on GitHubruum

Find what is filling a disk, mark what should go, and clean it up safely — with your volume's free space in view the whole time.
ruum is a cross-platform treemap disk analyzer and cleanup companion for macOS, Linux, and Windows. Built with GPUI and gpui-omarchy, it turns your drives and remote SSH servers into an interactive nested mosaic sized by real disk usage, pairs it with non-destructive mark-and-review workflows, and adds a low-overhead Disk Space Watchdog, AI cleanup assistant, and headless stdio MCP server (ruum mcp). The UI and CLI automatically localize into English, Simplified Chinese (zh), Japanese (ja), and Korean (ko).
Why "Ruum"?
Ruum takes its name from the Old Norse sense of spaciousness and open room (rúm). A disk analyzer shouldn't just draw another dense tree of numbers — its purpose is to clear away accumulated build artifacts, forgotten caches, and stray clutter so your drives have open breathing room again.
Table of Contents
- Installation & Initial Setup
- Quick Start Tutorial (3 Steps to Free Up Space)
- Remote Server Analysis over SSH
- Disk Space Watchdog & AI Cleanup Assistant
- MCP Server Integration for AI Agents
- CLI & Keyboard Shortcuts Reference
- Safety Guards, Measurement Notes & Development
- License
Installation & Initial Setup
Quick Install (One-Line Installer)
- macOS & Linux (installs the desktop app +
ruumCLI, verified with SHA-256):curl -fsSL https://ruum-updates.jsonlee12138.com/install.sh | sh # Headless / server CLI only: curl -fsSL https://ruum-updates.jsonlee12138.com/install.sh | sh -s -- --cli-only - Windows (PowerShell):
irm https://ruum-updates.jsonlee12138.com/install.ps1 | iex
In-app & CLI updates: Desktop installs check for new versions automatically in the background (configured in Settings › Updates, supporting Stable and Beta channels; nothing is downloaded until you click Download & Update). You can toggle the optional Share anonymous usage statistics setting in Settings › Updates (or via
ruum config update set --send-client-id false) — zero IP addresses or user paths are logged. On headless servers, runruum update checkto inspect available releases and print the exact upgrade command. Linux AppImage supports both built-in in-app updates (Stable/Beta) and.AppImage.zsyncincremental updates in tools likeAppImageUpdateorGear Lever(tracking Stablelatest).
macOS
Install via Homebrew (macOS 11 or newer, Apple Silicon aarch64-macos & Intel x86_64-macos):
brew tap JsonLee12138/tap && brew install --cask ruum
Or download an installer from the latest release:
- Disk image (
.dmg): openruum-*-aarch64-macos.dmg(orx86_64) and dragruum.appintoApplications. - Installer package (
.pkg): runruum-*-aarch64-macos.pkgto install/Applications/ruum.appand link/usr/local/bin/ruum. - Archive (
.zip): unzipruum-*-aarch64-macos.zipand dragruum.appintoApplications.
First-launch setup on macOS:
- Clear Gatekeeper quarantine (for unsigned builds): if macOS reports that the app cannot be verified or appears damaged, clear the browser quarantine attribute once:
(Or open it once and choose Open Anyway in System Settings › Privacy & Security.)xattr -dr com.apple.quarantine /Applications/ruum.app - Grant Full Disk Access: to inspect protected locations (Mail, Messages, Safari, Trash, and other app containers), grant ruum Full Disk Access in System Settings › Privacy & Security — the side panel shows an Open Privacy Settings button whenever items are unreadable — then reopen the app. If you launch
ruumfrom a terminal, your terminal app also needs Full Disk Access. macOS also prompts once for Desktop, Documents, and Downloads.
Linux
Download a package from the latest release (x86_64 or aarch64):
- Arch / Omarchy (AUR):
yay -S ruum-bin # prebuilt release binary # or: yay -S ruum # build from source - Debian / Ubuntu (
.deb):sudo apt install ./ruum-*-x86_64-linux.deb - Fedora / RHEL (
.rpm):sudo dnf install ./ruum-*-x86_64-linux.rpm - AppImage:
chmod +x ruum-*-x86_64.AppImage && ./ruum-*-x86_64.AppImage(supports built-in in-app updates, and includes.AppImage.zsyncforAppImageUpdate/Gear Levertracking Stablelatest). - Portable tarball: unpack
ruum-*-x86_64-linux.tar.gzand run./install.sh(or copyruumonto yourPATH).
Hyprland floating window rule: Hyprland tiles new windows by default; ruum works best in a roomy floating window (class is ruum):
windowrule = float, class:^(ruum)$
windowrule = size 1400 900, class:^(ruum)$
Windows
On Windows 10 or 11 (x86_64 or aarch64), download from the latest release:
- Installer wizard (
-setup.exe): runruum-*-x86_64-windows-setup.exe(supports silent install, Start Menu/Desktop shortcuts, and optionalPATHregistration). - MSI package (
.msi): installruum-*-x86_64-windows.msiper-machine with Start Menu shortcut and optionalPATHfeature. - Portable archive (
.zip): unpackruum-*-x86_64-windows.zipanywhere and runruum.exe.
NTFS fast scans on Windows: when scanning a whole NTFS drive (such as C:\) without --follow-links, running as Administrator lets ruum read the NTFS Master File Table (MFT) directly — several times faster than directory traversal — and inspect protected folders like System Volume Information. The side panel offers Restart as Administrator whenever elevation can speed up or unlock unreadable items.
Build from Source & Verify Downloads
Building requires Rust 1.97 or newer (pinned in rust-toolchain.toml via rustup).
- macOS & Linux (Linux also requires a Wayland or X11 session with a Vulkan-capable GPU; both macOS and Linux use the
muslstdlib targets below to embed static Linux SSH scanners duringmake install/make bundlewith no C cross-compiler required):# Both macOS & Linux (embeds static Linux SSH helpers, no C cross-compiler required): rustup target add x86_64-unknown-linux-musl aarch64-unknown-linux-musl git clone https://github.com/JsonLee12138/Ruum.git cd Ruum make install- On Linux,
make installembeds the static scanners into~/.local/bin/ruumand installs~/.local/bin/ruum-gui, a desktop entry (adding an Open with handler for directories without changing your default file manager), and theruum.svgicon. Usesudo make install PREFIX=/usr/localfor system-wide installation, ormake uninstallto remove everything it placed. - On macOS,
make installbuilds and installs~/Applications/ruum.app(includingContents/Resources/ruum-scan-linux.packwhen themusltargets are installed) and symlinks~/.local/bin/ruum(requires Xcode or Command Line Tools). If thosemusltargets are omitted on macOS,make installprints a warning and still succeeds, and remote SSH falls back to cached or server-installedruum-scan. - If an older binary earlier on
PATHshadows~/.local/bin/ruum, addexport PATH="$HOME/.local/bin:$PATH"to your shell configuration.
- On Linux,
- Windows (MSVC toolchain / Visual Studio Build Tools with C++ workload):
git clone https://github.com/JsonLee12138/Ruum.git cd Ruum cargo build --release # target\release\ruum.exe
Verify release artifacts: every release publishes SHA256SUMS, per-artifact .sha256 files, and Sigstore build provenance attestations:
sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify <downloaded-artifact> --repo JsonLee12138/Ruum
Register the ruum CLI in PATH
If you installed the desktop app from a .dmg, .zip, or portable archive, register the ruum terminal command in one click:
- Open Settings (
⌘,on macOS,Ctrl+,on Linux & Windows, or click the gear icon in the Left Icon Rail). - Under Command-Line Tool, click Install CLI Command (also accessible from the macOS menu bar via ruum › Install CLI Command…).
This registers /usr/local/bin/ruum on macOS, ~/.local/bin/ruum on Linux, or copies ruum.exe (along with sibling ruum-gui.exe) into %LOCALAPPDATA%\Programs\ruum\bin and updates your user Path on Windows — enabling ruum, ruum ssh, ruum watchdog, and ruum mcp from any shell or AI agent. When the Windows app updates, it also keeps ruum.exe, ruum-gui.exe, and ruum-scan-linux.pack in %LOCALAPPDATA%\Programs\ruum\bin in sync.
Quick Start Tutorial (3 Steps to Free Up Space)
Step 1: Choose a Source & Scan Root
- Launch ruum: running
ruumscans your home directory (~) immediately, largest entries first. - Pick another folder, drive, or remote host: press
v(or click Source… in the right panel, click the ruum logo, or runruum --choose) to open Sources & Drives:- Choose This computer (or enter an SSH target and click Connect SSH). Discovery lists mounts without probing network shares or scanning files.
- Select a mounted volume and click Scan selected root, or type any absolute path and click Scan directory.
- Widen to the whole disk anytime: press
g, launchruum --disk, or click an ancestor breadcrumb above your scan root (such as/). Widening is memoized: the subtree already scanned is reused so going from~to/only walks directories outside~.
Step 2: Explore & Locate Space Hogs
Use the Left Icon Rail on the far left edge to switch between Explore treemap, Sources & Drives, Watchdog, and Settings.
In the Explore screen:
- Read the treemap at a glance:
- Tile area shows proportional disk usage (or file count).
- Colors classify what data is: Code, Agent scratch, Toolchains, Synced, Git, Media, Documents, and Cache (
Otheris neutral). - Diagonal hatching marks Reclaimable directories (caches, sync history, package stores, compiler/bundler build output, reinstallable dependencies, sandbox layers, snapshots, trash, temporary files).
- Tune the view controls in the top bar:
- Size / Files / Age (
t): switch between allocated bytes, file count, or last-write Age (This week through Older). - Hidden files (
i): include or skip dotfiles and hidden folders (included by default because~/.cacheoften dominates home usage). - Apparent size (
d): toggle between real allocated blocks (st_blocks × 512) and logical file lengths (ls -l). - Depth 1–6 (
[/]): draw fewer or more nested levels simultaneously (default3). - Power Efficiency: choose worker presets (
Miser,Balanced,Aggressive,Drain My Battery) for future scans, or pass--scan-threadsvia CLI.
- Size / Files / Age (
- Navigate and filter quickly:
- Scroll wheel zooms smoothly toward the cursor and descends c
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
88.2kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.3k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
80.5kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
