I audited the AGENTS.md files of 8 popular open-source repos. Here's what coding agents are actually reading.

Isaac Johnson — Wed, 15 Jul 2026 05:17:39 +0000

Over 60,000 open-source repositories now carry an AGENTS.md file — the "README for agents" that Codex, Claude Code, Cursor, Copilot, and some thirty other tools read before touching your code. Large monorepos nest them: the main OpenAI repository reportedly has 88.

Here's the thing: almost nobody looks at what those files collectively tell an agent. Instructions accumulate from the repository root down to the file being edited. They're written by different people, in different years, for different tools. They duplicate. They contradict. They link to docs that were deleted three refactors ago. And every byte of them is paid for in context
tokens, on every request.

I built Scopeglass to make that chain visible, and then pointed it at 8 well-known repositories. All analysis was local and read-only — the tool makes no network calls and never executes repository content.

The numbers

Repository	Files	Depth	Max tokens	Median	Broken	Dups
openai/codex	2	2	7,695	7,601	0	0
apache/airflow	14	3	18,585	12,806	2	6
temporalio/sdk-java	5	3	1,055	987	0	0
PlutoLang/Pluto*	0	0	0	0	0	0
vercel/next.js	3	2	9,402	8,531	0	0
sst/opencode	15	4	11,144	4,164	0	1
block/goose	3	2	5,303	1,836	0	0
crewAIInc/crewAI	3	3	18,503	10,990	0	17

Columns: nested AGENTS.md files found; deepest root-to-target chain; max and median chain token estimate; broken/unsafe references; duplicated instructions. An eighth metric — possible conflicts — was zero for every repo; see finding 4.

*Pluto was on the AGENTS.md showcase list but has since removed its AGENTS.md entirely — instruction files rot at the repo level too.

Method: for every directory containing an AGENTS.md, Scopeglass resolved the full root-to-target chain and reported byte-exact size, a transparent token estimate (ceil(UTF-8 bytes / 3) — deliberately not a model tokenizer), and deterministic diagnostics. Diagnostics are deduplicated across chains. Numbers collected 2026-07-15 at each repo's default branch head; script below.

What stood out

1. A single bad reference at the root poisons every chain. Broken references were rarer than I expected — but where they exist, they inherit. Airflow's root AGENTS.md points agents at .claude/skills/magpie-setup/, which is a symbolic link — and because it's in the root file, all 14 of airflow's AGENTS.md chains inherit that reference. Deeper down, task-sdk/src/airflow/sdk/_shared/AGENTS.md directs agents to
../../../../shared — a path that no longer exists. Instructions politely pointing agents into a wall, on every request that touches those packages.

2. Instructions repeat — the champion does it 930 lines apart. Nested
files inherit their ancestors, so a rule written at three levels isn't
emphasis, it's triple-billed context. The standout is crewAI's CLI template
AGENTS.md — a file shipped to every new crewAI project — which states
"Python >=3.10, <3.14" at line 48 and again, verbatim, at line 980. Nobody
reads line 980 of their own instruction file; the agent reads it every time.
The 17 flagged duplicates in crewAI's declarative_flow template chain are
mostly repeated structural boilerplate — noise a human skims past but an
agent parses and pays for.

3. The token bill is real. The largest chain measured was ~18,600 tokens
(airflow's deepest package; crewAI's template chain is within 100 tokens of
it) before the agent reads a single line of source. Airflow's median chain
is ~12,800 tokens. If your agent bills per token, that's the standing cover
charge on every request.

4. An honest null: zero conflicts. Scopeglass's conflict heuristic is
deliberately narrow — same normalized rule core, opposite leading polarity —
and across all 8 repos it fired zero times. Popular repos with maintained
AGENTS.md files apparently don't argue with themselves in ways that pattern
catches. Fine by me: a diagnostic that stays quiet on healthy input is the
point.

Why this needs to be boring infrastructure

None of this is an indictment of the repos — it's what happens to any
config-by-prose system without a linter. We solved this for code style,
imports, and dead links years ago; instruction files are just the newest
place documentation rots invisibly, with the twist that the reader (an
agent) never complains.

That's the case for making it a CI concern:

scopeglass check . --fail-on error --max-tokens 8000

Exit 1 on broken references or a blown context budget, versioned JSON if you
want to track it over time. Local-only, deterministic, MIT.

Reproduce it

npm i -g scopeglass
node analyze-agents-md.mjs owner/repo another/repo …

The survey script (shallow-clones each repo, runs Scopeglass on every
AGENTS.md directory, dedupes diagnostics, emits this post's table plus a JSON
evidence file) is in a gist. If you run it on your own
monorepo and find something amusing, I'd love to hear about it.

Scopeglass reports expected scope: the canonical ancestor-chain semantics
the format documents. It doesn't claim to know how a specific vendor
assembles prompts, and its conflict heuristic is deliberately narrow — both
limitations are documented in the repo.

DEV Community: Isaac Johnson

I audited the AGENTS.md files of 8 popular open-source repos. Here's what coding agents are actually reading.

The numbers

What stood out

Why this needs to be boring infrastructure

Reproduce it