Windows Disk Cleanup

---
name: windows-disk-cleanup
description: Free space on a full Windows drive without losing user data - find what is consuming the system drive, delete only regenerable caches, and relocate the rest to another drive via NTFS junctions or environment variables. Use whenever the user mentions a full or nearly full C drive, low disk space on Windows, a huge AppData folder, "C盘满了", "C盘爆红", "C盘清理", "磁盘空间不足"; wants to move any cache, AppData folder, package cache, or app data directory to another drive (NuGet, npm, pip, Playwright, Cargo, Unreal Engine DDC, Feishu/Lark, Slack, Discord, NVIDIA shader cache, Claude transcripts); asks whether a cache or app folder is safe to delete, or whether deleting it will log them out, lose chat history, or break the app; or asks what is taking up space on their system drive - even if they never say "cleanup". Also use when a Windows disk is near full and apps behave strangely, since a full volume silently corrupts SQLite databases.
license: MIT
---

# Windows Disk Cleanup & Relocation

Recover space on a full Windows system drive **without losing a single piece of user
data**, and make the space stay recovered.

## Deleting is the easy half; the space comes back

A cleanup that only deletes is undone in about two weeks. Measured on one workstation
13 days after a run:

- Deleted-only locations regrew **11.25 GB** on C: (`%LOCALAPPDATA%\Temp` 10.94 GB,
  NVIDIA `DXCache` 0.31 GB) - roughly **0.87 GB/day**.
- Relocated applications produced **5.32 GB** of new data over the same period, and
  **none of it landed on C:** - including 5.76 GB of new chat-client cache.

That difference is the point of this skill. A junction is a filesystem-level redirect
resolved below the application layer, so the app keeps opening the path it always
used and never learns its data moved - which means its *future* growth follows the
link automatically. **So wherever something is too valuable to delete or certain to
regrow, relocate it rather than just clearing it.** Deleting alone means doing this
again next month.

The second reason to act, and to act early: a Windows volume that runs to zero bytes
does not fail loudly. It silently corrupts whatever was mid-write. In the incident
this skill was built from, a full C: drive truncated Chrome's `History` SQLite
database into an empty shell, and Chrome kept running without recording anything
until it was restarted - the loss was discovered days later, and the pre-incident
history was unrecoverable locally. Treat "the disk is nearly full" as an active
data-loss risk, not a housekeeping chore - and never let the cleanup itself be the
thing that destroys data. Everything below is built around that.

## The one rule

> Anything that can be regenerated by re-downloading or re-computing may be deleted.
> Anything a human created, received, or accumulated gets **moved, never deleted** -
> and only after a byte-level verification proves the copy is intact.

When you cannot confidently classify something, it is user data. Ask.

## Workflow

### 1. Measure before touching anything

Run the scanner. Never guess at what is big, and never delete based on a folder name.

```powershell
powershell -ExecutionPolicy Bypass -File scripts/Scan-DiskUsage.ps1 -Path C:\ -MinGB 0.3
```

It walks with a manual stack over .NET `EnumerateFileSystemInfos` and **skips
reparse points**, which matters because directory junctions would otherwise be
counted twice (or recursed infinitely) and hand you a fictional number. It also
survives permission-denied subtrees instead of aborting.

Drill down where the mass actually is - typically `C:\Users\<user>\AppData`,
`C:\ProgramData`, `C:\Windows\Installer`, and per-app data directories.

### 2. Classify every candidate

Read `references/app-cache-atlas.md` before deciding anything about a specific
application. It lists, per app, which subdirectories are pure regenerable cache and
which hold login state, message history, or drafts. The distinction is often *inside*
a single folder - e.g. in Chromium-based apps `Service Worker\CacheStorage` is
disposable but `Service Worker\Database` is not.

Three buckets:

| Bucket | Action | Examples |
|---|---|---|
| Regenerable cache | Delete | `Cache\Cache_Data`, `Code Cache`, `GPUCache`, shader caches, installer leftovers, driver download packages |
| Bulky but wanted | **Relocate** to another drive | package caches, engine DDC, chat app data directories, agent session transcripts |
| User data / risky | Leave alone, or let the user move it via the app's own settings | chat databases, browser profiles, project files, restore points |

Anything you are unsure about goes in bucket 3.

### 3. Propose, then let the user choose

Present a table: item, size, what it is, what happens if it goes. Ask about anything
that touches an application's own data directory. Do not silently widen scope - a user
who approved "clear caches" did not approve "delete the browser profile".

Never touch, unless the user explicitly and specifically asks:

