Choose a download

Windows x64Intel or AMD Windows Arm64Arm / Snapdragon

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

DeveloperPublished 8 min read

When the C: drive turns red, more people now ask Claude Code or Codex to find out why. An agent is good at that part: it can list a hundred folders, recognize that AppData\Local\npm-cache is a package cache and Documents\WeChat Files is chat history, and explain both in plain words. The risk is the next step, when the same agent writes a Remove-Item -Recurse -Force or a del /s /q from its own reading of folder sizes. One wrong quote or backslash in a generated command can point it at the wrong folder, and neither command asks first, uses the Recycle Bin or keeps a record.

This guide shows a safer split. The agent reads and explains, a cleanup tool with a preview does the removing, and you approve in between. The tool here is Mole CLI for Windows, the free PowerShell edition of Mole, together with its official agent skill, which teaches Claude Code, Codex, Cursor and other agents how to use it. The habits carry over to any tool with a dry run.

Why an agent should not clean with Remove-Item

Four things go missing when an agent cleans with raw PowerShell or cmd commands:

  1. A preview. Remove-Item acts when it runs. You approve one line, not the thousands of files it expands to. PowerShell's -WhatIf exists, but nothing makes the agent use it.
  2. A way back. Files removed this way skip the Recycle Bin.
  3. A record. When an app loses its settings next week, nothing tells you whether the cleanup touched them.
  4. A list of what never to touch. A folder called Cache may hold a browser profile's session, a game's saves or a database a running app still writes to.

A cleanup tool built for this already has all four. The agent's work becomes reading its output and asking you. If you want the background on which folders matter, Windows cache cleanup goes through them one by one.

Set it up

Install Mole CLI for Windows with Scoop, then the skill:

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

The skill command needs Node.js and installs the skill for Claude Code, Codex and Cursor; drop the agents you do not use. In Claude Code you can also run /plugin marketplace add tw93/Mole and then /plugin install mole@mole, and in Codex codex plugin marketplace add tw93/Mole and then codex plugin add mole@mole. Use version 1.37.0 or later of the CLI: it added mo analyze --json and mo uninstall --list, the two commands an agent needs most. mo --version shows which one you have.

The four rules the skill gives the agent

  1. Read before changing anything. The agent starts with read-only commands: mo analyze --json for disk usage, mo status --json for CPU, memory and disks, mo history --json for past cleanups, mo uninstall --list for installed apps, and mo clean --dry-run. These are safe to run without asking.
  2. Preview every removal. The agent runs the cleanup with --dry-run first and summarizes it: the total, the largest groups, and whether each is deleted for good, goes to the Recycle Bin, or needs a download to rebuild.
  3. Ask before typing a removing command. Run from an agent, mo clean starts at once with no confirmation, so your yes has to come in the conversation, after the preview.
  4. Leave some steps to you. Uninstalling apps, selection lists, and anything that needs an Administrator PowerShell stay in your own console. The agent gives you the exact command and stops. It never tries to elevate.

The skill also forbids inventing flags (Mole CLI for Windows has no --yes or --force) and forbids falling back to Remove-Item for anything Mole skipped or protected.

What a session looks like

Say you type: "My C drive is almost full. What is using it?"

The agent runs mo --version, sees Windows: on the second line and switches to the Windows rules. Then mo analyze --json returns an overview of your user folders and drives, with sizes in bytes, a scan_status of complete, partial or unavailable, and insight: true on known heavy places such as old Downloads, Temp and package-manager caches. For a closer look it runs mo analyze --json D:\ or the path of the largest folder.

It then sorts what it found:

Found Where it goes
Temp files, app and browser caches, logs mo clean
Windows Temp, system logs, error reports and memory dumps mo clean --system, run by you as Administrator
Build output and node_modules inside projects mo purge, run by you
An installed app you no longer use mo uninstall, run by you
Documents, photos, videos, game libraries, virtual machines Your call; no Mole command removes them

