AgentDoctor

Engineering assurance for AI coding agents.

Understand your codebase, assess the impact of changes, govern engineering knowledge, enforce safety policies, and attach inspectable evidence to AI-driven changes.

Published: @praneeth_54/agentdoctor@2.1.0 Release notes: docs/RELEASE_2_1_0.md · Prior assurance cut: docs/2.0.1/README.md

Install · Quickstart · Change assurance · Project AI (2.1) · Documentation · MCP · GitHub Action · Architecture

---

What AgentDoctor is

AgentDoctor sits between developers / AI coding agents and the repository’s engineering reality.

AI agents can write code quickly. The harder engineering problem is knowing whether a change is correct, safe, compatible, explainable, and consistent with the rest of the repository.

AgentDoctor collects repository signals — source structure, graphs, Git history, policies, knowledge, and verification evidence — so humans and agents can reason about changes with fewer unsupported assumptions.

Who it is for

| Audience | How AgentDoctor helps | | ---------------------- | ----------------------------------------------------------------------------- | | Manual developers | Scan / fix / verify, change impact, evidence, architecture and policy checks | | Students | learn — explain project, viva, docs; BUILD_WITH_ME after approval | | AI-assisted developers | Optional Project Chat (ask / chat) with evidence and truth labels | | AI coding agents | MCP + controlled tools; AgentDoctor owns context, execution, and verification |

It is not a generic chatbot, IDE interceptor, or claim of full autonomy. Optional Project AI (2.1) is opt-in and still subject to approvals, path/runner controls, and verification. It does not guarantee correctness. It produces evidence and controls you can inspect.

Architecture (when AI is enabled):

THE MODEL REASONS.
AGENTDOCTOR PROVIDES PROJECT CONTEXT.
AGENTDOCTOR CONTROLS TOOLS.
AGENTDOCTOR VERIFIES RESULTS.

Short description: Engineering assurance for AI coding agents — repository intelligence, change evidence, safety controls, MCP tools, and an optional Project AI Agent.

---

Why AgentDoctor?

Modern AI coding agents can:

• read individual files
• generate and edit code
• run tests when asked

Repository-level context is usually fragmented across:

| Signal | Typical location | | ------------------ | ------------------------------ | | Source structure | AST / imports / modules | | Dependencies | manifests / lockfiles | | History | Git | | Architecture | docs / conventions / inference | | Tests | test trees / naming heuristics | | Policy | CI rules / allowlists | | Decisions | ADRs / RFCs / tribal knowledge | | Secrets / exposure | config files / ignore rules |

AgentDoctor brings those signals into one local toolchain around an AI-driven engineering change:

Developer / AI Agent
        │
        ▼
   AgentDoctor
        │
┌───────────────────────────────┐
│ Repository Intelligence       │
│ AST / Graph / Git / Impact    │
├───────────────────────────────┤
│ Engineering Knowledge         │
│ Brain / Decisions / Provenance│
├───────────────────────────────┤
│ Safety & Policy               │
│ Scan / Fix / Enforce / Secrets│
├───────────────────────────────┤
│ Verification                  │
│ Tests / Reports / Evidence    │
└───────────────────────────────┘
        │
        ▼
Safer, explainable engineering decisions

---

Capability map

Status labels: SUPPORTED · PARTIAL · EXPERIMENTAL · NOT YET SUPPORTED

Details and evidence: docs/2.0/overview/capabilities.md · readiness matrix

Repository intelligence

| Capability | Status | | ---------------------------------------------------- | ------------ | | TypeScript / JavaScript AST graph (+ regex fallback) | PARTIAL | | Import / inferred call relationships | PARTIAL | | Git hotspot / engineering intelligence | PARTIAL | | Change / test / refactor impact | PARTIAL | | C4-style architecture views | EXPERIMENTAL |

Engineering knowledge

| Capability | Status | | ------------------------------------------------------------- | --------- | | Project Brain store + evidence-backed claims | SUPPORTED | | Repository Brain init / proposal review (never auto-approved) | PARTIAL | | Governed knowledge + abstention on retrieve | PARTIAL | | Provenance envelopes on Brain MCP tools | SUPPORTED |

Agent interfaces

