MCP · for coding agents

A cleanup tool your agent can use, and cannot misuse.

SweepLoom is an MCP server over stdio. Your agent gets eight read-only tools to see what is on disk, in RAM and in the agent host, and one tool that deletes only reviewed SAFE generated rows, only with confirm=true. There is no terminate tool.

Connect a host Tool reference docs/MCP.md

What it is for

Ground truth for the agent, a gate for you.

Ask an agent without SweepLoom what is safe to delete and it improvises: du on a guess, folder names as evidence, ~/.claude divided by four, or the idle editor killed to free RAM. With SweepLoom it reads classified rows with a safety verdict, and the one destructive call needs your yes.

Evidence instead of guesses
Sessions grouped into trees, folders with categories, projects with source and artifact heat and Git state, AI stores with classes and capped always-on token estimates.
Read-only by default
Eight tools only read and publish readOnlyHint, so hosts can treat them as safe. apply_cleanup refuses unless confirm is true, revalidates every row, and returns a receipt.
Local and quiet
The host launches sweeploom mcp and talks JSON-RPC over stdin and stdout. No network requests, no account, no telemetry, no LLM inside the tool.

What reaches your model provider. Tool results (paths, sizes, process and project details) enter the agent's context, so they reach whichever model provider your host uses. SweepLoom itself sends nothing anywhere. See the privacy policy.

Not a token saver. SweepLoom does not compress context. A live coding-agent run on 2026-09-15 found no coding-task token saving with the MCP attached, and we publish that result.

Install

One binary. The host starts it as sweeploom mcp.

Install the CLI from source; it is also the MCP server. Packages on crates.io and npm are not published yet.

install the CLI + MCP server

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

The server is the sweeploom binary with the argument mcp. There is no separate sweeploom-mcp binary; that name is only the alias of a future npm launcher.
Server id io.github.Weavatrix/sweeploom, transport stdio. You never type tools/call yourself; the host does.
sweeploom mcp --list prints the contract without serving, so you can check the install before wiring a host.

the agent contract, as the CLI prints it

$ sweeploom mcp --listsweeploom  SweepLoomio.github.Weavatrix/sweeploom  mcp_tools=9  list_sessions          read         cli=sessions mcp  disk_inventory         read         cli=scan mcp  list_projects          read         cli=projects mcp  list_ai_stores         read         cli=ai mcp  bench_compare          read         cli=bench  advise_context         read         mcp  cleanup_candidates     read         cli=clean mcp  explain_candidate      read         mcp  list_browser           read         cli=browser mcp  apply_cleanup          mcp-confirm  mcp  clean_apply            cli-write    cli=clean  companion_install      cli-write    cli=companion-install  companion_host         read         cli=companion-host

Connect a host

Claude Code, Cursor, Claude Desktop and Codex.

These are the hosts the docs cover. Any MCP host that launches stdio servers can use the same command and args. Reload the host after adding the entry.

user scope, every project

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

.mcp.json · project scope

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

User scope makes SweepLoom available in every project. For one repository, commit a .mcp.json with the same sweeploom mcp launch; the SweepLoom repository ships exactly that file.

Working on SweepLoom itself? You can point Claude Code at a clone without installing, but it recompiles on every host restart and is for development only:

from a clone (development only)

$ claude mcp add -s user sweeploom -- cargo run -q --manifest-path C:/Users/you/work/sweeploom/Cargo.toml -p sweeploom -- mcp

~/.cursor/mcp.json

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

~/.cursor/mcp.json applies to every workspace (%USERPROFILE%\.cursor\mcp.json on Windows); .cursor/mcp.json inside a project applies to that project. Then toggle sweeploom under Cursor → Settings → MCP.

Do not look for it under Plugins or the Marketplace. SweepLoom is an MCP server, and the Marketplace will not list it.

claude_desktop_config.json

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

Add the same object to the Claude Desktop config file, then restart the app:

macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json

A desktop app started from the Dock or Start menu may not see your shell PATH. If the server does not start, replace "sweeploom" with the absolute path, as on the Absolute path tab.

~/.codex/config.toml

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

optional: the plugin's skills

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

For MCP only, add the server to ~/.codex/config.toml. The Codex plugin adds three review skills on top of the same server.

Register the server in config.toml even if you install the plugin: the plugin's own entry runs npx -y sweeploom mcp, which needs the npm package that is not published yet. Start a new Codex session afterwards.

mcp.json with an explicit path

{  "mcpServers": {    "sweeploom": {      "command": "C:\\Users\\you\\.cargo\\bin\\sweeploom.exe",      "args": ["mcp"]    }  }}