Then, if you want space back, it runs mo clean --dry-run. Every candidate path goes to %USERPROFILE%\.config\mole\clean-list.txt, which the agent can read to answer "are my Chrome passwords in there?" before anything happens. Only after your yes does it run mo clean. On Windows mo clean does not empty the Recycle Bin. Game replays and GPU shader caches stay out unless you ask for --game-media or --gpu-shaders, because games rebuild shaders slowly on their next launch.

What stays with you, and why

Administrator steps. mo clean from an agent covers your user account only. For system-wide caches, open PowerShell with "Run as administrator" and run mo clean --system --dry-run, then mo clean --system. If your administrator account is a different Windows user, that shell has its own profile folder, so its whitelist and logs are separate from yours.

Uninstalling apps. The agent can find the app in mo uninstall --list, which reports each app's name, source (registry or Microsoft Store), publisher, version and size. The uninstall itself is a selection list, so you run mo uninstall --dry-run first to see which uninstaller each app would use, then mo uninstall and type to search for the app. Mole runs the vendor's own uninstaller, which decides what it removes inside its folder, then moves a verified leftover install folder to the Recycle Bin. Some uninstallers show their own UAC prompt or wizard. For what usually stays behind, see what apps leave behind after uninstall.

Project folders and System File Checker. mo purge opens a selection list, so it runs in your console. mo optimize ends with a question about running System File Checker, which takes several minutes; that answer is yours too.

Check afterwards

After a real run, the agent reads the command summary and mo history --json --limit 1, then reports what was removed and what was skipped, without retrying the skips. The history is kept in %USERPROFILE%\.config\mole\operations.log. Previews are not logged, so only real removals appear there.

That log also answers "did Mole delete my file?" weeks later. The agent searches mo history --json --limit 200 for the path. No match means Mole has no record of removing it, not proof that nothing else did.

To keep a folder out of every future cleanup, ask the agent to protect it. With your agreement it adds the path to %USERPROFILE%\.config\mole\whitelist.txt, saved as UTF-8 with a byte order mark so Windows PowerShell 5.1 reads non-English paths correctly, and confirms with a fresh mo clean --dry-run.

If you use a different tool

The rules are not specific to Mole. With any other tool, start the session with something like:

Before removing anything: show me the list first and tell me which items go to the
Recycle Bin and which are deleted permanently. Use the tool's preview or -WhatIf mode,
never Remove-Item -Recurse -Force or del /s. Do not elevate or ask for an administrator
shell. Wait for my yes before any command that removes files, and afterwards tell me
what was removed and what was skipped.

FAQ

Which AI agents can use the Mole skill on Windows?

Claude Code, Codex and Cursor are named in the install command, and npx skills can install it for other agents that read skill files. The agent needs a shell on your PC; Windows PowerShell 5.1 and PowerShell 7 both work.

Can the agent delete files without asking?

The skill tells it to preview first and wait for your yes, but that is an instruction, not a lock. Keep your agent's approval prompts on for shell commands, and do not pre-approve mo clean or Remove-Item in its settings. Uninstalls and Administrator cleanup cannot run from the agent at all.

Will it delete my Recycle Bin or my game saves?

mo clean does not empty the Recycle Bin on Windows, and it skips game media and shader caches unless you ask. Game saves and libraries are user data that no Mole command removes. An app's own uninstaller can still delete data inside its folder, which is why the agent hands uninstalls to you.

Is Mole CLI for Windows free?

Yes, it is open source under GPL-3.0, and the skill lives in the same repository. Mole for Windows is a separate paid app with a window; the differences are in Mole CLI for Windows vs Mole for Windows.

Does the same setup work on a Mac?

Yes. The skill reads mo --version and uses the macOS commands there, where uninstalled apps go to the Trash and mo clean empties it by default. The Mac version of this guide is How to Use Claude Code or Codex to Free Up Space on Mac Safely.