Env Doctor

Development Environment Doctor · env-doctor

"Doctor Family" third piece: claude-md-doctor (config) → skill-doctor (skills) → env-doctor (environment). The first two examine files, this one examines the machine.

How It Differs from Off-the-Shelf Cleaners (Read This First – It Defines All Behavior)

Off-the-shelf Mac cleaners answer "which directory is big." This tool answers "do you still use this tool."

Size can be scanned; identity can only be inferred — to tell if nvm is leftover, you must simultaneously check who shell configs load, who's in PATH, who actually provides node, and how long the directory has been untouched. This is the only differentiator of this tool, and no change should weaken it.

---

⛔ Three Iron Laws (see details in references/safety.md)

1. Deletion only comes from user per-item selection (via scripts/clean.sh). The model itself does not compose rm to run; if the user says "just delete it for me" → guide them to run the selector. Default: nothing selected, data classes locked, only whitelisted commands run, user must input yes to proceed.
2. Read-only scanning. scripts/scan.sh contains no write operations.
3. If unsure, say unsure. When signals conflict, label it honestly, don't guess for a prettier report.

---

Standard Workflow

Step 1 · Scan

bash scripts/scan.sh                      # Full scan (includes home directory large-folder discovery, ~30–60 sec)
bash scripts/scan.sh --quick              # Quick scan (skips discovery scan, ~20 sec)
bash scripts/scan.sh --profile ai-dev     # Quick scan for AI dev machine (Agent host directory + skip large-folder discovery)

Outputs six sections of raw data: DISK · SIZES · MANAGERS · RUNTIME · AI_AGENTS (if Agent host present) · DISCOVER (full scan only).

Step 2 · Classification

Compare against references/rules.md:

• Three-class method (data / cache / leftover) assigns an identity to each directory;
• Four-signal decision table (shell_loaded × cmd_in_path × runtime owner × last_modified) determines whether a version manager is active or leftover;
• Same version installed by two managers → list as a separate note.

Step 3 · Report

Follow the four-step conversation flow in references/report.md: give the conclusion first → present in three groups (leftovers → cache → data) → ask the user per group → generate command block only after confirmation.

⚠️ Don't dump dozens of lines at the user at once; ⚠️ Every suggestion must include five elements: "what it is / how big / why classified / official command / cost".

Step 4 · When Cleaning, Hand Over to the Selector

bash scripts/clean.sh --dry-run   # Preview without executing (strongly recommended first time)
bash scripts/clean.sh             # Select and clean after checking

Interactive selection: Space to select · ↑↓ to move · a for all · n for none · Enter to confirm · q to quit. Data classes have 🔒 lock and cannot be selected; the confirmation page lists each command and its cost, then prompts for yes to proceed.

---

Routing

What to do	Which to read
Determine which class a directory belongs to and its official cleanup command	references/rules.md
How to write the report and guide the conversation	references/report.md
Boundaries and what is absolutely forbidden	references/safety.md
Scanner implementation and self-checks	scripts/scan.sh
Cleanup selector (the only place deletion is allowed)	scripts/clean.sh

Standard Answers to Common Follow-ups

• "Just delete it for me" → I won't press Enter for you. Run bash scripts/clean.sh to select items; it will first show you the commands and costs. If you want to preview without executing, add --dry-run.
• "Can I delete the largest one" → Check identity first, not size. The largest is often model weights or container volumes (data class), which should precisely not be deleted.
• "What happens after deletion" → Every item has a "cost" column; cache items always "will redownload, costing time and bandwidth", while leftover items are pure gain.
• "Why classify this as leftover" → Report the original four signals so the user can verify themselves.

Boundaries

• Only covers development tool usage (version managers / package managers / build caches / containers / AI models). System caches, photos, email attachments, and WeChat are out of scope — leave those to the system "Storage" pane.
• Scans within the home directory only; does not touch system directories or other users.
• No network access, no upload of any scan results.

Doctor Family Cross-links

Layer	Skill	When to Hand Off
Config	hekouwang-claude-md-doctor-skill	AGENTS.md/CLAUDE.md duplicates, routing errors, missing frontmatter
Skills	hekouwang-claude-skill-doctor-skill	SKILL.md structure, dead links, OpenClaw declaration
Environment	this skill	Disk full, version manager leftovers, AI host directory bloat

If the report finds config/skill issues, name the other two doctors and do not perform file content audits within this report.