AgentDoctor

The intelligence and assurance layer for software projects.

Understand your codebase. Build safely. Verify the result.

Ask questions about a real repository. Plan a change. Require approval. Edit under path-safe controls. Map tests and risk. Attach evidence. Prove integrity — without pretending the change is “correct.”

Published package: @praneeth_54/agentdoctor Current product: 3.0 — project intelligence & assurance core (see Verification)

Install · 5-minute quickstart · What it can do · Students · MCP · Security · Limitations · Docs

What is AgentDoctor?

AgentDoctor is a project-aware intelligence and assurance platform. It helps people understand, learn, plan, safely change, test, secure, verify, and remember software projects — whether the code was written by hand, with AI, or by a coding agent.

Most tools answer one slice of the problem:

Tool type	Typical job
Linters	Style / static issues
Test runners	Execute tests
Code search	Find text / symbols
Security scanners	Find vulnerabilities
AI coding agents	Propose / apply edits

AgentDoctor connects those concerns around the project itself. It builds local understanding of structure, relationships, dependencies, Git, tests, security signals, requirements, and evidence — then uses that understanding across:

UNDERSTAND → ASK → PLAN → APPROVE → CHANGE → TEST → SECURE → VERIFY → PROVE

It is not “another chatbot,” a Cursor clone, a generic coding agent, or a claim of full autonomy.

Invariant

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

The model is not the source of truth. Repository evidence is.

Why it exists

AI tools can write code quickly. Engineering still needs answers to:

What is this project?
What depends on this module?
What breaks if I change it?
Which tests matter?
Is this change within policy / workspace bounds?
Did the requested change actually happen?
What evidence supports the result?
What remains UNKNOWN?

AgentDoctor exists for that loop — locally, inspectably, with explicit truth labels.

How it works

                 User / Student / Developer / AI agent
                                    │
                                    ▼
                              AgentDoctor
                     (CLI · MCP · Dashboard)
                                    │
                                    ▼
                        Project Understanding
              ┌─────────────┬─────────────┬──────────────┐
              │ Project Brain │ Code Graph │ Project DNA  │
              │ Architecture  │ Deps/Git   │ Tests/Sec    │
              │ Requirements  │ Search     │ Evidence     │
              └─────────────┴─────────────┴──────────────┘
                                    │
                                    ▼
                     Reasoning (optional LLM / deterministic)
                                    │
                                    ▼
                         Controlled tools (path-safe)
                                    │
                                    ▼
                    Verification · Evidence · Proof

Who is it for?

Students

College / B.Tech / final-year projects, inherited repos, viva prep, documentation.

agentdoctor start
agentdoctor learn .
agentdoctor learn . --viva
agentdoctor learn . --docs
agentdoctor ask "Explain authentication like a beginner." .

Use Build With Me only with explicit approval (--approve) before writes.

Developers

Inherited codebases, impact analysis, deps, architecture, change assurance.

agentdoctor dna .
agentdoctor graph .
agentdoctor map .
agentdoctor deps .
agentdoctor search "login" .
agentdoctor what-if src/auth.js .
agentdoctor change analyze .

AI-assisted developers

Works alongside Cursor, Claude Code, Codex, Copilot, Windsurf, Gemini CLI, Aider, and similar workflows as an assurance / intelligence layer (scan adapters + MCP) — not as a replacement IDE.

agentdoctor mcp --root /absolute/path/to/project
agentdoctor plan "Add password reset" .
agentdoctor agent --goal "…" --approve --apply --apply-ops '[...]' .

Security / reviewers

Secrets (redacted), technical security heuristics, forensic read-only mode, path/approval controls, evidence.

agentdoctor secrets .
agentdoctor security-doctor .
AGENTDOCTOR_FORENSIC_MODE=1 agentdoctor forensic .
agentdoctor evidence verify <changeId> .

Teams / owners

Local project DNA, twin snapshots, decisions/ADRs, org catalog (local JSON — not enterprise SSO).

agentdoctor twin .
agentdoctor decisions .
agentdoctor org .
agentdoctor dashboard .

What can it do?

Status below = complete at defined local scope (see docs/LIMITATIONS.md). EXTERNAL means outside systems are required for that upgrade path.

Understand

Capability	CLI / surface	Notes
Safe project discovery	`start`	Refuses home/Desktop dumps
Project DNA	`dna`, `start`	Manifest / marker evidence
Code graph + AST	`graph`	Strong TS/JS; host/line others
Architecture / C4	`architecture`, `c4`	Advisory unless you gate it
Dependencies + lockfiles	`deps`	VERIFIED when lock parsed
Software map / code health	`map`, `health-code`	Layout + indicators
Project Brain	`brain`, MCP	Local, deterministic
Requirements / API / DB / events	`requirements`, …	File evidence; live = EXTERNAL