When a GUI host cannot find sweeploom on PATH, give it the full path to the installed binary. Cargo installs it to %USERPROFILE%\.cargo\bin on Windows and ~/.cargo/bin on macOS and Linux. JSON needs doubled backslashes.

Prefer the installed binary in every always-on host. A cargo run launch recompiles on restart and can disconnect when the disk is full.

Check it works

After a reload the host should list nine SweepLoom tools. Then ask, naming the product: “Use SweepLoom to list cleanup_candidates for this repo and explain anything unclear. Do not apply yet.”

Tool reference

Nine tools. Eight read. One writes, behind confirm=true.

Arguments, access and what each tool returns, from the server's own catalog. Every read-only tool publishes readOnlyHint, and a test fails if the served annotations drift from that contract.

SweepLoom MCP tools: arguments, access, CLI equivalent and returned fields
Tool	Arguments	Access	CLI twin	Returns
`list_sessions` Live session trees with Keep / Optional recommendations	none	read-only	sessions	kind, processes, rss_bytes, cpu_percent, recommendation, activity, project, planned
`disk_inventory` What is on disk under a root, with categories (metadata only)	root? string	read-only	scan	root, entries, projects, capped, logical_bytes, children[path, logical_bytes, category]
`list_projects` Project kinds, source and artifact heat, Git state	root? string	read-only	projects	path, kind, source, artifact, git
`list_ai_stores` AI tool stores, classes and always-on token estimates; never opens secrets or SQLite	none	read-only	ai	title, path, logical_bytes, capped, entries[id, class, relative, prompt_tokens, advice, can_clean]
`advise_context` Advice for one leaf name: keep for Context such as AGENTS.md, empty for History; never writes	relative string	read-only	—	relative, class, advice (park? needs file age, so it comes from list_ai_stores)
`cleanup_candidates` Reviewable cleanup rows (dry run); SAFE generated rows pre-selected	root? string	read-only	clean	id, title, path, logical_bytes, selected, blocked, deletion
`explain_candidate` One row in detail before anyone agrees to it	id u64, root? string	read-only	—	the same row, or the error unknown candidate <id>
`list_browser` Browser pressure; tabs null when unknown	none	read-only	browser	companion, hosts, rss_bytes, tabs (null without a fresh companion)
`apply_cleanup` Revalidate and delete the agreed ids; returns a receipt	confirm bool, root?, ids? u64[]	gated	clean --apply	ok, error, deleted, skipped_changed, failed, receipt

Empty root is your home directory. Path tools default to home when root is missing or empty. Agents should always pass the workspace's absolute path.
Ids come from review. explain_candidate resolves an id from cleanup_candidates (or an AI store row from list_ai_stores); an unknown id returns unknown candidate <id>.
Unknown stays unknown. list_browser returns tabs: null without a fresh browser companion snapshot. Null is not zero.
Not in the catalog: no terminate, no park_file, no rewrite_agents. Those are not hidden flags; they do not exist.

The apply gate

List, explain, ask, then apply exactly what was agreed.

apply_cleanup runs the same plan → revalidate → execute → receipt path as sweeploom clean --apply. The difference is consent: on the CLI --apply is yours; over MCP the agent must send confirm=true, and only after you said yes.

the only apply path

tools/call  cleanup_candidates   { "root": "C:/work/app" }tools/call  explain_candidate    { "id": 3, "root": "C:/work/app" }# the agent shows you row 3 and askstools/call  apply_cleanup        { "confirm": true, "root": "C:/work/app", "ids": [3] }

1Review tools first. cleanup_candidates, then explain_candidate for anything unclear.
2Say the plan in plain words. Path, size, why it is SAFE generated, what it costs to rebuild.
3confirm: true only after the user agrees. Never as a retry after a refusal.
4ids = exactly what was agreed. Empty ids means every pre-selected SAFE row, the same as sweeploom clean --apply. Do not send empty ids unless that is what the user asked for.

a receipt

{  "ok": true,  "error": null,  "deleted": 1,  "skipped_changed": 0,  "failed": 0,  "receipt": 1}

Revalidated at apply time. If target/ changed since the listing, that row is counted in skipped_changed, not forced.

Blocked rows never go. Rows that are blocked (an active process, recent writes, uncommitted Git changes and similar) or inspect-only are filtered out even if their ids are passed.

Locked by a test. mcp_apply_without_confirm_does_not_run asserts that confirm: false returns ok=false and deletes nothing.

confirm missing or false

refused: MCP apply needs confirm=true after cleanup_candidates; CLI uses --apply

an id that was never listed

unknown candidate 999999

nothing SAFE matches

nothing eligible to apply

Boundaries

What an agent can and cannot do.

Can

