# Wsl Cursor Health

> Diagnoses WSL2 and Cursor/Claude performance issues on Windows, including memory, swap, disk, caches, and configuration, then recommends safe fixes.

- Skill: `joshuashepherd/wsl-cursor-health` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds add joshuashepherd/wsl-cursor-health`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/wsl-cursor-health/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra, Productivity, Cloud Platforms, Monitoring & Observability
- Tags: Cache, Cursor, Memory, Performance, Swap, Tsserver, Vhdx, Wsl2
- Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/joshuashepherd/wsl-cursor-health

---


# 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
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
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 --shutdown` from 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*`, or `node_modules` as part of this skill.
- Safe Linux clears require `CONFIRM=1` via `scripts/clear-safe-caches.sh`.
- Windows Cursor `Cache` / `CachedData` clears 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:

1. **TypeScript: Restart TS Server** (tsserver RSS flagged)
2. **Developer: Reload Window** (extensionHost / stale MCP children)
3. Close unused Cursor windows/workspaces on large monorepos
4. Kill obvious orphaned `node`/`vite`/`playwright` children only if clearly stale (confirm PIDs)

## Safe cache clear (Linux)

Only when the probe flagged sizes and the user agrees:

```bash
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:

```powershell
wsl --shutdown
```

Then reopen Cursor / Ubuntu. Re-run `check-health.sh`.

Optional compact (host disk pressure / large `ext4.vhdx`) — details in [reference.md](reference.md).

## Report format

Keep it short:

```markdown
## 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](reference.md).