Env Doctor

Tells a new developer why their AI coding setup is not working, on their own machine, without ever touching a secret value.

THE PROBLEM IT NAMES. "I put my API key in and it still does not work." Usually the key is not missing at all -- it is already set somewhere else, and that somewhere else wins silently. A .env file is parsed and then DISCARDED, because the default loader behaviour does not override a variable already present in the environment. Editing the file changes nothing and reports nothing, so the obvious debugging step -- open the file and check the key is right -- CONFIRMS THE WRONG CONCLUSION.

WHAT IT REPORTS. Which editors and coding agents are actually installed (VS Code, Cursor, Windsurf, Zed, Claude Code, the OpenAI Codex CLI), and for every well-known AI API key: where it is defined, which definition your tools will actually use, and which ones are being shadowed. When two sources disagree it says so, names the winner, and gives one concrete next action rather than a list of possibilities.

IT NEVER HANDLES YOUR KEY. It never prints, logs, stores or transmits a secret value. It reports only WHERE a name is defined, and when two sources hold different values it proves they differ with a one-way fingerprint that carries neither value. A tool that asks for your API key in order to tell you your API key is misconfigured has made the problem worse.

LOCAL ONLY. It reads local files and process.env, checks for known binaries and application directories, and shells out only to --version on a fixed set of known-safe commands. Nothing leaves the machine.

MEASURED, AND IT CORRECTS ITSELF IN PUBLIC. The README ships a real captured transcript, reproduced by evidence/reproduce-shadow.sh -- a .env file holding one value, a shell variable holding a different one, and env -i wiping everything else so the output is deterministic on any machine. The README then states plainly that an earlier draft of its own explanation overclaimed: because the harness runs under env -i, PATH is wiped too, so the app-bundle fallback is exercised by the harness rather than by the absence of a CLI shim on that machine. It is written down rather than quietly restated.

VERIFIED: 110 tests, measured by running the suite. Deliberate defects were applied to the real source and the suite caught every one of them (4 of 4) -- a suite that survives a flipped comparison is not testing that behaviour.

DELIVERY: free, signed download of a hash-verified tarball, immediately. Full source, no card, no trial, no expiry.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function detectTool(spec: ToolSpec, ctx: DetectContext): ToolDetection;
  export function detectAllEditors(ctx: DetectContext): ToolDetection[];
  export function detectAllAgents(ctx: DetectContext): ToolDetection[];
  export function gatherDetectContext(platform: PlatformName, homeOverride?: string): DetectContext;
  export function runDoctor(options: RunDoctorOptions = {}): DoctorReport;
  export function parseEnvFileEntries(text: string): EnvFileEntry[];
  export function parseEnvFileNames(text: string): string[];
  export function readEnvFiles(cwd: string, readFile: FileReader = realReadFile): EnvFileRead[];
  export function readShellRcFiles(home: string, readFile: FileReader = realReadFile): ShellRcRead[];
  export function sourcesForKey(name: string, processEnv: NodeJS.ProcessEnv, files: GatheredFiles): Source[];
  export function fingerprint(value: string): string;
  export function lengthBucket(value: string): "empty" | "short" | "typical" | "long";

  export type FileReader = (path: string) => string | null;
  export type Severity = "critical" | "warning" | "note";
  export type PlatformName = "macOS" | "Linux" | "Windows" | "Unknown";