agentic-win-cleanup

An agent-first workflow for cleaning up Windows machines that have accumulated startup bloat, vendor updaters, stale services, dev caches, Docker/WSL leftovers, and unexplained idle CPU/GPU power draw.

This is not a debloat preset. There are no opinionated lists of "apps to remove". The whole point is that an agent — Codex, Claude Code, or any other capable LLM agent — investigates your machine, connects findings to your hardware and workflow, asks you the right questions, and proposes a per-item candidate report you review before anything changes.

Why use an agent for this

Most Windows cleanup tools work by matching app names against curated lists. They cannot tell that:

• you have an external USB audio interface, so the Realtek panel may not be your daily-driver audio path;
• you use OEM software for fan control, so disabling the OEM update service is fine but disabling the fan-control service is not;
• you have two clipboard managers in autostart because you switched tools and forgot to remove the old one;
• your HuggingFace model cache is 47 GB and untouched for 5 months but you might come back to ML work next week;
• a vendor "updater" service is running for an app you uninstalled two years ago.

An agent reading the audit output, your installed-app list, your shell history, and asking you 3–5 focused questions can. This repo gives that agent a workflow, a toolbox, and a set of guard rails.

Quickstart

You need: Windows 10/11, an agent (Codex CLI or Claude Code), and an elevated PowerShell session opened in the repo root. winget is recommended (Microsoft Store → "App Installer") because the apply phase uses it as the primary uninstall path.

# 1. Clone
git clone https://github.com/<your-fork>/agentic-win-cleanup.git
cd agentic-win-cleanup

# 2. Open an elevated PowerShell in this directory.
#    Some apply phases require admin. Without it they fail fast — they don't break anything,
#    they just refuse to run. The audit phase works without admin.

With Codex CLI

# In the elevated PowerShell, with codex on PATH:
codex --skill skill/adapters/codex.yaml
# Then in the chat:
> Read skill/SKILL.md and skill/references/lessons-learned.md, then guide me through
> cleaning up this Windows machine. I want it to feel faster but I haven't pinned down
> what's slow. Audit first, ask me questions, write cleanup-candidates.md, and stop
> for my review before applying anything.

With Claude Code

# In the elevated PowerShell, with claude on PATH:
claude
# Then in the chat:
> Load skill/adapters/claude-code.md and skill/SKILL.md as a skill, then walk me
> through the workflow. Start with the audit phase. I want my Windows to feel
> faster — no specific complaint, just generally clean it up.

With any other capable agent

The skill is plain markdown + PowerShell. Tell the agent to read skill/SKILL.md first, follow the workflow, use skill/references/ for deeper guidance per area, and run the scripts in scripts/audit/ → scripts/apply/ → scripts/verify/ in that order. The agent must be able to read files and execute PowerShell.

Safety model

• Nothing changes until you've reviewed cleanup-candidates.md and the agent has produced approved-actions.json from it.
• Backups (registry, services, scheduled tasks) are exported to runs/<date>/backup-*/ before any apply phase runs.
• Default reversibility tier: move shortcut → remove Run value → service Manual → service Disabled → uninstall → delete files. The agent picks the most reversible option that achieves the goal.
• Hard stops: never disable Defender, Firewall, Windows Update, core networking, core audio, or RPC; never delete C:\ProgramData\Package Cache. See skill/references/safety-rules.md for the full list.

What's in here

skill/                      The skill — load this into your agent
  SKILL.md                    Source-of-truth workflow (agent-agnostic)
  adapters/
    codex.yaml                Codex CLI adapter
    claude-code.md            Claude Code adapter
  references/
    discovery-playbook.md     What to look for, with examples
    candidate-report-format.md  Vertical-block format for the review doc
    gpu-idle-investigation.md   The chain for "GPU idle but fans loud"
    fan-and-cpu-diagnostics.md  CPU-side variant (15s delta sampler etc.)
    lessons-learned.md          Common pitfalls — read first
    safety-rules.md             Hard stops