Ask

Capability	CLI / surface	Notes
Project Chat	`ask`, `chat`	Deterministic without LLM; LLM optional
Truth labels	responses	VERIFIED / INFERRED / UNKNOWN / EXTERNAL
Search	`search`, MCP	Lexical / TF-IDF; embeddings = EXTERNAL

Build

Capability	CLI / surface	Notes
Plan	`plan`	No writes
Coding agent	`agent`, `role-agent`	Writes need `--approve`
MCP agent tools	`mcp`	Token + planHash; bare `approved:true` fails
Controlled runner	`run`, `policy`	Shell off by default

Test

Capability	CLI / surface	Notes
Test Brain	`test-brain`	Mapping / impact — not mutation testing
Impact	`impact`	Heuristic; coverage optional
Evaluation lab	`eval-lab`	Fixture checks

Secure

Capability	CLI / surface	Notes
Secrets (redacted)	`secrets`	Values never printed
Security Doctor	`security-doctor`	Technical heuristics ≠ commercial SAST
Forensic mode	`forensic` + env	Read-only; blocks writes/exec
Path / workspace	all write surfaces	Traversal / symlink escape blocked
Privacy Doctor	`privacy-doctor`	Technical PII-ish — not legal compliance

Verify

Capability	CLI / surface	Notes
Change analyze	`change analyze`
Evidence / proof	`change verify`, `evidence`, `proof`	Integrity ≠ engineering correctness
Scan → Fix → Verify	`scan`, `fix`, `verify`	Agent-config safety
Self-check	`self-check`	Installation diagnosis

Learn

Capability	CLI
Learn / viva / docs	`learn`, `--viva`, `--docs`
Build With Me	`learn --mode BUILD_WITH_ME --build "…" --approve`

Remember / operate (local)

Capability	CLI / surface	Boundary
Decisions / evolution	`decisions`, `evolution`	Local ledgers / git
Digital Twin	`twin`	Local snapshot — not live runtime twin
What-if	`what-if`	Graph impact — not certainty
Infra markers	`infra`	Compose/K8s/TF files — live cluster EXTERNAL
Incident hypotheses	`incident`	Not auto-verified root cause; APM EXTERNAL
Org catalog	`org`	Local JSON — IdP EXTERNAL

Not just a coding agent

A coding agent can modify files. AgentDoctor is built for the full loop:

UNDERSTAND → PLAN → APPROVE → CHANGE → TEST → SECURE → VERIFY → PROVE

Don't just generate a change. Understand the project and verify the change.

Proof means hash integrity over evidence, with:

ENGINEERING_CORRECTNESS_NOT_CLAIMED

Workflow: “Add password reset”

agentdoctor start — discover project, DNA, Brain
agentdoctor ask "How does authentication work?" — evidence-backed / deterministic paths
agentdoctor search login / what-if src/auth.js — related files & tests
agentdoctor plan "Add password reset" — plan only; no writes
Review risk; approve explicitly
agentdoctor agent --goal "Add password reset" --approve --apply --apply-ops '[…]' — path-safe tools
agentdoctor change analyze / change verify — assessment + evidence
agentdoctor proof — integrity check
Read Verified / Not verified / UNKNOWN — never treat integrity as product correctness

Student path: learn → ask → viva → docs → Build With Me (with --approve).

Install

Requires Node.js 20+.

npm install -g @praneeth_54/agentdoctor@3.0.3
agentdoctor --version   # 3.0.3
agentdoctor --help

Or without global install:

npx @praneeth_54/agentdoctor@3.0.3 --help

Five-minute quickstart

# 1. Install
npm install -g @praneeth_54/agentdoctor@3.0.3

# 2. Enter YOUR project (not your home folder)
cd /path/to/my-project

# 3. Discover
agentdoctor start

# 4. Understand
agentdoctor dna .
agentdoctor graph .
agentdoctor map .

# 5. Ask (works without an LLM — deterministic analyzers)
agentdoctor ask "Explain my project." .
agentdoctor ask "How does authentication work?" .

# 6. Inspect
agentdoctor search "TODO" .
agentdoctor deps .
agentdoctor security-doctor .

# 7. Plan a change (no writes)
agentdoctor plan "Add a health check endpoint" .

# 8. Apply only with explicit approval (example ops JSON; --goal required)
agentdoctor agent --goal "Add a health check note" --approve --apply \
  --apply-ops '[{"name":"create_file","arguments":{"path":"HEALTH.md","content":"# Health\n"}}]' .

# 9. Verify change signals
agentdoctor change analyze .
agentdoctor changes .

Optional UI (loopback):

agentdoctor dashboard .
# → http://127.0.0.1:<port>/

Command reference

All commands below exist in the current CLI (agentdoctor --help). Prefer --json for scripts.

