Env Doctor
'Works on my machine', fixed: checks version → deps → env vars → ports → paths in order, and diffs against CI when local breaks but CI passes.
v1.0.0 · ~578 tokens · ⬇ 0 · Updated July 6, 2026
What it does
Diagnoses a broken local dev environment in likelihood order (runtime version mismatch, stale/partial deps, missing env vars, port/service conflicts, path/OS issues) before touching code, then reads the real error last. When it works in CI but not locally, diffs local against the CI config — the diff is the bug. Never prints env var values.
Example uses
Diff local against CI
The test suite is green in CI but explodes on your machine, and the difference between the two is the bug.
Our Jest suite passes in GitHub Actions but fails locally with ECONNREFUSED on port 5432. Diff my local environment against the CI config — Node version, env vars, install command, service containers — and tell me which difference explains the failure.Diagnose a failed dev setup
A new teammate followed the README step by step and the app still refuses to start.
I cloned the repo, ran npm install and npm run dev, and I get 'Cannot find module sharp'. Walk the diagnostic order: my Node version against the project's pinned version, whether my install is stale against the lockfile, my .env against .env.example, then ports — and stop at the first cause that explains it.Fix a broken Python environment
The project ran fine last month and now imports fail after a machine upgrade.
This Django project stopped running after I upgraded my machine — 'ModuleNotFoundError: No module named psycopg2'. Check my python --version against .python-version, whether the venv is stale, and my env vars against .env.example. List the names of anything missing, but never print the values.Install
# 1. Create the skill folder in your Claude setup mkdir -p ~/.claude/skills/env-doctor # 2. Download SKILL.md into it (or move the file you just downloaded) # → ~/.claude/skills/env-doctor/SKILL.md # 3. Claude Code auto-discovers it on next launch.
Inside the skill
--- name: env-doctor description: Diagnose a broken local dev environment fast — "works on my machine", missing env vars, wrong versions, failed install. Use when setup fails, the app won't start locally, or the user says "it won't run", "fix my environment", "works in CI but not locally". Checks the common causes in order. --- # Env Doctor Most "it won't run" bugs are environment, not code. Check the usual suspects in order of likelihood before touching a single line of application logic. ## Diagnostic order (stop at the first that explains it) 1. **Runtime version.** Compare the installed version (`node -v`, `python --version`) to what the project pins (`.nvmrc`, `engines`, `.python-version`, `pyproject`). Mismatch is the #1 cause. Fix: switch to the pinned version. 2. **Dependencies actually installed + current.** Lockfile changed since last install? `node_modules`/venv stale or partial? → clean reinstall from the lockfile. Don't debug against half-installed deps. 3. **Env vars.** Compare `.env` against `.env.example` — missing or empty required keys are a silent killer. List exactly which are absent. (Never print their values.) 4. **Ports / services.** Is the port already in use? Is the DB/redis/service the app needs actually running and reachable? `lsof -i :PORT`, ping the service. 5. **Paths / OS.** Line endings (CRLF vs LF), path separators, case-sensitivity (works on mac, fails on Linux CI), missing system binary. 6. **Read the actual error.** Only now — the real message often names the cause once the environment noise is cleared. ## Compare against CI (the source of truth) If it works in CI but not locally, diff your local against the CI config: versions, env vars, install command, service containers. CI is a clean, reproducible environment — your machine has drift. The diff IS the bug. ## Output ``` ENV DIAGNOSIS Cause: <the first check that failed> Evidence: <version mismatch / missing VAR names / port in use / …> Fix: <exact command or step> Also worth checking: <secondary risks, if any> ``` ## Rules - Work top-down; don't jump to exotic causes while a version mismatch sits unchecked. - Never print env var VALUES — names only. - If everything environmental checks out, THEN it's a code bug — hand off to systematic-debugging.
Changelog
- v1.0.02026-07-03Initial clean-room write.
Frequently asked questions
Is Env Doctor free?
Yes. Env Doctor is free to download and MIT-licensed.
Where do I install Env Doctor?
Place the SKILL.md file in ~/.claude/skills/env-doctor/ and Claude Code auto-discovers it on next launch.
How many tokens does Env Doctor use?
About 578 tokens — it is designed to be token-lean.
We're developers and SaaS builders who use these tools daily in production. Every review comes from hands-on experience building real products — DealPropFirm, ThePlanetIndicator, PropFirmsCodes, and many more. We don't just review tools — we build and ship with them every day.
Written and tested by developers who build with these tools daily.