JoshuaShepherd WSL + Cursor health
You are on a Windows PC doing intensive context coding with Cursor (and
often Claude in-app / Claude Code) against Ubuntu on WSL2. When this skill
is invoked, run the probe first, then report findings and remediation in
severity order. Do not jump to wsl --shutdown or cache wipes without evidence.
Invoke immediately
From any workspace (script is absolute-path safe):
bash /home/josh/dev/01-Movemental-Core/my-skills/cursor/wsl-cursor-health/scripts/check-health.sh
Or after install (~/.cursor/skills/wsl-cursor-health → my-skills):
bash ~/.cursor/skills/wsl-cursor-health/scripts/check-health.sh
Parse the trailing MACHINE_SUMMARY line (severity=OK|WARN|CRIT, codes=...).
Progress checklist
wsl-cursor-health:
- [ ] 1 Run check-health.sh
- [ ] 2 Classify severity from MACHINE_SUMMARY + Findings
- [ ] 3 Soft fixes first (reload TS / window) when WARN
- [ ] 4 Safe cache clear only if sizes flagged + user confirms
- [ ] 5 Recommend wsl --shutdown from Windows only when CRIT/swap/session warrants
- [ ] 6 Optional: .wslconfig / VHDX compact guidance
- [ ] 7 Short report: what is wrong, what to do, what not to do
Hard rules
- Detect, then recommend. Never run destructive cleanup unprompted.
- Never run
wsl --shutdownfrom inside WSL as an “agent action” that you expect to continue afterward — it kills the distro (and this session). Tell the user to run it in Windows PowerShell or cmd. - Never delete
~/.cursor/projects, Claude transcripts,.git,.env*, ornode_modulesas part of this skill. - Safe Linux clears require
CONFIRM=1viascripts/clear-safe-caches.sh. - Windows Cursor
Cache/CachedDataclears require Cursor fully quit first. - Prefer soft IDE fixes before VM restart when severity is WARN.
Severity → action
| Severity | Typical signals | Agent response |
|---|---|---|
| CRIT | High swap (≥40% or ≥2GiB), tiny MemAvailable, disk ≥90%, extreme tsserver RSS | Lead with save work → wsl --shutdown from Windows → reopen. Then re-probe. |
| WARN | Moderate swap, elevated RAM, fat caches, long uptime, busy extensionHost | Soft fixes first; optional safe cache clear; shutdown if still bad. |
| OK | No thresholds crossed | Say healthy; mention re-run after multi-hour agent marathons. |
Soft fixes (try before shutdown)
Ask the user (or guide them) in this order when WARN and swap is not critical:
- TypeScript: Restart TS Server (tsserver RSS flagged)
- Developer: Reload Window (extensionHost / stale MCP children)
- Close unused Cursor windows/workspaces on large monorepos
- Kill obvious orphaned
node/vite/playwrightchildren only if clearly stale (confirm PIDs)
Safe cache clear (Linux)
Only when the probe flagged sizes and the user agrees:
CONFIRM=1 bash ~/.cursor/skills/wsl-cursor-health/scripts/clear-safe-caches.sh npx trash
# or: playwright | vite | all
WSL shutdown (Windows host)
When CRIT swap/memory or long uptime + swap WARN that soft fixes did not clear:
wsl --shutdown
Then reopen Cursor / Ubuntu. Re-run check-health.sh.
Optional compact (host disk pressure / large ext4.vhdx) — details in reference.md.
Report format
Keep it short:
## Verdict: CRIT|WARN|OK — <one line>
### Signals
- ...
### Do now
1. ...
### Optional later
- ...
### Do not
- Auto-shutdown from WSL / wipe project state / delete node_modules
Extra detail
Thresholds, .wslconfig knobs, Windows cache paths, VHDX compact: reference.md.