AgentDoctor

Lighthouse for AI coding agents.

Audit coding-agent configuration before it becomes a repository problem.

AgentDoctor is a local CLI that inspects project-level AI coding agent setup — Cursor, Claude Code, and Codex — for security, instructions, context, and MCP configuration. Deterministic static analysis. No API key. No code upload by default.

npx @praneeth_54/agentdoctor

Public beta (0.3.0-beta). Scan → Fix → Verify. Deterministic scores in the terminal and JSON.

---

What you get

Real scan of the included insecure-agent-project fixture using AgentDoctor v0.3.0-beta.

$ npx @praneeth_54/agentdoctor

🩺 AgentDoctor v0.3.0-beta

Scanning repository...

Repository
  Framework: Node.js
  Language: JavaScript
  Package manager: npm
  Files scanned: 7

AI Coding Agents

✓ Cursor       configured
✓ Claude Code  configured
✓ Codex        configured

Findings

CRITICAL

  ✗ Sensitive environment file may enter agent context
    .env
    Affected: Claude Code, Codex
    Fix: Add an agent-specific exclusion (for example .cursorignore or a
         Claude Code Read deny rule), keep the file out of version control,
         and rotate any credentials that may have been exposed.

  ✗ Private key or credential file present in repository
    test-private-key.pem
    Affected: Claude Code, Codex, Cursor

WARNING

  ! Claude Code bypassPermissions mode enabled
    .claude/settings.json

Summary

  3 critical
  1 warning
  0 info

  Readiness: 13/100
  Category and agent scores: agentdoctor scan --json

Abbreviated text example from the same fixture for accessibility and search. Secret values are never printed. Re-run the scan if counts change.

---

Why AgentDoctor?

Repositories accumulate agent configuration quickly:

• Multiple instruction formats (.cursor/rules, CLAUDE.md, AGENTS.md)
• Stale path references in always-on instructions
• Ignore differences between .gitignore, .cursorignore, and agent defaults
• MCP filesystem scopes that are broader than intended
• Generated directories and large logs that waste context
• Credential-like files that may be readable by agents
• Conflicting assumptions about what each agent can see

Manually reviewing all of that across Cursor, Claude Code, and Codex is slow and inconsistent. AgentDoctor provides one deterministic local audit with stable rule IDs, evidence paths, and affected-agent information.

| Analogy | Domain | | --------------- | -------------------------------- | | Lighthouse | Web pages | | npm audit | Dependencies | | ESLint | Source code | | AgentDoctor | AI coding agent environments |

AgentDoctor analyzes configuration. It does not run agents or call an LLM. agentdoctor fix may append safe context exclusions (Cursor .cursorignore, Claude Code Read deny rules, and Codex filesystem deny keys); it does not rewrite secrets, credentials, or security modes such as bypassPermissions.

---

Before / after

Before

A repository may contain:

.cursor/rules/
AGENTS.md
CLAUDE.md
.claude/settings.json
.mcp.json
.env

Potential problems stay invisible until something leaks into model context, CI, or a teammate’s agent session:

• environment or credential-like files reachable by agents
• stale instruction path references
• broad MCP filesystem access
• oversized always-on context

Run

npx @praneeth_54/agentdoctor

After

You get deterministic findings with:

• stable rule IDs (for example security/env-file-exposure)
• evidence paths
• affected agents when exposure claims are supported
• conservative recommendations
• readiness score (scores.overall in JSON; overall line in the terminal)

Safe context exclusions (Cursor / Claude Code / Codex) can be applied with agentdoctor fix. Security and review findings stay manual — Fix explains why and does not invent unsafe edits.

---

Quick start

One-shot (recommended)

npx @praneeth_54/agentdoctor

Pin a beta version when you need a fixed install:

npx @praneeth_54/agentdoctor@0.3.0-beta

Global (optional)

npm install -g @praneeth_54/agentdoctor
agentdoctor

Scan → Fix → Verify

# 1. Scan (save a baseline for Verify)
npx @praneeth_54/agentdoctor scan . --json > agentdoctor-report.json

# 2. Fix safe context exclusions (preview first with --dry-run)
npx @praneeth_54/agentdoctor fix . --dry-run
npx @praneeth_54/agentdoctor fix . -y

# 3. Verify against the baseline
npx @praneeth_54/agentdoctor verify . --baseline agentdoctor-report.json

fix writes safe context exclusions for Cursor (.cursorignore), Claude Code (permissions.deny Read rules in .claude/settings.json), and Codex (filesystem deny keys under a permissions profile in .codex/config.toml) for findings such as unignored build/ or large logs. Review/manual security findings are listed as skipped — address those yourself, then re-run verify.

Published 0.3.0-beta: npm and Action @v0.3.0-beta still ship Cursor-only Fix (.cursorignore). Claude Code / Codex Fix writers, Action policy inputs, and scan --ci failing on criticals are in this repository’s Unreleased tree (CHANGELOG.md).

Common commands

