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.1.x-beta). Readiness scoring and automatic fixes are not available yet.

What you get

$ npx @praneeth_54/agentdoctor

🩺 AgentDoctor v0.1.3-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

Scoring: not included in this release

Example abbreviated from a real fixture scan (fixtures/insecure-agent-project). Secret values are never printed.

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.

AgentDoctor analyzes configuration. It does not run agents, call an LLM, or modify your repository in this release.

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

Automatic repair is not included in this beta. Findings tell you what to review; you decide what to change.

Quick start

One-shot (recommended)

npx @praneeth_54/agentdoctor

Pin a beta version when you need a fixed install:

npx @praneeth_54/[email protected]

Global (optional)

npm install -g @praneeth_54/agentdoctor
agentdoctor

Common commands

agentdoctor .
agentdoctor . --json
agentdoctor . --verbose
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 } from "@praneeth_54/agentdoctor";

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

Supported agents

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

Additional adapters are planned — see ROADMAP.md.

Finding categories

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

Use JSON for automation:

npx @praneeth_54/agentdoctor --json

--ci runs non-interactively. Until readiness scoring ships, successful scans exit 0 even when findings exist, and --min-score is accepted but ignored.

There is no packaged GitHub Action yet (planned — ROADMAP.md).

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

Beta limitations

Honest limits of the current public beta:

See CHANGELOG.md and docs/release-notes-v0.1.3-beta.md.

Architecture

Discovery → Project detect → Agent adapters → Rule engine → Findings → Terminal / JSON

Details: docs/architecture.md

Documentation

Contributing

Issues and pull requests are welcome.

1. Read CONTRIBUTING.md and the Code of Conduct
2. Prefer good first issues ideas
3. Report security issues via SECURITY.md — never paste real secrets into issues

git clone https://github.com/pranee54/AgentDoctor.git
cd AgentDoctor
npm install
npm run verify
node dist/cli/index.js ./fixtures/clean-configured-project

Next steps

• Try it: npx @praneeth_54/agentdoctor
• Report a false positive / false negative: use the issue templates (include version, rule ID, anonymized evidence — no secrets)
• Propose a rule or adapter: feature request / rule proposal
• Contribute: CONTRIBUTING.md
• Useful? Star or watch the repository so you see updates

License

MIT © AgentDoctor Contributors