---

name: cleaning-wsl-docker description: Reclaims SSD disk space consumed by WSL2/Docker. Use when user reports disk space issues, Docker build failures due to space, or slow WSL performance. Handles Docker prune, cache cleanup, VHDX compaction, and prevention setup. MUST BE USED when "disk full", "out of space", or "VHDX" mentioned.

WSL2/Docker Disk Space Cleanup

Problem

WSL2 stores all data in ext4.vhdx files that:

• GROW automatically when adding files/building Docker images
• NEVER SHRINK automatically when files are deleted
• docker system prune frees space inside WSL but NOT on Windows SSD

Workflow

CopyPHASE 1: Diagnose → PHASE 2: Cleanup → PHASE 3: Compact VHDX → PHASE 4: Prevent

---

PHASE 1: Diagnose

Check VHDX Size

Copy# Find VHDX files and sizes
Get-ChildItem -Path "$env:LOCALAPPDATA" -Recurse -Filter "ext4.vhdx" -ErrorAction SilentlyContinue |
  Select-Object FullName, @{N='SizeGB';E={[math]::Round($_.Length/1GB,2)}}

Check Docker Usage

Copywsl -e bash -c "docker system df -v"

---

PHASE 2: Cleanup (Inside WSL)

Docker Cleanup

Copywsl -e bash -c "
  docker stop \$(docker ps -aq) 2>/dev/null
  docker container prune -f
  docker image prune -a -f
  docker builder prune -a -f
  # CAUTION: Only if volumes are disposable
  # docker volume prune -f
  docker system df
"

Project Caches

Copywsl -e bash -c "cd /mnt/c/path/to/project && \
  rm -rf .mypy_cache .pytest_cache .ruff_cache htmlcov __pycache__ && \
  find . -type d -name '__pycache__' -exec rm -rf {} + 2>/dev/null"

Unbounded Logs

Copywsl -e bash -c "rm -rf main/logs/traces/* main/logs/workflow_test* main/logs/langfuse/*"

---

PHASE 3: Compact VHDX (CRITICAL - Reclaims Windows Space)

IMPORTANT: This phase requires Administrator privileges. The AI agent CANNOT run diskpart directly. You MUST provide manual instructions to the user.

Step 1: Shutdown WSL (AI can run this)

Copywsl --shutdown
wsl --list --running  # Should show "no running distributions"

Step 2: Find VHDX Path (AI can run this)

CopyGet-ChildItem -Path "$env:LOCALAPPDATA" -Recurse -Filter "ext4.vhdx" -ErrorAction SilentlyContinue | Select-Object FullName

Step 3: Update compact-wsl.txt Script

Edit .claude/skills/cleaning-wsl-docker/compact-wsl.txt with the correct VHDX path:

Copyselect vdisk file="C:\Users\USERNAME\AppData\Local\wsl\{GUID}\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit

Step 4: MANUAL USER ACTION REQUIRED

Tell the user to run these commands in Administrator PowerShell:

Copy1. Press Win + X
2. Click "Terminal (Admin)" or "PowerShell (Admin)"
3. Click Yes on UAC prompt
4. Run:

diskpart /s "PROJECT_ROOT/.claude/skills/cleaning-wsl-docker/compact-wsl.txt"

If "file in use" error:

Copywsl --shutdown
taskkill /F /IM wslservice.exe
taskkill /F /IM wsl.exe
:: Wait 10 seconds, retry diskpart

Step 5: Verify (AI can run after user completes)

CopyGet-ChildItem -Path "$env:LOCALAPPDATA" -Recurse -Filter "ext4.vhdx" | Select-Object FullName, @{N='SizeGB';E={[math]::Round($_.Length/1GB,2)}}

---

PHASE 4: Prevent Future Bloat

Update .wslconfig

Add to C:\Users\USERNAME\.wslconfig:

Copy[experimental]
sparseVhd=true           # Auto-reclaim space (WSL 2.0+)
autoMemoryReclaim=gradual

Then: wsl --shutdown to apply.

Weekly Maintenance

Copy# Run in Admin PowerShell
wsl -e bash -c "docker container prune -f && docker image prune -a -f && docker builder prune -a -f"
wsl --shutdown
# Then run diskpart compact

---

Expected Recovery

---

Checklist

• Diagnose: Check VHDX size and Docker usage
• Docker: Prune containers, images, build cache
• Caches: Remove .mypy_cache, .pytest_cache, etc.
• Logs: Clean unbounded log directories
• WSL: Shutdown completely
• VHDX: Compact using diskpart (Admin required)
• Prevent: Enable sparseVhd in .wslconfig