List live sessions grouped into trees, with Keep or Optional for each.
Map a folder, list its projects with source and artifact heat and Git state.
Inspect AI stores and their always-on token estimates without opening secrets or SQLite.
Explain any candidate row before you decide.
Delete SAFE generated rows you agreed to, after revalidation, and show you the receipt.

Cannot

Terminate any process. Idle agents and their attached MCP servers stay Keep.
Delete anything without confirm=true, or delete blocked and inspect-only rows at all.
Edit AGENTS.md, *.mdc or rules, or flip alwaysApply. park? is advice for you.
Touch Docker, simulators, models, archives or the Trash. Those live in the desktop app, where a person confirms.
See browser tabs without the companion. It reports unknown, not zero.

Example chats

What good and bad requests look like.

Condensed from the copy-paste chats in the repository. The JSON is the shape the tools return; sizes are from the 2026-09-14 capture.

“This repo is huge, clean it”the only apply path

You
This workspace is huge. What can SweepLoom delete safely? Show me the rows. Do not delete yet.

Agent calls

cleanup_candidates   { "root": "C:/work/app" }
explain_candidate    { "id": 3, "root": "C:/work/app" }

SweepLoom returns

[
  { "id": 3, "title": "cargo target", "logical_bytes": 1288490188,
    "selected": true, "blocked": false, "deletion": "PermanentGenerated" },
  { "id": 4, "title": "node_modules", "logical_bytes": 851443712,
    "selected": true, "blocked": false, "deletion": "PermanentGenerated" }
]

Agent
Two SAFE generated rows: • id 3 cargo target ~1.2 GB rebuild = cargo build • id 4 node_modules ~812 MB rebuild = npm ci Nothing else is pre-selected. I have not deleted anything. Want id 3 only, both, or stop?
You
Only cargo target.

Agent calls

apply_cleanup   { "confirm": true, "root": "C:/work/app", "ids": [3] }

SweepLoom returns

{ "ok": true, "deleted": 1, "skipped_changed": 0, "failed": 0, "receipt": 1 }

Agent
Deleted id 3 (target). Receipt 1. node_modules left alone.

An agent tries to skip reviewrefused, 0 deleted

You
Just wipe the build cache.

Agent calls

apply_cleanup   { "confirm": false, "root": "C:/work/app" }

SweepLoom returns an MCP error

refused: MCP apply needs confirm=true after cleanup_candidates; CLI uses --apply

Agent
Nothing was deleted. Let me list the candidates first and show you what would go.

“Why is my agent so expensive?”read-only

You
Codex feels expensive. Is it history on disk or always-on context? Do not delete my chats. Do not edit AGENTS.md.

Agent calls

list_ai_stores
advise_context   { "relative": "AGENTS.md" }
advise_context   { "relative": "history.jsonl" }

SweepLoom returns

{ "relative": "AGENTS.md", "class": "Context", "advice": "keep" }
{ "relative": "history.jsonl", "class": "History", "advice": "" }

Agent
~/.claude/projects is 862 MB of History: archive, 0 always-on tokens. I will not delete it. plugins is ~4096 always-on tokens (capped), keep. skills is park? (idle 30+ days); SweepLoom will not flip alwaysApply. AGENTS.md and rules stay keep. .credentials.json is Secret and never opened.

“Cursor is idle, kill it”no terminate tool

You
Cursor is idle and 7 GB. Kill it.
Agent calls
```
list_sessions
```

SweepLoom returns

[
  { "kind": "Cursor", "processes": 43, "rss_bytes": 7838315315,
    "recommendation": "Keep", "activity": "Idle", "planned": false },
  { "kind": "Codex", "processes": 3, "recommendation": "Keep" },
  { "kind": "Claude Code", "processes": 2, "recommendation": "Keep" }
]

Agent
SweepLoom has no terminate tool. Cursor, Codex and Claude are Keep so this chat stays. I will not shell out to taskkill. If you want a dry-run plan of Optional helpers only: sweeploom sessions --quiet

Map a folder, then decideread-only

You
What is under C:/work/app besides source?

Agent calls

disk_inventory   { "root": "C:/work/app" }
list_projects    { "root": "C:/work/app" }
list_browser

SweepLoom returns

{ "root": "C:\\work\\app", "entries": 18420, "capped": false,
  "children": [ { "path": "C:\\work\\app\\target", "logical_bytes": 1288490188,
                  "category": "Generated" } ] }
[ { "path": "C:\\work\\app", "kind": "Cargo", "source": "Warm",
    "artifact": "Hot", "git": "Clean" } ]
{ "companion": "disconnected", "hosts": 1, "rss_bytes": 8804682956, "tabs": null }

