Skip to content
Agent Friendly Code

How long should an AGENTS.md be?

The median AGENTS.md or CLAUDE.md in 226 popular open source repos is 6,942 characters, and half of them fall between 3,271 and 12,769. Below: the spread, the files long enough that an agent loads only part of them, and what the agents' own docs advise.

Median length

6,942

characters, across 226 files

Median AGENTS.md

7,400

characters, 207 repos

Median CLAUDE.md only

5,626

characters, 18 repos

Over Devin's 16 KiB

19%

39 of 207 AGENTS.md files; 7 are over Codex's 32 KiB

Sizes of 226 files, in characters

10th percentile
1,237
25th
3,271
Median
6,942
75th
12,769
90th
20,082
  • Under 1K21 (9%)
  • 1K–4K54 (24%)
  • 4K–8K51 (23%)
  • 8K–16K60 (27%)
  • 16K–32K33 (15%)
  • Over 32K7 (3%)

1K is 1,024 characters, so the last two edges are Devin's 16 KiB (16,384) and Codex's 32 KiB (32,768). Those caps are in bytes; for plain ASCII text a character is a byte, and accents, emoji or CJK text make a file larger in bytes than its count here.

Median length by stars

Median instructions file length by the repo's stars
StarsFilesMedian chars
Under 10k ★407,860
10k–30k ★555,398
30k–100k ★1027,190
100k+ ★2911,708

Median length by language

Median instructions file length by the repo's main language
LanguageFilesMedian chars
TypeScript649,347
Python296,301
Rust248,357
Go234,648
Java197,099
C++118,107

Languages with at least 8 files.

Longest and shortest files that pass

Longest

Longest AGENTS.md or CLAUDE.md files
RepoFileLength
modelcontextprotocol/serversAGENTS.md 51,045
coollabsio/coolifyAGENTS.md 46,544
cloudflare/vinextAGENTS.md 41,619
krakenfx/kraken-cliAGENTS.md 39,417
webpack/webpackAGENTS.md 35,357

Shortest at 800+ characters

Shortest AGENTS.md or CLAUDE.md files that pass
RepoFileLength
scylladb/scylladbAGENTS.md 865
lit/litAGENTS.md 924
nuxt/nuxtAGENTS.md 947
antiwork/gumroadAGENTS.md 978
meilisearch/meilisearchAGENTS.md 989

Is longer better?

Median overall score by instructions file size
SizeFilesMedian score
Under 1K2172
1K–4K5473
4K–8K5173
8K–16K6077
16K–32K3375
Over 32K776
No file17660

Correlation, not cause. The AGENTS.md check is part of the score and gives files under 800 characters partial credit, so the gap between no file and a file is partly built in. Repos that keep a detailed file may also be the ones with the tests, CI and setup the rest of the score counts. Nothing here says a longer file makes an agent work better.

What the agents' docs say

  • Claude Code targets under 200 lines per CLAUDE.md: longer files “consume more context and reduce adherence.” Instructions for one part of the codebase belong in path-scoped rules under .claude/rules/, which load only for matching files; @path imports organise a long file but don't shrink what it costs (memory docs (new tab), best practices (new tab)).
  • Codex stops adding instruction files once their combined size reaches project_doc_max_bytes, 32 KiB by default. Its fix: raise the setting or split large files across nested directories (Codex docs (new tab)).
  • Devin includes the first 16 KiB of each AGENTS.md; what comes after it reads only on demand. It advises keeping critical instructions near the top and always-on guidance under 16 KiB (Devin docs (new tab)).

So how long should yours be?

  • Short enough that every line earns its place. The typical file here is about 6,942 characters; past 16 KiB, Devin no longer loads all of it up front.
  • Commands first: install, test, a single test, lint and typecheck. Then what the code can't tell an agent: traps, decisions, the rules that keep getting broken.
  • Leave out what an agent can read from the code or the README, and move rules for one directory into that directory's own file.
  • Under 800 characters, the AGENTS.md check gives partial credit: a file that short rarely holds the commands and the traps.

Real AGENTS.md examples →

Methodology

  • One file per repo: the AGENTS.md or CLAUDE.md the check found at the root, with content. Nested files aren't measured, so a repo under Codex's cap here can still exceed it once they add up.
  • Length is characters after trimming leading and trailing whitespace. Claude Code's guidance counts lines, which we don't.
  • A token is roughly four characters of English, so the median file is about 1,736 tokens; code and other languages vary.
  • The sample is the leaderboard, rescored daily. Adoption over time: State of AGENTS.md adoption.