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

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](/windows/blog/windows-cache-cleanup) goes through them one by one.

## Set it up

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

```powershell
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](/windows/blog/what-apps-leave-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:

```prompt
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](/windows/blog/mole-cli-vs-windows-app).

### 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](/blog/use-claude-code-to-clean-up-mac).

## Related reading

- [C: drive full on Windows](/windows/blog/windows-c-drive-full) for where the space usually goes.
- [Windows developer caches](/windows/blog/windows-developer-caches) for npm, pip, Gradle and the other stores coding tools fill.
- [Find large files on Windows](/windows/blog/find-large-files-on-windows) for doing the same search by hand.


Canonical: https://mole.fit/windows/blog/use-claude-code-to-clean-up-windows