Project & intelligence

Command	Purpose
`start [path]`	Safe discovery, DNA, Brain init
`dna [path]`	Project DNA fingerprint
`graph [path]`	Intelligence graph
`map [path]`	Software map
`deps` / `dependency`	Dependencies + lockfiles
`search <query>`	Symbol / concept search
`health` / `health-code`	Git / code health
`requirements` / `api` / `database` / `events` / `features`	Lifecycle intelligence
`twin` / `what-if` / `forensic` / `evolution` / `memory`	Twin, impact, forensic, memory
`infra` / `incident` / `org`	Local ops / org catalog

Chat, agent, learning

Command	Purpose	Safety
`ask <question> [path]`	One-shot Project Chat	Deterministic if no provider
`chat [path]`	Interactive chat	Needs provider for LLM mode
`plan <goal>`	Plan only	No file edits
`agent`	Tools / apply	`--apply` requires `--approve`
`role-agent`	Role allowlists	Same approval gates
`learn`	Student explain / viva / docs / build modes	Writes need approval

Security, change, evidence

Command	Purpose
`scan` / `fix` / `verify`	Agent-config Scan → Fix → Verify
`secrets` / `security-doctor` / `privacy-doctor`	Secrets & technical doctors
`change analyze` / `change verify`	Change assessment & evidence
`evidence` / `proof`	Inspect / integrity
`policy` / `run` / `enforce`	Controlled execution
`self-check` / `eval-lab` / `doctor`	Self / eval / install health

Brain, MCP, dashboard, workspace

Command	Purpose
`brain`	Project Brain CLI
`mcp --root <abs-or-rel>`	Combined Brain + intelligence + agent MCP (STDIO)
`brain-mcp`	Brain-only MCP
`dashboard [path]`	Local read-only SPA (loopback)
`workspace`	Multi-repo local isolation under `.agentdoctor/workspaces/`

AI providers

AI is optional. Core discovery, DNA, graph, scan/fix/verify, deps, search, security heuristics, evidence, and deterministic ask work without an API key.

Implemented providers (docs/MODEL_PROVIDERS.md):

Provider	Role
`none`	Default fail-closed for LLM chat
`deterministic` / local analyzers	Project Chat without LLM
`mock`	Tests / demos
`openai-compatible`	OpenAI-compatible HTTP API
`ollama`	Local Ollama-compatible HTTP

Configure with AGENTDOCTOR_AI_PROVIDER, AGENTDOCTOR_AI_API_KEY, AGENTDOCTOR_AI_BASE_URL, AGENTDOCTOR_AI_MODEL.

Not implemented: native Anthropic / Gemini clients (do not claim).

MCP

Connect AgentDoctor to AI coding workflows over STDIO:

agentdoctor mcp --root /absolute/path/to/project

Audited combined server exposes 38 tools (Brain + intelligence + agent), including project DNA/context/ask, search, file read, planning, change analysis, and controlled writes.

Safety (verified):

Path / workspace bounds; traversal rejected
Writes need trusted approvalToken + planHash + resource binding
Bare approved: true is rejected
approval_issue requires AGENTDOCTOR_MCP_TRUSTED_APPROVE=1
Secret redaction; no unrestricted shell tool
Forensic mode blocks write/execute

Details: docs/MCP.md · docs/AGENT_APPROVALS.md

Security model

Repository content is untrusted data — never system policy.

Controls include:

Central path safety (traversal, symlinks, workspace escape)
Approval-bound mutations (CLI --approve / MCP grants)
Controlled runner (shell=false by default)
Secret scanning with redaction
Forensic read-only mode (AGENTDOCTOR_FORENSIC_MODE=1)
Prompt-injection treated as data (eval fixture + chat framing)
Evidence / audit trails

AgentDoctor does not claim to be “completely safe,” a legal compliance product, or a commercial SAST replacement.

Policy: SECURITY.md · Model: docs/SECURITY_MODEL.md

Truth model

Label	Meaning
VERIFIED	Directly supported by repository evidence
INFERRED	Derived from available signals
UNKNOWN	Insufficient evidence
EXTERNAL	Needs systems outside the local repo

Honesty is a feature: the system should not invent files, line numbers, or root causes.

Evidence and proof

AgentDoctor answers: what changed, what was affected, what evidence exists, what was integrity-checked, and what remains uncertain.

agentdoctor change analyze .
agentdoctor change verify .
agentdoctor evidence inspect <changeId> .
agentdoctor proof verify <changeId> .

Proof = hash integrity over an evidence bundle. It is not a formal proof of correctness.

Architecture (modules)

CLI / MCP / Dashboard
        │
        ▼
Agent runtime · Project Chat · Student / roles
        │
        ▼
Context retrieval · Truth labels
        │
        ▼
