Windows disk cleanup

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 -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 -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 -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 -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.