agentdoctor .
agentdoctor scan . --json
agentdoctor fix . --dry-run
agentdoctor verify . --ci --baseline agentdoctor-report.json
agentdoctor explain security/env-file-exposure
agentdoctor doctor

Package name: @praneeth_54/agentdoctor (npm blocks the unscoped name). CLI binary: agentdoctor. Requires Node.js 20+.

Programmatic API

npm install @praneeth_54/agentdoctor

import { scan, verify, buildFixPlan, applyFixPlan } from "@praneeth_54/agentdoctor";

const result = await scan({ cwd: process.cwd() });
console.log(result.summary);
console.log(result.scores?.overall);
console.log(result.agentSecurityAnalysis); // "full" | "limited"

---

Supported agents

Project-level configuration only (repository files). Global user settings are not scanned.

| Agent | What AgentDoctor inspects | | --------------- | ---------------------------------------------------------------------- | | Cursor | .cursor/rules/*.mdc, .cursorignore, Cursor MCP config, AGENTS.md | | Claude Code | CLAUDE.md, .claude/settings*.json, .claude/rules, MCP config | | Codex | AGENTS.md / overrides, project .codex/ configuration |

Additional adapters are planned — see ROADMAP.md.

---

Finding categories

| Category | Examples | | ---------------- | --------------------------------------------------------------------- | | Security | Env-file exposure, private-key filenames, broad MCP filesystem scopes | | Context | Large instruction files, large logs, unignored generated directories | | Instructions | Empty instructions, duplicate content, missing path references | | MCP | Malformed MCP config, high-risk filesystem path arguments |

Full catalog with severities and fixability: docs/rules.md.

Explain any rule:

npx @praneeth_54/agentdoctor explain security/env-file-exposure

---

Privacy and trust

Scans run locally on your machine.

AgentDoctor:

• does not require an API key
• does not upload repository contents by default
• does not call an LLM for core scanning
• does not execute MCP servers
• does not execute project code
• never prints secret values from files it flags by name
• enforces repository boundary checks for path references and symlink escape

This is still software that reads untrusted repository trees. Treat findings as guidance, not a security certification. AgentDoctor is not a complete secret-content scanner.

---

CI usage

GitHub Action

Run AgentDoctor directly in a workflow:

Published Action @v0.3.0-beta is report-only (path, version, output-file):

permissions:
  contents: read

steps:
  - uses: actions/checkout@v4

  - name: Audit coding-agent configuration
    id: agentdoctor
    uses: pranee54/AgentDoctor@v0.3.0-beta
    with:
      path: .
      output-file: agentdoctor-report.json

  - name: Upload AgentDoctor report
    uses: actions/upload-artifact@v4
    with:
      name: agentdoctor-report
      path: ${{ steps.agentdoctor.outputs.report-path }}

Policy inputs (minimum-score, fail-on-severity, fail-on-rule, fail-on-new, verify-baseline, summary, annotations) exist in this repository’s Unreleased action.yml and matching CLI. Do not pass them to @v0.3.0-beta — that tag ignores them. Use this repo’s Action revision (or a later release tag) with a matching CLI (version pin or version: workspace). The action installs @praneeth_54/agentdoctor (pin via version), runs scan (or verify when verify-baseline is set) with --json, and writes the report inside the workspace.

CLI

Use JSON directly in other CI systems:

# Report-only (exit 0 even when findings exist; scores still in JSON)
npx @praneeth_54/agentdoctor --json

# Published 0.3.0-beta: --ci is report-only; use --min-score to fail CI
npx @praneeth_54/agentdoctor@0.3.0-beta --ci --json --min-score 70

# Unreleased tree CLI: --ci fails on any critical finding
agentdoctor --ci --json

# Unreleased: fail when overall readiness is below 70 (with --ci also fails on criticals)
agentdoctor --ci --json --min-score 70

# Unreleased: fail on warning-or-higher (overrides the default critical gate from --ci)
agentdoctor --ci --json --fail-on-severity warning

In this repository’s Unreleased CLI, --ci fails when any critical finding exists. Override the severity floor with --fail-on-severity, and use --min-score / --fail-on-rule for additional gates. Omit --ci for report-only JSON (exit 0 even when findings exist). Published 0.3.0-beta treats --ci as report-only and does not accept --fail-on-severity / --fail-on-rule.

Exit codes: docs/exit-codes.md. Compatibility promises: docs/compatibility.md.

Readiness scoring

Scans populate scoringAvailable: true and a deterministic scores object (overall, categories, agents). The terminal prints overall readiness; category and agent scores are in JSON (--json).

--min-score N is enforced by the CLI. Details (weights, security caps, threshold rules, and deferred v2 items): docs/scoring.md.

---

Beta limitations

Honest limits of the current public beta:

| Limitation | Status | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Automatic fixes | Safe Cursor / Claude Code / Codex context exclusions (Unreleased; published 0.3.0-beta is Cursor .cursorignore only) | | Security f