mintwork / agent-ready
Lighthouse for AI coding agents
Score how well Claude Code, Codex and Cursor can work in your repo, then auto-fix the gaps.
npx @mintwork/agent-ready # score this repo
npx @mintwork/agent-ready --fix # apply the safe fixes
The problem
Your agent is only as good as the repo you drop it into. No AGENTS.md? It guesses your test command. A stale CLAUDE.md? It confidently edits files deleted months ago. dist/ not ignored? It greps your minified bundle and burns half its context window.
agent-ready checks all of that in under a second and gives you a 0 to 100 score, a category breakdown, and a punch list of fixes, many of which it can apply for you.
What it does
Five categories
Context docs, feedback loops, navigability, type safety and safety, weighted into one score.
Auto-fix
--fixwrites a starter AGENTS.md and CLAUDE.md from your real scripts and structure, and fixes ignore files.Doc drift
Flags agent docs that mention files, scripts or commands that no longer exist.
CI gate
The Agent Readiness Score Action fails pull requests that make the repo worse for agents.
Many stacks
JS/TS, Python, Go and Rust, with basic Java and Kotlin support, and it understands monorepos.
Read-only by default
Zero dependencies. Nothing changes unless you pass
--fix.
Install
npx @mintwork/agent-ready # no install
npm i -D @mintwork/agent-ready # or pin it in your project
npx @mintwork/agent-ready --badge # a README badge with your scoreGitHub Action
- uses: actions/checkout@v7
with: { fetch-depth: 0 }
- uses: mintwork/agent-ready@v0
with:
min-score: 75How is this different from a linter?
A linter tells you your code is wrong. agent-ready tells you your repository is hard to work in, for the coworker who reads every file literally, never asks a clarifying question, and runs whatever npm run build does.
Open source, MIT licensed
Built in CI and published to npm with signed provenance. The full docs, changelog and issues are on GitHub.