How to Use Claude Code or Codex to Free Up Space on Mac Safely

DeveloperPublished 10 min read

More people now open Claude Code or Codex and type "my disk is full, find out why". It is a good use of an agent: it can read a hundred folders, recognize that ~/Library/Developer/Xcode/DerivedData is build output and ~/Library/Containers/com.tencent.xinWeChat is chat history, and explain both in plain words. The risky part comes one step later, when the same agent writes rm -rf from its own reading of a du listing and runs it against your home folder. A shell command has no preview, no Trash and no record of what it removed.

This guide shows a safer split. The agent does the reading and explaining, a cleanup tool with a preview does the removing, and you approve in between. The tool here is Mole CLI, the free command line edition of Mole, and its official agent skill, which teaches Claude Code, Codex, Cursor and other agents how to use it. The same habits work with any tool that has a dry run.

Why an agent should not delete files with rm

An agent is strong at the fuzzy parts of a cleanup: walking a large folder tree, attributing paths to the apps that own them, and ranking which twelve of four thousand items deserve a look. Deciding that a path is safe to delete is a different kind of problem. It needs the same answer every time and a list you can check, and a model gives neither. The longer argument is in AI Mac cleaners and what the model actually decides.

In practice, four things go missing when an agent cleans with raw shell commands:

  1. A preview. rm acts as soon as it runs. You see the command, not the 3,000 paths it expands to.
  2. A way back. Files removed with rm skip the Trash. Unless you have a backup, they are gone.
  3. A record. Next week, when an app forgets its settings, nothing tells you whether the cleanup touched them.
  4. A list of what never to touch. An agent may not know that a folder named like a cache holds sessions, signing keys or a database another app still writes to.

A cleanup tool built for this already has those four parts. The agent's job becomes reading its output and asking you.

Set it up

Install Mole CLI with Homebrew, then the skill:

brew install mole
npx skills add tw93/Mole -a claude-code codex cursor -g -y

The second command installs the skill for Claude Code, Codex and Cursor in one go; drop the agents you do not use. If you prefer your agent's plugin system, run /plugin marketplace add tw93/Mole and then /plugin install mole@mole in Claude Code, or codex plugin marketplace add tw93/Mole and then codex plugin add mole@mole in Codex. Update the skill later with npx skills update -g -y.

Nothing else needs configuring. The next time you ask about disk space, an app to remove or why the Mac is slow, the agent loads the skill and follows it.

The four rules the skill gives the agent

The skill is a short Markdown file, and most of it is rules rather than commands. These are the ones that matter for your files:

  1. Read before changing anything. The agent answers with read-only commands first: mo analyze --json for disk usage, mo status --json for memory and CPU, mo history --json for past cleanups, mo uninstall --list for installed apps, and every --dry-run. These are safe to run without asking.
  2. Preview every removal. Before a cleanup, the agent runs it with --dry-run and summarizes the result: the total, the largest groups, and for each group whether it is deleted for good, goes to the Trash, or needs a download to rebuild.
  3. Ask before typing a removing command. Run from an agent, mo clean starts the moment it is invoked, with no confirmation, so the agreement has to happen in the conversation first. "Why is my disk full?" is a question, not consent. "Go ahead and clean those" after the preview is.
  4. Leave some steps to you. Uninstalling an app, choosing items from a list, and anything that needs an administrator password stay in your own Terminal. The agent gives you the exact command and stops. It never runs sudo and never asks for your password.

Two smaller rules close the usual escape routes. The agent may use only the commands and flags the skill lists, so it cannot invent a --force. And when Mole skips or protects a path, the agent may not fall back to rm to remove it anyway: a skip is Mole's answer.

What a session looks like

Say you type: "My Mac says the disk is almost full. What is using it?"

The agent runs mo --version to check that it is talking to the macOS edition, then mo analyze --json. That returns the large locations in your home folder with sizes in bytes, a scan_status of complete, partial or unavailable, and flags such as cleanable: true for folders Mole recognizes as caches. It may run mo analyze --json again on the two or three biggest entries to see inside them.

Then it maps what it found to who can deal with it:

Found Where it goes
App caches, logs, leftovers of apps you already deleted mo clean
Build output and dependency folders inside projects mo purge
An installed app you no longer use mo uninstall, run by you
Installers in Downloads mo installer, run by you
Documents, photos, music, virtual machines, iPhone backups Your call; no Mole command removes them

