Before handing a repo to an AI coding agent, run a quick local checkup.
agent-project-doctor is a local TypeScript CLI for maintainers and developers who want to understand whether a repository has enough docs, validation guidance, agent instructions, and safety boundaries for tools like Codex, Claude Code, Cursor, Cline, and similar AI coding agents.
It generates:
- an HTML readiness report
- a Markdown summary
- a draft
AGENTS.generated.md
No code upload. No LLM calls. No target repo scripts executed.
Run it from the repository you want to scan:
npx --yes github:jiusi1-cpu/agent-project-doctor scan --path . --out .agent-project-doctorThis project is not published to npm yet. The command above installs and runs the CLI directly from GitHub; do not use npx agent-project-doctor unless an npm package is published later.
If the GitHub npx command fails, check that:
- Node.js 20 or newer is installed.
- Git is installed and available on your
PATH. - Your network can reach GitHub and the npm registry.
- npm lifecycle scripts are enabled.
Fallback: clone and run it locally:
git clone https://github.com/jiusi1-cpu/agent-project-doctor.git
cd agent-project-doctor
npm install
npm run build
node dist/cli.js scan --path ../your-repo --out ../your-repo/.agent-project-doctorOr scan this project itself after building locally:
node dist/cli.js scan --out .agent-project-doctorGenerated files:
agent-doctor-report.htmlagent-doctor-summary.mdAGENTS.generated.md
The generated AGENTS.generated.md is a draft. Review it before copying any guidance into a real AGENTS.md.
The MVP is intentionally local and conservative:
- It does not upload code.
- It does not call LLMs or external APIs.
- It does not execute target repository install/build/test/deploy scripts.
- It does not install target repository dependencies.
- It does not read ordinary source file contents by default.
- It does not read
.envvalues. - It does not write
AGENTS.md. - It writes only the three known generated files inside the selected output directory.
- It does not overwrite existing generated outputs unless
--forceis provided.
This is a best-effort readiness signal scanner, not a security certification and not proof that a repository is safe for agents.
- README and quick-start signals.
- Contribution and license guidance.
- Test command and common test directory signals.
- GitHub Actions workflow presence.
AGENTS.md,CLAUDE.md, Cursor rules, and Cline rule signals.- Missing scope or validation guidance in agent instructions.
.env,.env.example, and.gitignoresafety signals.- Risky destructive command language.
- Production deploy wording.
- Large repository context warnings.
- It does not modify source files.
- It does not create pull requests.
- It does not run tests for the target repository.
- It does not perform vulnerability scanning.
- It does not certify a repository as secure or AI-ready.
- It does not publish reports or upload artifacts.
See:
npm install
npm test
npm run build
node dist/cli.js scan --path tests/fixtures/minimal-node --out tmp/minimal --forceMVP release validation stops at:
npm pack --dry-runDo not run npm publish, create a GitHub Release, push tags, or upload public artifacts unless the project owner explicitly confirms that release step.
- Improve rule wording and reduce false positives.
- Add more ecosystem-specific command detection.
- Add optional GitHub Action after the CLI MVP is stable.
- Add optional MCP/config scanning after safety wording is mature.
Keep changes small and covered by tests. The scanner must remain local-only by default and must not execute target repository scripts.
