Make your repo readable to coding agents.

agent-ready-repo audits and fixes any repository so coding agents — Claude Code, Gemini CLI, Jules, Cursor, Lovable, Bolt, and Replit Agent — can understand it and work on it without API-key hell.

Agents are the new developers. GitHub is their memory. Docs are their instructions. Templates are their instincts. This tool makes your repo a place agents can navigate on their first try.

Quickstart

# audit the current repo and write a report
npx agent-ready-repo audit

# scaffold any missing agent-readiness files (safe — never overwrites silently)
npx agent-ready-repo fix

No install, no account, no API keys. It runs locally and only reads/writes files in the target directory.

What it checks

audit scores your repo (0–100, grade A–F) across four areas:

• Files — README.md, AGENTS.md, CLAUDE.md, llms.txt, .env.example, .gitignore, LICENSE, SECURITY.md, CONTRIBUTING.md, and the docs/ handbook (HANDOFF, ROADMAP, KNOWN_ISSUES, ARCHITECTURE, DEPLOYMENT, MONETIZATION).
• Content — a repo description, a README quickstart, and actionable agent instructions in AGENTS.md.
• Package scripts — build, test, preview/dev, and deploy commands.
• Security — possible committed secrets and leftover placeholder URLs.

Output goes to your console, to docs/AGENT_READY_REPORT.md, and optionally to JSON.

What fix does

fix creates only the missing starter files from safe, generic templates. It never overwrites existing content silently:

• Existing files are skipped and listed.
• --force backs each existing file up to <file>.bak before writing.
• --dry-run shows what would change without writing anything.

After running fix, edit the placeholders and re-run audit.

Commands

agent-ready-repo audit [--cwd <dir>] [--json [path]] [--no-report] [--silent] [--ci]
agent-ready-repo fix   [--cwd <dir>] [--dry-run] [--force]

Option	Applies to	Meaning
--cwd <dir>	both	Target directory (default: current directory).
--json [path]	audit	Print JSON, or write it to path.
--no-report	audit	Skip writing docs/AGENT_READY_REPORT.md.
--ci	audit	Exit non-zero when the grade is failing (D or F).
--dry-run	fix	Show planned changes without writing.
--force	fix	Overwrite existing files (backs up to .bak first).

For coding agents

See AGENTS.md for build/test commands and conventions, and docs/AGENT_PROMPTS.md for ready-to-use prompts.

Development

npm install
npm run typecheck
npm test
npm run build

Roadmap & business model

This is the free CLI core of a broader agent-readiness toolchain. See docs/ROADMAP.md and docs/MONETIZATION.md.

License

MIT — see LICENSE.