Docs · SweepLoom

Overview

SweepLoom is a developer-aware workstation resource manager. It answers three questions locally, without an LLM on classify or apply: what is sitting on disk, in RAM and in the agent host; whether it is still earning its keep; and how to reclaim it without losing the workspace.

CLI

sweeploom

For hands. --apply is consent.

MCP server

sweeploom mcp

For agents. Apply needs confirm=true.

Desktop app

sweeploom-gui

A local reviewer for people.

Install

SweepLoom installs from source with Cargo. It is not on crates.io or npm yet, and there are no prebuilt releases. You need Git and Rust via rustup: 1.88 or newer for the CLI and library, 1.95 or newer for the desktop app.

CLI + MCP server

$ cargo install --locked --git https://github.com/Weavatrix/sweeploom sweeploom$ sweeploom --help$ sweeploom mcp --list

This puts two binaries in ~/.cargo/bin: sweeploom, the CLI, which serves MCP as sweeploom mcp, and sweeploom-companion-host, which the browser companion launches. There is no separate sweeploom-mcp binary. Update by re-running the line with --force; remove with cargo uninstall sweeploom.

For the desktop app, the signed macOS bundle and uninstalling, see Download.

Quick start

Look first. Every command below is read-only except the last one.

your first five minutes

$ sweeploom sessions             # what is alive; agents are Keep$ sweeploom ai                   # AI stores and always-on token tax$ sweeploom scan .               # what is on disk in this tree$ sweeploom projects .           # heat, Git state, artifact offers$ sweeploom clean .              # cleanup candidates, dry run$ sweeploom clean . --apply      # delete pre-selected SAFE rows

clean . printing no generated candidates is a valid result: the walk found nothing SAFE to remove. Bare sweeploom prints help; it never waits on stdin.

CLI reference

SweepLoom CLI commands
Command	What it does
`sweeploom sessions [--free-ram GB] [--reduce-cpu PERCENT] [--quiet]`	Live session trees. Flags print a dry-run plan; nothing is terminated.
`sweeploom scan [path]`	Disk inventory of a tree. No path means home; pass . for the current tree.
`sweeploom projects [path]`	Project kinds, source and artifact heat, Git state, artifact offers.
`sweeploom clean [path] [--apply]`	List generated cleanup candidates; --apply deletes pre-selected SAFE rows after revalidation.
`sweeploom ai`	AI tool stores under home: classes, sizes, always-on token estimates. Never deletes.
`sweeploom browser`	Browser process pressure; tab activity via the companion.
`sweeploom bench`	With vs without SweepLoom on a fixed gold store.
`sweeploom mcp [--list]`	Serve MCP over stdio (for hosts). --list prints the tool contract instead.
`sweeploom companion-install [--chromium-id ID]`	Register the browser companion's native messaging host.
`sweeploom companion-host`	What the browser launches. Not a daily command.

Help goes to stderr. An unknown command prints help and exits with status 2; an unknown flag is rejected the same way, so there is no hidden --kill or --yes. From a clone without installing, replace sweeploom with cargo run -p sweeploom --; the -- keeps the flags for SweepLoom instead of Cargo.

MCP setup

The full MCP guidePer-host tabs, every tool's arguments and return fields, the apply gate, example chats, troubleshooting.

SweepLoom speaks MCP over stdio. Server id: io.github.Weavatrix/sweeploom. Your host launches sweeploom mcp; you never type it into a terminal yourself. SweepLoom is an MCP server, not a Cursor Marketplace plugin, so searching the marketplace will find nothing. Add the server entry, then reload the host.

Cursor and Claude Desktop

Cursor: ~/.cursor/mcp.json for every workspace (%USERPROFILE%\.cursor\mcp.json on Windows), or .cursor/mcp.json in a project. Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows.

mcp.json

{  "mcpServers": {    "sweeploom": {      "command": "sweeploom",      "args": ["mcp"]    }  }}

Hosts started from the Dock, Start menu or a launcher may not see your shell PATH. If the server does not start, use the absolute path: ~/.cargo/bin/sweeploom on macOS and Linux, C:\Users\you\.cargo\bin\sweeploom.exe on Windows.

Claude Code

user scope

$ claude mcp add -s user sweeploom -- sweeploom mcp

Codex

Prefer the plugin. For MCP only, add the server to ~/.codex/config.toml:

~/.codex/config.toml

[mcp_servers.sweeploom]command = "sweeploom"args = ["mcp"]

Prefer the installed binary for always-on hosts. Wiring a host to cargo run … -- mcp recompiles on host restarts, writes build diagnostics into the MCP stream, and can disconnect when the disk is full.

Using it well

Name the product. A connected server can still be ignored if the model decides to use the shell. Say “Use SweepLoom to…” when you want its tools.
Pass the workspace path. An empty root on path tools means your home directory.
Review, then apply. cleanup_candidates, then explain_candidate, then ask, then apply_cleanup with confirm: true and exactly the agreed ids. Empty ids means every pre-selected SAFE row.

