Skip to content

About

A local disk-space browser, live system monitor and safe cleaner. One small binary runs the service and serves the web UI nothing to configure, no Node, no database, nothing leaves your machine.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

28 Commits

Folders and files

Repository files navigation

Spacescope logo

Spacescope

A local disk-space browser, live system monitor and safe cleaner. One small binary runs the service and serves the web UI — nothing to configure, no Node, no database, nothing leaves your machine.

Project page: https://forkyeahman.github.io/Spacescope/

  • Dashboard — live CPU, memory, disk and network charts (last minute, hover to inspect).
  • System — OS, health, per-core load, memory, temperatures and every storage device.
  • Cleaner — scan a folder or the whole disk, then browse the result as a sunburst chart: open folders to go deeper, tick anything and move it to the Trash (always recoverable — nothing is permanently deleted).

Works on macOS, Linux and Windows. Light and dark themes follow your OS.

Install

From source (needs Rust 1.85+):

git clone https://github.com/ForkYeahMan/Spacescope
cd Spacescope
./install.sh          # or: make install   /   cargo install --path .

This puts spacescope in ~/.cargo/bin. Remove it with ./uninstall.sh.

Prebuilt binaries: tagged releases publish macOS, Linux and Windows archives on the GitHub Releases page (built by .github/workflows/release.yml).

Use

spacescope            # starts on http://127.0.0.1:8080 and opens your browser
spacescope --home     # Cleaner defaults to your home folder
spacescope --port 9000 --no-open

Press Ctrl-C to stop. If the port is taken, the next free one is used.

Flag Description Default
--port <PORT> Port for the web UI 8080
--host <ADDR> Address to listen on (non-loopback = no auth, be careful) 127.0.0.1
-p, --path <PATH> Folder pre-filled in the Cleaner whole disk
--home Pre-fill the Cleaner with your home folder off
-m, --min-size Smallest file to list, in MB 1
-d, --depth <N> Folder levels to descend below the root (0 = no limit) 0
--no-open Don't open the browser off

Sizes

Sizes are decimal (1 GB = 1,000,000,000 bytes), the same as Finder and System Settings. A disk sold as "256 GB" reports about 245 GB usable on macOS, because the OS reserves part of it.

Safety

  • Deleting only moves to the Trash; restore anything until you empty it.
  • The API only accepts paths from the current scan results, and each must still resolve inside the scanned folder (no .. or symlink escapes).
  • System files appear in the chart (they take up space) but can't be selected or deleted.
  • "Safe" means regenerated by the system or a tool: caches, temp files, build output, node_modules, package caches and logs. Downloads, archives, old files and duplicates are your data and are never pre-selected.
  • The server listens on localhost only and rejects requests with a foreign Host header (DNS-rebinding protection).

Development

make dev        # debug server; frontend files are read from disk — edit and refresh
make test       # unit tests
make lint       # clippy + fmt

Layout:

src/
  main.rs            CLI, port binding, browser launch
  scanner/           parallel directory walk (depth, cancel, hard-link dedupe)
  analyzer/          file categorisation and "safe to delete" rules
  cleaner/           move-to-Trash
  web/
    server/          axum routes, handlers, errors, request guard, embedded assets
    sysmon/          sysinfo-backed live metrics
    assets/          the UI — plain ES modules, no build step
      css/           tokens (light/dark) · base (shell, cards, controls) · charts · pages
      js/lib/        api, store (live metrics), format, theme, tiny html``
      js/charts/     hand-rolled SVG/HTML: line, storage bar, columns, bar rows
      js/components/ sidebar, ui, toast, confirm dialog
      js/pages/      dashboard, system, cleaner/{home,scanning,results}

License

MIT

About

A local disk-space browser, live system monitor and safe cleaner. One small binary runs the service and serves the web UI nothing to configure, no Node, no database, nothing leaves your machine.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages