Let your AI agent clean up files through Mint

What comes with Mint Direct

Mint Direct links mint-cli into /opt/homebrew/bin or /usr/local/bin, whichever it can write to, each time it launches, so it works from any terminal. mint-cli status shows how your disk use changed across recent scans, mint-cli why shows what is growing, and mint-cli scan lists caches and junk that can go. mint-cli agents reports what Codex, Claude Code and Cursor keep on disk.

The Mac App Store and Setapp editions include neither the CLI nor the MCP server. Cleanup that an agent runs through Mint counts toward the same cleanup allowance as cleanup in the app.

Connecting your agent over MCP

Running mint-cli mcp starts an MCP server that talks to your agent over standard input and output. It runs on your Mac. Scans and cleanup go through the Mint app, and the other tools read the data Mint already keeps on disk.

1. Download Mint Direct from the Mint website and open it once.
2. Run mint-cli status in Terminal and check that it prints your disk summary.
3. Add an MCP server to your agent’s settings with mint-cli as the command and mcp as the argument.
4. Restart the agent and ask it what is using space on your Mac.

What the agent can see

The server offers eight tools. mint_status and mint_why cover disk trends and where growth came from. mint_scan runs Mint’s own read-only cleanup scan and returns each item with its reason and whether an agent may act on it.

mint_recent and mint_activity read the operation journal and the activity log, mint_agents reads Mint’s last AI agents scan, and mint_rules lists your cleanup rules or does a dry run of one. None of these change anything on disk.

What happens when the agent cleans up

Only mint_execute changes files. It takes the plan ID from a recent mint_scan, the item IDs the agent picked and a short reason, and it never accepts a file path. A plan expires after 15 minutes and works once. Right before touching each file, Mint checks again that it is the same file, that nothing is using it and that it is still allowed.

Everything goes to the Trash, even if the app is set to delete permanently. The result carries the journal batch ID, so you can find that batch in Mint and undo it, and the journal keeps up to 90 days of history. Trashed files still take space until you empty the Trash, so the result reports that figure separately.

Your ignore list applies to agents too

Paths on Mint’s Ignore List keep the level you gave them when an agent asks. A Protected path never shows up in the agent’s scans. A Needs Review path may appear in results, but the agent cannot remove it, so you confirm it in the app.

The journal makes an agent’s work traceable and usually reversible, but it cannot make every choice a good one. Keep version control and backups for work you can’t replace.

Frequently asked questions

Which Mint editions include the CLI and MCP server?

Only the Direct edition you download from the Mint website. The Mac App Store and Setapp editions do not include them.

Can an agent permanently delete files through Mint?

Not through the MCP tools. mint_execute only moves files to the Trash, and anything that needs permanent deletion waits in the Mint app for you.

Will connecting Mint stop my agent from using rm?

Not by itself. The MCP server asks the agent to use mint_execute for cleanup, but it cannot block the shell, so keep your agent’s own permission settings in place.

Try it with one small cleanup

Install Mint Direct, connect mint-cli mcp to your agent and ask it to clear a developer cache. Then open that batch in Mint to see what it did.

Choose your Mint plan