prompts that work

Use SweepLoom to list cleanup_candidates for this repo and explain anything unclear. Do not apply yet.Use SweepLoom to list_ai_stores and show always-on token tax. Do not park AGENTS.md or rules.Use SweepLoom to list_sessions. Do not terminate live agents.

MCP tools
Tool	Arguments	Access
`list_sessions`	none	read-only
`disk_inventory`	root? string	read-only
`list_projects`	root? string	read-only
`list_ai_stores`	none	read-only
`advise_context`	relative string	read-only
`cleanup_candidates`	root? string	read-only
`explain_candidate`	id u64, root? string	read-only
`list_browser`	none	read-only
`apply_cleanup`	confirm bool, root?, ids? u64[]	confirm=true

Codex plugin

The Codex plugin is the same MCP server plus three skills, review-cleanup, token-tax and live-sessions, that force review-before-apply. It is listed in the weavatrix marketplace.

Codex CLI

$ codex plugin marketplace add Weavatrix/sweeploom$ codex plugin add sweeploom@weavatrix

Start a new Codex session afterwards; skills and MCP tools load with new sessions. The plugin's bundled MCP entry launches npx -y sweeploom mcp, which needs the npm package. Until that is published, register sweeploom mcp yourself in ~/.codex/config.toml as shown above.

Rust library

The sweeploom crate is the same engine as the CLI and the MCP server. Until it is on crates.io, depend on it from Git:

Cargo.toml

[dependencies]sweeploom = { git = "https://github.com/Weavatrix/sweeploom" }

src/main.rs

use sweeploom::{classify_name, estimated_prompt_tokens, AiClass}; assert_eq!(classify_name("AGENTS.md").label(), "Context");assert_eq!(classify_name("history.jsonl"), AiClass::History);assert!(!classify_name(".credentials.json").can_clean());assert_eq!(    estimated_prompt_tokens(AiClass::History, "history.jsonl", 2_000_000),    0);

Listing sessions, inventories and apply (ApplyRequest { confirm, root, ids }) are in docs/LIBRARY.md. An apply_cleanup with confirm: false returns ok == false and deletes nothing.

Desktop app

Nine tabs in four groups. Cleanup has seven sources and History has two views; scans run in the background and keep their results when you switch tabs. The desktop app tour walks through every tab with screenshots.

Desktop app tabs
Group	Tab	What it shows
Live	Overview	Memory, per-core CPU and disk pressure; every tile opens the screen that explains it
	Sessions	Session trees, member processes, observed CPU, dry-run plans
	History	Observed process activity, plus saved disk scansProcess activity · Disk scans
Disk	Cleanup	Everything reclaimable, by source, with the consequence of removalProject output · Docker · iOS & Xcode · Build & packages · App & browser caches · AI models · Archives & large data
	Projects	Every project under your developer folders: size, change, Git, artifacts
	Explorer	Folder inspector, off the UI thread; collapsing never re-walks the disk
Workspace	Browser	Browser trees, companion tabs, the Later shelfProcess trees · Tabs · Later
	AI	AI stores, classes and always-on token tax
App	Settings	Theme, interface size, tray; telemetry stays off

Needs Rust 1.95 or newer. Either run it from a clone, or install it as a sweeploom-gui binary:

build and run

$ git clone https://github.com/Weavatrix/sweeploom.git$ cd sweeploom$ cargo run --release -p sweeploom-gui

or install the binary

$ cargo install --locked --git https://github.com/Weavatrix/sweeploom sweeploom-gui

On macOS, build the signed bundle so folder permissions survive updates. It needs a code-signing identity in your keychain; see Download → macOS. On Windows and macOS the app can keep running in the tray; sweeploom-gui --tray starts it hidden.

If the app ever panics, the message and source location are appended to ~/Library/Logs/SweepLoom/panic.log on macOS, %LOCALAPPDATA%\SweepLoom\panic.log on Windows, and $XDG_STATE_HOME/SweepLoom/panic.log (or ~/.local/state/SweepLoom/panic.log) on Linux. Attach it to the issue.

Browser companion

Optional. Without it, sweeploom browser still reports real RSS and CPU, and tab counts stay unknown, never zero. With it, the extension reports each tab's title, stripped URL and lastAccessed to a local SweepLoom process over native messaging. It makes no network requests and never closes tabs by default.

register the native host

$ sweeploom companion-install$ sweeploom companion-install --chromium-id <id from edge://extensions>$ sweeploom browser

Load browser/chromium-extension (Chrome, Edge and other Chromium browsers) or browser/firefox-extension (Firefox 121+) from the repository as an unpacked extension, then run companion-install. Chromium browsers also need the extension id from edge://extensions or chrome://extensions. sweeploom browser shows companion=connected once a fresh snapshot arrives.

Reference docs

Everything else, with full transcripts, lives in the repository.

Get SweepLoom running, then point your agent at it.

Cursor and Claude Desktop

Claude Code

Codex

Using it well