Project Brain · Graph/AST · DNA · Git · Deps · Tests · Security · Twin
        │
        ▼
Path-safe tools · Approvals · Controlled runner
        │
        ▼
Change assessment · Evidence · Proof

Primary code: src/cli, src/agent, src/product, src/intelligence, src/mcp, src/dashboard, src/core, src/assurance, src/security.

Technology stack

Derived from package.json and source:

Area	Technology
Language	TypeScript (ESM)
Runtime	Node.js ≥ 20
CLI	Commander
Tests	Vitest
Build	`tsc`
MCP	`@modelcontextprotocol/sdk`
Dashboard	Local Node HTTP + embedded SPA
AST (TS/JS)	TypeScript compiler API
Packaging	npm (`files`: `dist`, README, LICENSE, CHANGELOG)
License	MIT

Verification

AgentDoctor 3.0 — local acceptance evidence:

Gate	Result
Formal / release / product acceptance	PASS (maintainers: docs/internal/)
`npm run verify`	627/627 tests, typecheck, lint, format, build
Clean `npm pack` install	PASS
MCP	38 tools; approval + path checks
Dashboard / API	Real project JSON (not fake cards)
Security / forensic / eval / self-check	PASS
P0 / P1 blockers	0

Reproduce:

npm run verify

Limitations

Honesty is part of the product. Read docs/LIMITATIONS.md.

Notable boundaries:

Live Kubernetes / APM / enterprise IdP → EXTERNAL
Neural embeddings / commercial SAST → EXTERNAL
Full compiler-grade semantics for all languages → EXTERNAL where adapters are line scanners
Optional LLM providers → configure explicitly; core stays useful without them
Proof ≠ engineering correctness

Post-acceptance ideas for later releases: maintainers see docs/internal/POST_3_0_BACKLOG.md.

Roadmap

Track	Meaning
3.0.0 (released)	Original public release (`v3.0.0` → `c21faf1`)
3.0.1 (released)	Freeze remediation / ownership & security hardening follow-up
3.0.2 (released)	`start` discovery aligned with deterministic `detectProject`
3.0.3 (released)	Brain → Project Chat evidence + `ask` progress UX
Coming soon	Maturity, language depth, runtime adapters, DX — not promised ship dates

Documentation

Full index: docs/README.md

Topic	Link
Product	docs/PRODUCT.md
Project Chat	docs/PROJECT_CHAT.md
AI Agent	docs/AI_AGENT.md
Student mode	docs/STUDENT_MODE.md
MCP	docs/MCP.md
Approvals	docs/AGENT_APPROVALS.md
Security model	docs/SECURITY_MODEL.md
Evidence / Proof	docs/EVIDENCE.md · docs/PROOF.md
Project Brain	docs/PROJECT_BRAIN.md
Limitations	docs/LIMITATIONS.md
Feature guides	docs/guides/features/
Contributing	CONTRIBUTING.md
Security policy	SECURITY.md
Code of conduct	CODE_OF_CONDUCT.md
Changelog	CHANGELOG.md

Contributing

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

See CONTRIBUTING.md. Issues and PRs welcome via GitHub templates.

License

GitHub discoverability (maintainers)

Suggested repository description:

Project intelligence and assurance for software — understand, ask, plan, approve, change, test, secure, verify, and prove. Local-first. MCP-ready.

Suggested topics: software-engineering, developer-tools, code-intelligence, ai-agents, mcp, static-analysis, developer-experience, security, testing, typescript

Try it on a real project in five minutes. If something is UNKNOWN, that is intentional — AgentDoctor should show the boundary, not invent certainty.

Name		Name	Last commit message	Last commit date
.cursor/skills		.cursor/skills
.github		.github
.vscode		.vscode
docs		docs
examples/mcp		examples/mcp
fixtures		fixtures
schemas/v2		schemas/v2
scripts		scripts
src		src
tests		tests
validation		validation
.cursorignore		.cursorignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
action.yml		action.yml
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
prettier.config.js		prettier.config.js
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.understanding.config.ts		vitest.understanding.config.ts

Latest commit

History

Folders and files

Repository files navigation

AgentDoctor

The intelligence and assurance layer for software projects.

What is AgentDoctor?

Why it exists

How it works

Who is it for?

Students

Developers

AI-assisted developers

Security / reviewers

Teams / owners

What can it do?

Understand

Ask

Build

Test

Secure

Verify

Learn

Remember / operate (local)

Not just a coding agent

Workflow: “Add password reset”

Install

Five-minute quickstart

Command reference

AI providers

MCP

Security model

Truth model

Evidence and proof

Architecture (modules)

Technology stack

Verification

Limitations

Roadmap

Documentation

Contributing

License

GitHub discoverability (maintainers)

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages