Coding Agent Doctor

A cross-provider health check for Claude Code, OpenAI Codex CLI, and Cursor CLI installations. It inventories binaries, parses configuration layers, checks MCP transports and runners, detects unset MCP environment keys, and produces a redacted support report.

How it differs

Provider-native commands such as Claude Code’s /doctor are best at diagnosing one agent. agent-doctor focuses on semantic quality of instruction files, while ecc-agentshield is a broader security auditor. Coding Agent Doctor focuses on the local runtime and configuration surface shared by multiple coding agents: duplicate binaries, invalid config syntax, MCP transport divergence, missing runners, unset MCP environment keys, and provider-layer drift.

The scan is offline and read-only. It never calls a model, opens credential stores, starts MCP servers, or modifies configuration.

Install

npm install --save-dev coding-agent-doctor
npx agent-doctor --help

Node.js 20 or newer is required.

Run a diagnostic

# All supported providers, human-readable output
npx agent-doctor

# One provider and one project
npx agent-doctor --agent codex --cwd services/payments

# Machine-readable CI artifacts
npx agent-doctor --json > agent-doctor.json
npx agent-doctor --markdown > agent-doctor.md
npx agent-doctor --sarif > agent-doctor.sarif

# Fail on warnings as well as errors
npx agent-doctor --strict

# Write a redacted support bundle
npx agent-doctor bundle --output agent-doctor-report.json

Example:

Coding Agent Doctor

claude   binary=2.1.90   configs=3   mcp=2
codex    binary=0.147.0  configs=1   mcp=1
cursor   binary=1.7.12  configs=2   mcp=3

WARNING AGD006  MCP browser references an unset environment key
  Evidence: BROWSER_TOKEN
  Next: set it in the launch environment or remove the stale MCP entry.

Checks and finding IDs

| ID | Meaning | | --- | --- | | AGD001 | multiple installations of an agent on PATH | | AGD002 | invalid JSON/TOML configuration | | AGD003 / AGD004 | MCP command or runner cannot be resolved | | AGD005 | same MCP server differs between configuration layers | | AGD006 | MCP references an unset environment key | | AGD010 | sensitive field name detected; values remain redacted |

The report also records Node/npm/Git and common runner availability, config scope (managed, user, project, local), MCP transport (stdio, sse, http), URL/command metadata, and source paths.

Output and exit codes

--json is schema-versioned and safe to attach to an issue. --markdown is designed for a support ticket or PR comment. --sarif integrates with code-scanning viewers. Exit code 0 means no errors, 1 means diagnostic errors (or warnings under --strict), and 2/3 means the tool itself could not complete.

Privacy model

• values are never printed; token-shaped strings and credentialed URLs are redacted;
• MCP commands are resolved but not executed;
• no network requests or model calls are made;
• reports contain paths, key names, versions, and evidence needed to reproduce a local setup issue.

Development

npm install
npm run lint
npm test
npm run test:cli
npm pack --dry-run

Issues and pull requests are welcome in the GitHub repository.

License

MIT © Debaditya Hait