Can an AI agent actually work in your repo?

When Claude Code or Cursor flails in a codebase, everyone blames the model. Usually it is the repository.

Try it on the repo you have open right now. Nothing installed, no code executed.

Median agent-readiness by language

873 most-starred software repos on GitHub

TypeScript 73

Go 72

Rust 65

Python 61

JavaScript 60

Shell 49

Java 45

C++ 43

C 42

Jupyter Notebook 41

Higher is better. Curated lists and tutorials excluded.

What we found across 873 repositories

median mark out of a hundred

37%

have no test command an agent can find

35%

ship an AGENTS.md

See the whole class list

Five things decide whether an agent succeeds

Instructions

An AGENTS.md that names the real commands

Setup

A lockfile, declared commands, a documented environment

Verification loop

Tests an agent can find and run to check itself

Context economy

No 400KB files, no committed build output

Navigability

Documentation, a description, a licence

bash — ~/code

$ curl agentreadme.com/honojs/hono.txt

# honojs/hono — 72/100 · B+

✗ Instructions              3/27   F
  None found. Every agent that opens
  this repo starts from zero.
✓ Setup                    14/14   A+
✓ Verification loop        24/25   A+
✓ Context economy          18/20   A
✓ Navigability             10/10   A+

# fix first
+ Add an AGENTS.md at the root: what the
  project is, how to install, how to run,
  how to test, and the conventions a
  newcomer always gets wrong.
+ Instructions earn their keep by naming
  exact commands.

# full report: agentreadme.com/honojs/hono

$

Recently marked

freeCodeCamp/freeCodeCamp 69 B openclaw/openclaw 73 B+ nilbuild/developer-roadmap 45 C vinta/awesome-python 81 A- obra/superpowers 74 B+ mattpocock/skills 70 B+ 996icu/996.ICU 24 F affaan-m/ECC 89 A

Private repo? Run it locally.

This site cannot read private repositories and never will. The same rubric runs on your machine instead.

Nothing is uploaded. No account, no token, no network call at all. It works on private repos, monorepos, uncommitted work, and code that was never pushed anywhere.

It grades what git tracks, so a local run and this site agree on the same repository.

Do not take our word for it. The published binary imports three things: fs, path, and child_process, the last only to ask git which files it tracks. It contains no fetch, no http client, and no sockets. It cannot send your code anywhere because there is nothing in it that could. Run it with your network off and see.

The package on npm · read the CLI source

bash — ~/your-private-repo

$ npx agentreadme

  acme/internal-api   54/100  C-

  Instructions       ░░░░░░░░░░░░    0/27  F
  Setup              ████████░░░░   14/20  B+
  Verification loop  ██████░░░░░░   12/25  C
  Context economy    ██████████░░   17/20  A
  Navigability       ████████░░░░    5/7   B+

  Fix these first
  1. Agent instruction file
  2. Test command is discoverable

$

--write-agents drafts the file for you. --min 70 fails a build below a score.

Four ways in

Wherever your agent already works.

The command above handles private code on your machine. Here is everything else, all running the same rubric.

A URL

Put any owner and repo after the domain. Add .txt and you get the report as plain text, which is what an agent should read.

$ curl agentreadme.com/honojs/hono.txt

A Claude Code skill

The agent marks the repo it is working in, says what is costing the most, then offers to fix it and check again.

$ /plugin marketplace add dejan23/agentreadme
$ /plugin install agentreadme

An MCP server

For Cursor, Claude Desktop, or anything else that speaks MCP. No key, nothing installed, streamable HTTP at /mcp.

$ claude mcp add --transport http agentreadme https://agentreadme.com/mcp

The server exposes three tools: mark a repository, draft its AGENTS.md, and pull the study numbers so a score has something to sit against. It reads public repositories only, same as this site.

Try it on the repo you have open right now.

Two API calls. Nothing cloned, nothing executed, no account. The marking scheme is published in full and every deduction cites its file.