| Capability | Status | | --------------------------------------------------------------------------------- | --------- | | Brain MCP (brain_* tools, STDIO) | SUPPORTED | | Combined MCP (Brain + intelligence tools) | PARTIAL | | Agent MCP (project_ask, path-safe file tools, plan, change verify) — 2.1 | PARTIAL | | Optional Project Chat / coding agent CLI (chat, ask, agent, learn) — 2.1 | PARTIAL | | Agent adapters (Cursor, Claude Code, Codex, Copilot, Windsurf, Gemini CLI, Aider) | SUPPORTED | | Local dashboard + /api/v2/* + ask-only /api/chat — 2.1 | PARTIAL | | Programmatic API (scan, Fix, Brain helpers) | SUPPORTED |

Safety & governance

| Capability | Status | | -------------------------------------------------------- | --------------------- | | Scan → Safe Fix → Verify | SUPPORTED | | Policy gates (--min-score, severity, rule, verify-new) | SUPPORTED | | Evaluate-only policy / controlled enforcement runner | PARTIAL | | Secret scan (redacted findings) + export redaction | PARTIAL | | Path-safety for MCP / dashboard | PARTIAL | | Local-dev team auth (scrypt) | PARTIAL — not SSO |

Verification

| Capability | Status | | ------------------------------------------------------- | -------------------------- | | Change assurance assessment + evidence bundles | PARTIAL | | Evidence hash verify (verified = integrity only) | SUPPORTED | | Unit / integration / MCP STDIO tests (npm run verify) | SUPPORTED | | Packed CLI clean-install smoke | SUPPORTED | | Reproducible AST perf harness | PARTIAL (synthetic sample) |

---

How AgentDoctor is different

Most engineering tools optimize one layer: static analysis, search, docs generation, dashboards, security scanners, or AI chat.

AgentDoctor is designed around the lifecycle of an AI-driven change:

Repository
    → Understand
    → Impact
    → Knowledge
    → Policy
    → Change
    → Verification
    → Evidence

That combination is the product direction. It does not mean every layer is equally mature — see the capability map and limitations.

---

Architecture

AgentDoctor
│
├── Repository Intelligence
│   ├── AST (TS/JS)
│   ├── Graph
│   ├── Git
│   └── Impact
│
├── Engineering Knowledge
│   ├── Brain
│   ├── Governance
│   └── Provenance
│
├── Safety
│   ├── Scanner
│   ├── Safe Fix
│   ├── Secrets
│   └── Policies
│
├── Agent Interface
│   ├── MCP (brain-mcp / mcp)
│   ├── CLI
│   ├── API / dashboard
│   └── Adapters
│
└── Verification
    ├── Tests
    ├── Reports
    └── Release validation

Code layout: src/{intelligence,knowledge,core,mcp,platform,enforcement,cli}/

Canonical docs: docs/2.0/overview/architecture.md

---

Engineering principles

1. Evidence over assumptions
2. Explicit limitations over inflated claims
3. Safety before automation
4. Repository context over isolated files
5. Human approval for governed decisions
6. Backwards compatibility where documented
7. Reproducible verification
8. Explainable agent actions
9. Least privilege
10. Secure defaults

---

Install

Requires Node.js 20+.

npm install -g @praneeth_54/agentdoctor@2.1.0
# or:
npx @praneeth_54/agentdoctor@2.1.0 --help

From source:

git clone https://github.com/pranee54/AgentDoctor.git
cd AgentDoctor
npm install
npm run verify

---

Quickstart

agentdoctor --version          # 2.1.0
agentdoctor scan .
agentdoctor scan . --json
agentdoctor fix --dry-run
agentdoctor verify --baseline agentdoctor-report.json

# Repository Brain proposals (not auto-approved)
agentdoctor init --name "My App" --domain "payments"
agentdoctor brain proposals

# Intelligence
agentdoctor graph --mode auto --json
agentdoctor impact --json
agentdoctor c4 --json

# Change assurance
agentdoctor change analyze
agentdoctor change verify
agentdoctor change explain|diff|status
agentdoctor evidence inspect <id>
agentdoctor evidence verify <id>
agentdoctor proof build|inspect|verify|export <id>

# Architecture / policy / controlled run
agentdoctor architecture init|check|explain
agentdoctor policy check|explain --command "npm test"
agentdoctor run explain --command "npm test"
agentdoctor workspace create|add|list|status|remove

# MCP (absolute --root required)
agentdoctor brain-mcp --root /ABS/PATH/TO/REPO
agentdoctor mcp --root /ABS/PATH/TO/REPO

Project AI Agent (2.1 — optional; local RC)

Requires an explicit provider (AGENTDOCTOR_AI_PROVIDER=mock or openai-compatible / ollama). Default none fails closed for chat.

agentdoctor ask "How does login work?" .
agentdoctor chat .
agentdoctor learn .
agentdoctor learn --viva
agentdoctor plan "Add registration"
# Writes require --approve; model cannot self-approve
agentdoctor agent --goal "Add registration" --approve --apply --apply-ops '[...]' .

Details: docs/RELEASE_2_1_0.md · docs/AI_AGENT.md · docs/SECURITY_AGENT.md

CLI reference: docs/2.0/guides/cli.md · Change assurance: docs/2.0.1/change-assurance.md

---

Project AI Agent (2.1)

Optional Project AI on top of the 2.0.1 assurance substrate. See docs/RELEASE_2_1_0.md.

| Piece | Behavior | | --------- | ------------------------------------------------------------------------- | | Context | Project evidence with truth labels; repository text is untrusted DATA | | Tools | Path-saf