Command line

devbroom brings the app's scan to the terminal: the same verdicts, the same reasons. Scanning deletes, moves and changes nothing; cleaning is a separate command.

The command line is free. Scanning only reads. devbroom clean does what the app's Clean button does: it shows what's Ready first, asks, then moves it to the Trash. The protections you set in the app apply here too.

Setup

devbroom comes inside the app; there's nothing extra to install. Press “Link devbroom” in Settings › Agents and integrations and the command is linked as ~/.local/bin/devbroom. If the app isn't in the Applications folder, move it there first, or the link breaks. Then open a new terminal and check the version.

Terminal

$ devbroom --versiondevbroom 0.1.0

If ~/.local/bin isn't on your shell's PATH, run the command by its full path or add that folder to your PATH.

Usage

devbroom [scan] [PATH...] [options]devbroom clean [PATH...] [--dry-run] [--delete] [--include-review PATH]... [--yes] [--json]devbroom status [--json]devbroom mcpdevbroom compat

Without a path, the folder you're in is scanned. You can give several paths. The agents' data in your home folder is part of every scan.

Examples

$ devbroom                        # the folder you are in$ devbroom ~/projects ~/work      # several folders$ devbroom ~/projects --details   # with every reason$ devbroom ~/projects --all       # all of them, not just the biggest

Options

Option	What it does
`-d, --details`	Shows every reason behind every verdict.
`-a, --all`	Lists every item found, not just the biggest.
`--json`	Writes the whole report as JSON.
`--no-color`	Turns colors off. No colors are used when `NO_COLOR` is set either.
`-h, --help`	Shows help.
`-V, --version`	Shows the version.
`--`	Treats everything after it as a path: `devbroom -- -odd-folder`

An unknown option is an error, and nothing is scanned.

Cleaning

devbroom clean scans, makes a fresh plan from what's Ready, shows the plan, and only after your OK moves those folders to the Trash. What it did shows up in the app's History; if a cleanup is already running in the app it doesn't wait, it exits.

Terminal

$ devbroom clean ~/projects --dry-run   # only show$ devbroom clean ~/projects             # show, ask, move to the Trash

Option	What it does
`-n, --dry-run`	Shows the plan and changes nothing.
`--delete`	Deletes permanently instead of moving to the Trash. Not available if your organization turned permanent deletion off.
`--include-review PATH`	Adds a Review item to the plan; the app's “Include anyway”. Asks for confirmation in the terminal and can't be used with `--yes`. Can be given more than once.
`-y, --yes`	Cleans without asking.
`--json`	Writes the plan and the result as JSON.

Without a path it uses the folders you chose in the app, or the folder you're in if the app was never set up. clean cleans only build folders, agents' scratch folders and caches; worktrees and agent data are cleaned in the app.

When there's no terminal to ask in, or --yes is given, it's stricter: items that are Ready only because of a project's own .devbroom.toml stay out of the plan, since an agent could have written that file. With no terminal and no --yes, nothing changes.

Status

devbroom status shows the app's last scan without scanning again: how much is ready to clean, how many minutes ago it was scanned and the biggest Ready items. --json gives the same as JSON. If the app hasn't scanned yet, it's an error.

MCP for agents

devbroom mcp is an MCP server. Claude Code, Codex or Cursor can read the last scan, ask why a folder is Ready or Blocked, and ask you to clean; the request comes to you in the app, and it never cleans anything on its own. Setup is on the Integrations page.

Reading the output

The report is written in English and has four parts. Each line starts with the item's verdict.

devbroom ~/projects

$ devbroom ~/projectsDevbroom scan (read-only) ~/projects in 22.4sAgent data on this Mac  Claude Code 2.1.288   37.8 GB  297 sessions, 2 running  Codex 0.159.2          746 MB  41 sessions  Orca 1.4.215           528 MBCleanup potential  READY    19.7 GB  56 items  every check passed  REVIEW   16.9 GB  39 items  worth a look before cleaning  BLOCKED  19.1 GB   5 items  in use or holding work

Agent data on this Mac: The agents on this Mac: version, space taken, number of sessions, how many are for folders that no longer exist and how many are running.
Cleanup potential: Total size and number of items for each verdict.
Worktrees: The suggested action for each worktree (remove, prune, repair) and its verdict.
Largest items: The biggest items, with their reasons. --all shows them all.

Verdicts

The command line uses the app's four verdicts, written in capitals.

In the output	What it means
READYReady	Every check passed for this action.
REVIEWReview	A known risk, or a call only you can make; an ignored `.env` file, for example.
BLOCKEDBlocked	In use, protected, or holding work git would refuse to throw away.
UNKNOWNUnknown	Not enough evidence. Never counted as Ready.

JSON output

--json writes the whole report; it suits scripts and continuous integration. The format is versioned by the schema_version field, currently 1. No progress line is written when JSON is asked for.

Terminal

$ devbroom ~/projects --json > report.json$ head -3 report.json{  "schema_version": 1,  …

Compatibility

devbroom compat shows which agent versions Devbroom has tested and which ones are installed on your Mac.

devbroom compat

Claude Code  tested: 2.1.0 to 2.1.292     here: 2.1.288 · verifiedCodex        tested: 0.115.0 to 0.159.2   here: 0.159.2 · verifiedCursor       tested: none yet             here: not on this MacOpenCode     tested: none yet             here: not on this MacOrca         tested: 1.4.0 to 1.4.221     here: 1.4.215 · verified

If your version is outside the tested range but the agent's files are in the expected format, Devbroom works and shows it as “not tested yet”. If the format doesn't hold, that agent's data is only read; none of it counts as ready to clean.

Exit codes

Code	Meaning
`0`	Done.
`1`	Failed.
`2`	Wrong usage: an unknown option or a path that isn't a folder.
`3`	`clean`: not confirmed, nothing changed.
`4`	`clean`: partly done.
`5`	`clean`: another cleanup is running.
`6`	`clean`: your organization's policy doesn't allow it.
`130`	Cancelled (Ctrl-C).

Ctrl-C stops the scan; a second Ctrl-C exits at once.

Environment variables

Variable	Effect
`NO_COLOR`	When set, the output has no colors.
`CLAUDE_CONFIG_DIR`	If Claude Code's settings folder is somewhere other than `~/.claude`, it's read from there.
`CLAUDE_CODE_TMPDIR`	If you moved Claude Code's temporary folder, it's read from there.
`CODEX_HOME`	If Codex's folder is somewhere other than `~/.codex`, it's read from there.
`CURSOR_CONFIG_DIR`	If Cursor's folder is somewhere other than `~/.cursor`, it's read from there.
`XDG_DATA_HOME`, `XDG_CACHE_HOME`, `OPENCODE_DB`	If OpenCode's data and database are elsewhere, they're read from there.

PreviousRules NextIntegrations

Last updated: October 7, 2026