SkillAgentSearch skills...

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/Ruum

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

84/100

Category

Operations

Supported Platforms

Claude Code
Claude Desktop

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.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
4/20
Freshness
15/15

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 found

Our 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.

SkillScoreStarsUpdatedFormat
Ruum (this skill)by JsonLee1213884102d agoMCP Server
Agent-Reachby Panniantong100114.0ktodayCLAUDE.md
hyperframesby heygen-com10088.2ktodayCLAUDE.md
rufloby ruvnet10082.3ktodayCLAUDE.md
headroomby headroomlabs-ai10080.5ktodayCLAUDE.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.

ruum

English | 简体中文 | 日本語 | 한국어

ruum treemap window showing the left icon rail, category legend, color-coded treemap with hatched reclaimable space, Selection and Worth a look side panel, and live disk free-space meter

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

  1. Installation & Initial Setup
  2. Quick Start Tutorial (3 Steps to Free Up Space)
  3. Remote Server Analysis over SSH
  4. Disk Space Watchdog & AI Cleanup Assistant
  5. MCP Server Integration for AI Agents
  6. CLI & Keyboard Shortcuts Reference
  7. Safety Guards, Measurement Notes & Development
  8. License

Installation & Initial Setup

Quick Install (One-Line Installer)

  • macOS & Linux (installs the desktop app + ruum CLI, 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, run ruum update check to inspect available releases and print the exact upgrade command. Linux AppImage supports both built-in in-app updates (Stable/Beta) and .AppImage.zsync incremental updates in tools like AppImageUpdate or Gear Lever (tracking Stable latest).

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): open ruum-*-aarch64-macos.dmg (or x86_64) and drag ruum.app into Applications.
  • Installer package (.pkg): run ruum-*-aarch64-macos.pkg to install /Applications/ruum.app and link /usr/local/bin/ruum.
  • Archive (.zip): unzip ruum-*-aarch64-macos.zip and drag ruum.app into Applications.

First-launch setup on macOS:

  1. Clear Gatekeeper quarantine (for unsigned builds): if macOS reports that the app cannot be verified or appears damaged, clear the browser quarantine attribute once:
    xattr -dr com.apple.quarantine /Applications/ruum.app
    
    (Or open it once and choose Open Anyway in System Settings › Privacy & Security.)
  2. 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 ruum from 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.zsync for AppImageUpdate / Gear Lever tracking Stable latest).
  • Portable tarball: unpack ruum-*-x86_64-linux.tar.gz and run ./install.sh (or copy ruum onto your PATH).

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): run ruum-*-x86_64-windows-setup.exe (supports silent install, Start Menu/Desktop shortcuts, and optional PATH registration).
  • MSI package (.msi): install ruum-*-x86_64-windows.msi per-machine with Start Menu shortcut and optional PATH feature.
  • Portable archive (.zip): unpack ruum-*-x86_64-windows.zip anywhere and run ruum.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 musl stdlib targets below to embed static Linux SSH scanners during make install / make bundle with 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 install embeds the static scanners into ~/.local/bin/ruum and installs ~/.local/bin/ruum-gui, a desktop entry (adding an Open with handler for directories without changing your default file manager), and the ruum.svg icon. Use sudo make install PREFIX=/usr/local for system-wide installation, or make uninstall to remove everything it placed.
    • On macOS, make install builds and installs ~/Applications/ruum.app (including Contents/Resources/ruum-scan-linux.pack when the musl targets are installed) and symlinks ~/.local/bin/ruum (requires Xcode or Command Line Tools). If those musl targets are omitted on macOS, make install prints a warning and still succeeds, and remote SSH falls back to cached or server-installed ruum-scan.
    • If an older binary earlier on PATH shadows ~/.local/bin/ruum, add export PATH="$HOME/.local/bin:$PATH" to your shell configuration.
  • 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:

  1. Open Settings (⌘, on macOS, Ctrl+, on Linux & Windows, or click the gear icon in the Left Icon Rail).
  2. 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

  1. Launch ruum: running ruum scans your home directory (~) immediately, largest entries first.
  2. Pick another folder, drive, or remote host: press v (or click Source… in the right panel, click the ruum logo, or run ruum --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.
  3. Widen to the whole disk anytime: press g, launch ruum --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 (Other is 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 ~/.cache often 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 (default 3).
    • Power Efficiency: choose worker presets (Miser, Balanced, Aggressive, Drain My Battery) for future scans, or pass --scan-threads via CLI.
  • 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

View on GitHub
GitHub Stars10
CategoryOperations
Updated2d ago
Forks1

Languages

Rust

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 info