Agent
1.2 GB of target/ is generated output in a clean Cargo project. Browser tabs are unknown (tabs: null), not zero. Want me to list cleanup candidates?

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.

The full transcripts, including the JSON for every call, are in docs/MCP-CHATS.md and docs/MCP-CHATS-AGENTS.md.

Codex plugin

The same server, plus skills that make review the default.

The plugin is listed in the weavatrix marketplace in this repository. Its three skills turn the chats above into instructions Codex follows on every request.

Codex CLI

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

also register the server (npm is not published yet)

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

From a clone: codex plugin marketplace add . then codex plugin add sweeploom@weavatrix. Start a new Codex session; check with codex plugin list or /plugins.

review-cleanup

Review generated cleanup rows, then apply only after the user agrees. Never delete first.

cleanup_candidates → explain_candidate → show the plan → apply_cleanup with confirm: true and the agreed ids

token-tax

Inspect always-on AI context. History is archive. Do not disable AGENTS.md or rules.

list_ai_stores → advise_context → report prompt_tokens and advice; never invent counts

live-sessions

List live coding sessions. Keep live agents. Only an MCP server with no parent agent may be Optional.

list_sessions → explain Keep / Optional; dry-run plans are a CLI suggestion, never a kill

The plugin will not terminate live agents, apply without confirm=true, rewrite AGENTS.md, *.mdc or rules, or open secrets or SQLite. Why skills matter.

Troubleshooting

When the agent does not do what you expect.

The server is connected, but the agent ignores it and uses the shell

A connected server is a catalog the model may or may not consult. If you never say “SweepLoom”, it can decide that du is good enough. Name the product, or a skill, when you want its tools:

silent vs told

# connected, not named: the model may skip the catalogCodex feels expensive. Do not delete my chats. # connected and named: the model should call list_ai_storesUse SweepLoom to list_ai_stores. Do not park AGENTS.md.

The server does not start from Claude Desktop or Cursor

Hosts launched from the Dock, the Start menu or a launcher may not inherit your shell PATH, so the bare command sweeploom is not found. Use the absolute path of the installed binary: /Users/you/.cargo/bin/sweeploom on macOS, /home/you/.cargo/bin/sweeploom on Linux, C:\Users\you\.cargo\bin\sweeploom.exe on Windows (see the Absolute path tab above). Then reload the host.

Searching the Cursor Marketplace for SweepLoom finds nothing

That is expected. SweepLoom is an MCP server, not a Marketplace plugin. Add the mcpServers entry and toggle it under Cursor → Settings → MCP.

npx -y sweeploom mcp fails, or the Codex plugin's tools never appear

SweepLoom is not on npm or crates.io yet, so npx -y sweeploom mcp, which the Codex plugin's bundled entry uses, cannot start today. Install from source and register sweeploom mcp in ~/.codex/config.toml yourself. Then start a new Codex session: skills and MCP tools load with new sessions, not mid-chat.

The agent scanned my whole home directory

An empty or missing root on disk_inventory, list_projects, cleanup_candidates, explain_candidate and apply_cleanup means your home directory. Ask the agent to pass the absolute path of the workspace, and to use the same root for the review and the apply.

apply_cleanup answered “refused” or “nothing eligible to apply”

refused: MCP apply needs confirm=true… is the gate working: the agent tried to apply without your agreement. nothing eligible to apply means no SAFE, unblocked row matched the ids (or, with empty ids, nothing was pre-selected). A clean tree is a valid answer; SweepLoom does not invent junk.

Running sweeploom mcp in a terminal just sits there

It is serving MCP over stdio and waiting for a host. Leave that to Claude Code, Cursor, Claude Desktop or Codex. To see the contract without serving, run sweeploom mcp --list. Bare sweeploom prints help; it never waits on stdin.

I wired the host to cargo run and it keeps disconnecting

cargo run … -- mcp recompiles when the host restarts, writes build diagnostics into the MCP process, and can fail with an OS disk-full error. It is a development command. Install the binary once (cargo install --path crates/sweeploom-cli --locked from a clone) and point the host at sweeploom mcp.

Reference

A cleanup tool your agent can use, and cannot misuse.

Ground truth for the agent, a gate for you.

Evidence instead of guesses

Read-only by default

Local and quiet

One binary. The host starts it as sweeploom mcp.

Claude Code, Cursor, Claude Desktop and Codex.

Nine tools. Eight read. One writes, behind confirm=true.

List, explain, ask, then apply exactly what was agreed.

What an agent can and cannot do.

Can

Cannot

What good and bad requests look like.

The same server, plus skills that make review the default.

When the agent does not do what you expect.

The MCP docs on GitHub.