- Browser profiles and history (`Chrome\User Data`, `Edge\User Data`, Firefox profiles)
- Chat application message stores (WeChat, WeCom, QQ, Telegram, Slack)
- Volume Shadow Copies / System Restore points
- `C:\Windows\WinSxS` (never delete by hand; only `DISM /StartComponentCleanup`)
- Anything under a user's Documents / Desktop / project directories

### 4. Delete the safe set

```powershell
powershell -ExecutionPolicy Bypass -File scripts/Invoke-SafeClean.ps1 -WhatIf
```

`Invoke-SafeClean.ps1` is **dry-run by default**. It only removes paths matching an
explicit allowlist of cache patterns, reports the size of each, and degrades to
best-effort per-file deletion when a directory is partially locked rather than failing
the whole batch. Review the dry-run output with the user, then re-run with `-Execute`.

Close the owning application first. `Rename-Item` on the target directory is a cheap,
side-effect-free **lock probe**: if the rename succeeds nothing holds a handle and the
delete or move will succeed; if it fails, a process still has the directory open and
you should stop rather than force it.

### 5. Relocate what should not be deleted

Read `references/relocation-methods.md` to choose the mechanism. In order of
preference:

1. **The application's own setting** - always best; the app knows about it.
   (WeChat/WeCom storage location, JianYing draft directory, Steam library folders.)
2. **An environment variable** the toolchain respects -
   `NUGET_PACKAGES`, `PLAYWRIGHT_BROWSERS_PATH`, `PIP_CACHE_DIR`, `UE-LocalDataCachePath`.
3. **An NTFS directory junction** - for the majority of apps, which offer no setting
   at all. Applications treat a junction as a real directory; no app-level support
   needed.

Use the script, which enforces the safety sequence:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/Move-AppData.ps1 `
  -Source "$env:APPDATA\SomeApp" -Destination "D:\AppData\SomeApp"
```

**The four steps are not optional and not reorderable:**

1. `robocopy /E /COPY:DAT /DCOPY:DAT` the source to the destination.
2. **Verify** - independently recompute total bytes *and* file count on both sides
   and require an exact match. Do not trust robocopy's summary; recount.
3. Only then delete the source.
4. `mklink /J` the original path to the new location.

If step 2 does not match, stop and report. Never delete a source you have not proven
was copied. This ordering is what makes the operation safe to interrupt: at every
moment before step 3, the original data is still fully present.

Rules that keep this from going wrong:

- Junctions work **within the same machine, NTFS to NTFS**. Do not point one at a
  network share, a removable drive that may be absent at boot, or a non-NTFS volume.
- Never junction a directory the OS needs before the target volume mounts.
- Environment variables set with `setx` / `[Environment]::SetEnvironmentVariable(...,'User')`
  only reach **newly started** processes. Tell the user to restart their IDE/terminal.

### 6. Verify, and restart the app

```powershell
powershell -ExecutionPolicy Bypass -File scripts/Test-Migration.ps1
```

Confirms free space, that each junction resolves to its intended target, and that
environment variables are set. Then **start the relocated application and confirm new
writes are landing on the destination drive** - a junction that silently failed looks
identical to one that worked until you check.

Report honestly: free space before/after, what was deleted, what was moved where,
and anything that could not be completed.

## Platform pitfalls

Read `references/windows-pitfalls.md` before writing any PowerShell for this task.
The short version, all of which cost real debugging time:

- **Write helper `.ps1` files in pure ASCII.** Windows PowerShell 5.1 reads a UTF-8
  file without BOM as ANSI. Non-ASCII characters in comments corrupt the byte stream
  and can *swallow adjacent statements* - variables silently become `$null` and the
  script half-runs without ever erroring.
- **`robocopy` exit codes are not booleans.** Anything below 8 is success (`0` = nothing
  to copy, `1` = files copied). Testing `$?` or `$LASTEXITCODE -ne 0` will report
  a perfectly good copy as a failure.
- **Do not parse localized tool output.** On non-English Windows, `robocopy` and `DISM`
  emit localized (and frequently mojibake'd) text. Compute sizes yourself.
- Elevation is required for `C:\ProgramData`, `C:\Windows\Temp`, and `mklink`.

## Reference files

- `references/app-cache-atlas.md` - per-application: what is safe to delete, what must stay, where the data lives. **Read before touching any named app.**
- `references/relocation-methods.md` - choosing between app setting / environment variable / junction, with a per-app table.
- `references/windows-pitfalls.md` - PowerShell, encoding, robocopy, locking, and permission gotchas.
- `references/case-study.md` - a fully worked run that recovered 43.7 GB, with the actual numbers and what each decision was.