Agent skill
cleaning-wsl-docker
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.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/cleaning-wsl-docker
SKILL.md
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 prunefrees space inside WSL but NOT on Windows SSD
Workflow
PHASE 1: Diagnose → PHASE 2: Cleanup → PHASE 3: Compact VHDX → PHASE 4: Prevent
PHASE 1: Diagnose
Check VHDX Size
powershell
# 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
bash
wsl -e bash -c "docker system df -v"
PHASE 2: Cleanup (Inside WSL)
Docker Cleanup
bash
wsl -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
bash
wsl -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
bash
wsl -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)
powershell
wsl --shutdown
wsl --list --running # Should show "no running distributions"
Step 2: Find VHDX Path (AI can run this)
powershell
Get-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:
select 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:
1. 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:
cmd
wsl --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)
powershell
Get-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:
ini
[experimental]
sparseVhd=true # Auto-reclaim space (WSL 2.0+)
autoMemoryReclaim=gradual
Then: wsl --shutdown to apply.
Weekly Maintenance
powershell
# 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
| Action | Recovery |
|---|---|
| Docker image prune | 2-10 GB |
| Docker builder prune | 10-100 GB |
| Cache cleanup | 200-500 MB |
| VHDX compaction | 5-50 GB |
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
Didn't find tool you were looking for?