Env Doctor, a Claude Code environment check mod for Node versions and env vars
A /env-doctor command that checks Node and package manager versions against package.json and reports env var presence.
Permissions
- Reads filesCan read files and list directories on your machine ($.fs.read / list / stat / exists).
- Runs commandsCan run shell programs on your machine ($.process.run / spawn). Check the source for exactly which ones.
- Intercepts tool callsSees every tool call Claude makes (tool.call / tool.check) and could block or change it.
- Changes the UIDraws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
- Adds commands/toolsRegisters new slash commands or tools that you or Claude can invoke ($.command.register / $.tool.register).
- Stores dataKeeps data between sessions in the plugin's private store ($.store.*).
- tested with
- v2.1.310
- last tested
- requires
- Claude Code ≥ 2.1.287
- surfaces
- none
- source
- YeonwooSung (Apache-2.0)
Install inside Claude Code:
/plugin install env-doctor --marketplace YeonwooSung/my-claude-code-modsWhat does this mod do?
Env Doctor is a community mod by YeonwooSung (YeonwooSung), one plugin in the my-claude-code-mods collection. It adds a /env-doctor command that works as a Claude Code environment check: it compares the Node.js and package manager versions installed on your machine with what the project's package.json asks for, and it tells you whether the environment variables you care about are set.
The report is plain text returned by the command, with one line per item. A typical run prints a header, then lines such as node: v22.4.0 — MATCH >=20 and DATABASE_URL: SET. Each version line ends in MATCH, MISMATCH or UNKNOWN. Variable lines say SET, MISSING or UNKNOWN. The commands are:
/env-doctor check(also the default with no argument): run the checks./env-doctor require <ENV_NAME>: remember a variable name, then run the checks./env-doctor reset: forget the remembered names./env-doctor help: print the usage line.
It does not edit your project, call the model, or fix anything. It only reports.
Install
Use any of the methods in the install block; they install from the author's own marketplace, my-claude-code-mods. Reload plugins or restart Claude Code afterwards, then run /env-doctor help. To try it without installing, the author's README suggests claude --plugin-dir ./env-doctor from a checkout of the repository.
$ install env-doctor
Requires Claude Code ≥ 2.1.287
Installs from the author's own marketplace: YeonwooSung/my-claude-code-mods
1.One line, inside Claude Code
/plugin install env-doctor --marketplace YeonwooSung/my-claude-code-modsPaste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.
2.From your shell
claude plugin marketplace add YeonwooSung/my-claude-code-mods claude plugin install env-doctor@my-claude-code-modsThen run /reload-plugins in any session that is already open.
3.Try it without installing
git clone https://github.com/YeonwooSung/my-claude-code-mods claude --plugin-dir ./my-claude-code-mods/env-doctorLoads the mod for one session only. Nothing is added to your settings.
How it works
The plugin is one hooks module, hooks/register.ts. On session.start it registers the command; command.run answers only /env-doctor. The process port is deliberately narrow: only node, npm, pnpm and yarn with exactly --version are allowed, and anything else throws.
io.run = argv => {
if (argv.length !== 2 || argv[1] !== '--version') throw new Error('Only version probes are supported')
switch (argv[0]) {
case 'node': return $.process.run(['node', '--version'], { cwd, timeoutMs: 10_000 })
case 'npm': return $.process.run(['npm', '--version'], { cwd, timeoutMs: 10_000 })
// pnpm and yarn follow the same pattern
default: throw new Error('Unsupported version program')
}
}The version comparison is a small hand-written semver function in hooks/core/feature.ts. For variable names it runs the bundled hooks/env-presence.mjs with node, passing the validated name. The list of required names is saved with $.store, keyed by the working directory and session id, so resuming the same session restores it.
Customize it
There are no /config options. The only settings are the variable names you add with /env-doctor require <NAME>; names must match [A-Za-z_][A-Za-z0-9_]*, and the list keeps at most 200 entries. Engine requirements come from your own package.json, so to change what is checked, edit engines or packageManager there.
Permissions & safety
We read every file the plugin can execute before running it: hooks/register.ts, hooks/core/feature.ts, hooks/core/runtime.ts, hooks/core/redact.ts, hooks/env-presence.mjs, hooks/hooks.json and the manifest, plus the two test files. There is no package.json, install script, binary or minified code, and we found no hidden Unicode. Here is what we found:
- Runs commands (
$.process.run):node --version,npm --version,pnpm --version,yarn --version, andnode -- <plugin-root>/hooks/env-presence.mjs <NAME>. Each is an argument array with no shell and a 10-second timeout. The programs are resolved from your PATH. - Reads files (
$.fs.read): onlypackage.jsonin the current project directory. - Writes: only to the plugin's own store (
$.store), holding the required variable names. Nothing is written to~/.claude, settings, shell files or the project. - Environment variables: the helper checks whether a name exists and prints
setor nothing. Values are not read or returned. - No network, no telemetry, no daemon, and no text injected into prompts.
- Gating hooks: validate lists
command.run{command=env-doctor}andtool.callas hooks without a.catch. The command hook answers only/env-doctor. Thetool.callhook returnsnext(e)unchanged; the observation branch is disabled here, so it never reads, delays or alters a tool call. - Redaction: the mod masks obvious secrets and terminal escapes in text it stores or prints. The author calls this best effort.
The repository carries an Apache-2.0 LICENSE at its root (the plugin folder has none of its own). claude plugin validate reported no errors or warnings. The author's 10 tests passed on Claude Code 2.1.310.
- Reads files
- Can read files and list directories on your machine ($.fs.read / list / stat / exists).
- Runs commands
- Can run shell programs on your machine ($.process.run / spawn). Check the source for exactly which ones.
- Intercepts tool calls
- Sees every tool call Claude makes (tool.call / tool.check) and could block or change it.
- Changes the UI
- Draws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
- Adds commands/tools
- Registers new slash commands or tools that you or Claude can invoke ($.command.register / $.tool.register).
- Stores data
- Keeps data between sessions in the plugin's private store ($.store.*).
Compatibility & troubleshooting
Checked with Claude Code 2.1.310 on macOS (validate and tests); the author reports testing on 2.1.302. If something looks wrong:
package.json manifest unavailable or malformedmeans the project directory has no validpackage.jsonobject. Start Claude Code in the project root.UNKNOWN (binary unavailable)means that program is not on PATH.UNKNOWNnext to a range means the mod does not understand that range syntax, or the version output was cut off. It does not guess.- The presence check needs
nodeon PATH, because the helper is a Node script. Without it, variables showUNKNOWN (presence unavailable). - After installing from the shell into an open session, run
/reload-plugins.
To check that it works, run /env-doctor require PATH and then /env-doctor check in a project with a package.json; PATH: SET should appear.
FAQ
- Does Env Doctor show or store the values of my environment variables?
- No. It only reports SET or MISSING. A bundled helper, hooks/env-presence.mjs, tests the name with Object.hasOwn(process.env, name) and prints either "set" or nothing, so the value is never read into the mod. A variable that exists with an empty value counts as SET.
- Which versions does it check, and against what?
- It reads package.json in the project directory. It runs node --version and compares it with engines.node. For the package manager it uses the packageManager field (npm, pnpm or yarn), or falls back to engines.npm, engines.pnpm and engines.yarn.
- Which version ranges does it understand?
- Exact versions, major or x ranges, the comparators >=, <=, >, < and =, full ^ and ~ ranges, and || alternatives. Anything else, including partial > and <= forms, is reported as UNKNOWN instead of guessed.
- Does it block or change my tool calls?
- No. Its tool.call hook only forwards each call. In the tested version the observer branch is switched off, because the Feature class defines no observe method, so tool calls pass straight through.
- How do I clear what it remembers?
- Run /env-doctor reset. That empties the list of required variable names for the current folder and session. The list lives in the plugin's own store, keyed by working directory and session id.
# Related mods
Assumption Tracker
Log claims with /assume, then confirm or refute each one with written evidence; the history is kept per session.
- none
- Reads files
- Runs commands
- Intercepts tool calls
- Changes the UI
- Adds commands/tools
- Stores data
tested with v2.1.307
Decision Ledger
A /decision command that records a choice, the reason and the rejected alternative, tied to a file or symbol.
- transcript
- Reads files
- Runs commands
- Intercepts tool calls
- Changes the UI
- Adds commands/tools
- Stores data
tested with v2.1.307
More in Slash commands, Timers, todos, standups.