The last row matters as much as the others. A good answer says that 40 GB of it is a Parallels virtual machine and leaves the decision with you, instead of looking for a command that would delete it.

If you want space back, the agent runs mo clean --dry-run. The summary appears in the chat, and every candidate path is written to ~/.config/mole/clean-list.txt, which the agent can read to answer "is my Slack history in there?" before anything happens. It will also tell you that mo clean empties the Trash by default, since people often keep things there on purpose. Only after you say yes does it run mo clean.

What stays with you, and why

Administrator steps. Some system caches need an administrator password. From an agent, mo clean cleans the user-level part and skips the system part, and says so. When you want both, the agent asks you to run mo clean in your own Terminal, where Mole asks for the password itself and does everything in one pass. It will not do half now and half later, because the second run would rescan and repeat the first.

Uninstalling apps. The agent can find the app with mo uninstall --list and show you exactly what would go with mo uninstall --dry-run <name>: the app, its caches, and a "Personal data kept" list of settings and data that stay unless you choose otherwise. The real uninstall refuses to run without a terminal, so you run mo uninstall <name> yourself. Removed files go to the Trash. If an app you removed earlier still left things behind, see how to remove leftover files after uninstalling.

Project folders. mo purge --dry-run lists build output, which rebuilds offline, and dependency folders such as node_modules, which need a download to restore. If you want only some projects cleaned, the agent hands you mo purge, whose selection list lets you pick.

Check afterwards

After a real run, the agent reads the command's own summary and mo history --json --limit 1, then tells you what was removed and what was skipped. It does not retry skipped items: Mole skips files that are in use or protected on purpose.

The log also answers the question that usually comes a week later: "did the cleanup delete my file?" Ask the agent exactly that. It searches mo history --json --limit 200 for the path and anything under it, and reads the full deletions log if the date is older. No match means Mole has no record of removing it, which is not the same as proof that nothing did, and the agent should say it that way.

To keep a folder out of every future cleanup, ask the agent to protect it. It adds the path to ~/.config/mole/whitelist after you agree, then runs a fresh mo clean --dry-run to confirm the path is no longer listed.

If you use a different tool

The skill is specific to Mole, but its rules are not. If you ask an agent to clean with anything else, paste something like this at the start of the session:

Before removing anything: show me the list first and tell me which items go to the
Trash and which are deleted permanently. Use the tool's dry-run or preview mode, never
rm or find -delete. Do not run sudo. Wait for me to say yes before any command that
removes files, and afterwards tell me what was removed and what was skipped.

It will not give the agent a protected-path list or a log that does not exist, but it puts the preview and the decision back where they belong. For what to keep regardless of tool, what Mac cleaners should never delete and which Mac caches are safe to delete go through the folders one by one.

FAQ

Which AI agents can use the Mole skill?

Claude Code, Codex and Cursor are named in the install command, and npx skills can install it for other agents that read skill files. Claude Code and Codex can also install it from their plugin marketplaces. The agent needs a shell on your Mac, so chat-only assistants without a terminal cannot run Mole.

Can the agent delete my files without asking?

The skill tells it not to: removing commands come only after a preview and your yes in the conversation. That is an instruction to the agent, not a lock, so keep your agent's own approval prompts on for shell commands and do not pre-approve rm or mo clean in its permission settings. Uninstalls and administrator steps cannot run from the agent at all; they need your Terminal.

Does cleaning through an agent remove more than the Mole app or the CLI alone?

No. The agent runs the same CLI commands you could type, with the same protected paths and the same preview. What it adds is reading and explaining: which folder belongs to which app, and which command, if any, handles it.

Is the Mole CLI free?

Yes. Mole CLI is open source under GPL-3.0 and the skill is part of the same repository. Mole for Mac is a separate paid app for people who would rather click than type; the agent mentions it at most once, and only when a step suits a window better, such as picking apps to uninstall.

Does this work on Windows?

Yes, with Mole CLI for Windows, which has its own commands and its own rules about the Recycle Bin and administrator steps. The skill reads mo --version and switches to the Windows reference automatically. The Windows version of this guide is How to Use Claude Code or Codex to Free Up Space on Windows Safely.