scripts/                    PowerShell toolbox
  lib/Common.ps1              Shared helpers (logging, backups, dispatch)
  audit/                      Read-only data collection
    00-audit.ps1              Baseline audit (Windows version, disks, startup, services, tasks, GPU snapshot, Docker, WSL)
    tools/                    Targeted probes — cpu-delta sampler, gpu-snapshot,
                                startup-shortcut-resolver, stale-data-hoards, docker-stale-containers
  apply/                      Apply phases — all driven by approved-actions.json
    01-backup.ps1             Registry / services / scheduled-tasks backup
    10-startup-user.ps1       HKCU Run, user Startup folder
    20-startup-machine-admin.ps1   HKLM Run, common Startup (elevated)
    30-services-admin.ps1     Service start types (elevated)
    40-scheduled-tasks.ps1    Disable scheduled tasks
    50-uninstall-apps.ps1     winget-first uninstall, fallback to UninstallString discovery
    60-cache-cleanup.ps1      Rebuildable dev caches, %TEMP% age cutoff
    70-docker-cleanup.ps1     Stop/remove containers, prune images/volumes/builders
  verify/
    90-verify.ps1             Post-apply diff baseline + targeted re-checks
    99-post-reboot-verify.ps1 Detect re-grown entries (Office shortcuts, app self-restoring Run values, services flipped by Windows Update)

examples/
  approved-actions.example.json    Schema for the agent-generated approval JSON
  cleanup-candidates.example.md    What the candidate report looks like

runs/                       Local per-run state (gitignored except .gitkeep)

How a run works

0. Pick a run id          runs/2026-01-15/
1. Discovery              scripts/audit/00-audit.ps1 + targeted probes
2. Reasoning              agent reads CSVs, cross-checks system state, infers patterns
3. Ask the user           3–5 focused questions for missing context
4. Candidate report       agent writes runs/<date>/cleanup-candidates.md (vertical blocks)
5. → User edits decisions  per-block "decision: YES / NO / LATER / ASK / note"
6. Approval JSON          agent translates approved blocks → runs/<date>/approved-actions.json
7. Backup                 scripts/apply/01-backup.ps1
8. Apply phases           one at a time, each as a separate hidden process
9. Verify                 scripts/verify/90-verify.ps1
10. (Optional) reboot
11. Post-reboot           scripts/verify/99-post-reboot-verify.ps1
12. State                 update runs/<date>/state.md so the next run can resume

The apply scripts are data-driven: they read approved-actions.json and dispatch to helpers in Common.ps1. No app names are hardcoded anywhere in scripts/.

What you should expect

1. The agent runs the read-only audit and reads the CSV/text reports under runs/<date>/reports/.
2. The agent asks you a few focused questions (3–5) about your daily workflow, what's slow, what hardware you have, what apps you actually use.
3. The agent writes runs/<date>/cleanup-candidates.md. Stop. Read every block. Edit decision: per item.
4. The agent translates your decisions into runs/<date>/approved-actions.json and shows you a summary before running anything.
5. Each apply phase runs as a separate hidden process with a timeout. If one hangs, only that phase is affected.
6. After all phases, the agent runs verification. If it recommends a reboot, do it, then run the post-reboot verify so the agent can spot any entries that regrew.

If you want to test individual phases by hand (without the agent), they all take a -RunId parameter:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\audit\00-audit.ps1 -RunId 2026-01-15
# ... after the agent has written runs\2026-01-15\approved-actions.json:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\apply\01-backup.ps1 -RunId 2026-01-15
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\apply\10-startup-user.ps1 -RunId 2026-01-15
# Phases with `admin` in the filename require elevated PowerShell.

What this repo deliberately does not do

• No GUI, no installer, no service. It's documentation + scripts.
• No telemetry. No network calls beyond what individual apply actions explicitly need (e.g. winget).
• No "one-click optimize". The whole design assumes a human reviews the candidate report.
• No PowerShell module published to the gallery. The scripts are intentionally short and readable.

Requirements

• Windows 10 or 11.
• PowerShell 5.1 or PowerShell 7.x.
• An agent capable of reading markdown skill docs and invoking PowerShell. Tested mentally with Codex CLI and Claude Code; any agent with file read + shell execution should work.
• winget recommended (used as the preferred uninstall path).

Contributing

See CONTRIBUTING.md. The biggest thing the project needs is more references/ material — documented heuristics for areas (audio production, gaming, content creation, ML, .NET enterprise dev) that the current docs cover only at a generic level.

License

MIT.