Skip to content
claudemods

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

Install inside Claude Code:

/plugin install env-doctor --marketplace YeonwooSung/my-claude-code-mods
All install options ↓

What 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. 1.One line, inside Claude Code

    /plugin install env-doctor --marketplace YeonwooSung/my-claude-code-mods

    Paste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.

  2. 2.From your shell

    claude plugin marketplace add YeonwooSung/my-claude-code-mods
    claude plugin install env-doctor@my-claude-code-mods

    Then run /reload-plugins in any session that is already open.

  3. 3.Try it without installing

    git clone https://github.com/YeonwooSung/my-claude-code-mods
    claude --plugin-dir ./my-claude-code-mods/env-doctor

    Loads 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, and node -- <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): only package.json in 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 set or 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} and tool.call as hooks without a .catch. The command hook answers only /env-doctor. The tool.call hook returns next(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 malformed means the project directory has no valid package.json object. Start Claude Code in the project root.
  • UNKNOWN (binary unavailable) means that program is not on PATH.
  • UNKNOWN next 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 node on PATH, because the helper is a Node script. Without it, variables show UNKNOWN (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.
>_ assumption-tracker

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

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.