AGENTS.MD

AGENTS.md:
how Codex, Cursor and Claude Code read it.

AGENTS.md is a Markdown file in your repo that tells coding agents how to build, test and change your code. Codex, Cursor and Copilot read it as is; Claude Code by default reads it only when no CLAUDE.md or CLAUDE.local.md sits in or above your folder, so import it with @AGENTS.md if you keep both.

Start freeGet started Explore the team demo

Free for 3 seats · No credit cardStarter covers 3 seats · Pro is $49 a month for 5 · The demo needs no signup

Open the live team demo

Sample data, no signup · Create a free accountCreate your account

Zest lemon in its mech suit

01See your team’s AI stack

Winding / Teams Last 30 days

Zest

3 Members 1 Agent
Team overview
67%
AI Adoption▲ 34 pts
240
PRs Merged▲ 101
96.1h
Median AI Time▲ 9.5h
57.2h
Build Hours▲ 20.3h
This week
Member AI PRs/wk AI Task Plan Impl Last Standup AI Stack
22.8/wk28 min ago
15.8/wk12 min ago
4/wkAug 14
—2 hours ago
Current AI models & harnesses As of Sep 8
Claude CodeFable 5.1 (max) (with fallback)70.4 · Coding Agent Index
CodexGPT-6 Astra (max)67.0 · Coding Agent Index
Muse CodeMuse Spark 1.3 (xhigh)64.2 · Coding Agent Index
Grok BuildGrok 4.5 (high)64.1 · Coding Agent Index
Kimi Code CLIKimi K362.6 · Coding Agent Index
OpencodeGemini 3.8 Flash (high)61.2 · Coding Agent Index
Cursor CLIComposer 2.5 Fast38.3 · Coding Agent Index

Demo setups use current model families. The pairings above are the combinations benchmarked by Artificial Analysis; rankings measure performance, not popularity.

Intelligence Index

Illustrative daily trends · Other totals: last 30 days. Build Hours: this week, model-estimated activity including overlap; not engineer hours.

USED BY ENGINEERING TEAMS AT

Flyps Charm Wildfires Geoforge MisaLabs

What goes in an AGENTS.md file

Write down what an agent can't work out from the code itself: the exact commands to install, test and lint, the conventions no linter checks, and the mistakes it keeps making. There are no required fields. It's plain Markdown under any headings you like.

  • Commands with their real flags. Agents use what the file names: in one study, agents ran uv 1.6 times per task when the file mentioned it, and almost never when it didn't.
  • Choices the code doesn't show: the package manager, the test runner, where new files go, which folders are generated.
  • How to finish: what to run before a commit, how to title a pull request.
  • Review rules. Codex's code review on GitHub follows a ## Code Review Rules section in the AGENTS.md nearest the code it reviews.

AGENTS.md example

The first file is the example on agents.md: a dozen lines, commands first. The second is real, from a subfolder of our monorepo, for a server that is built with Bun but runs on Cloudflare Workers. That's the kind of fact an agent gets wrong on its own. The file is a CLAUDE.md in that repo, and the lines would read the same in an AGENTS.md.

AGENTS.md (the example on agents.md)
# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible
apps/mcp-server/CLAUDE.md (ours, excerpt)
## Runtime

**Cloudflare Workers** — not Bun. Bun is the dev toolchain (install, test, scripts) but the server runs on CF Workers with `wrangler`.

- Use the Supabase JS client for data access, not raw Postgres drivers

### Deployment

Secrets are managed via `wrangler secret put <NAME>`. Never hardcode secrets or commit them to source.

Where each coding agent looks for AGENTS.md

All four can read an AGENTS.md at the repo root. They differ on three things: whether a file in a subfolder loads, which file wins when two disagree, and what else they read next to it.

From OpenAI's Codex AGENTS.md guide, Anthropic's Claude Code memory docs, Cursor's rules docs and help page, and GitHub's custom instructions support table, read November 11, 2026.
Reads AGENTS.md fromWhen two files disagreeAlso reads
Codex~/.codex, then each folder from the repo root down to where you started itThe nearest one is read last and wins; AGENTS.override.md replaces AGENTS.md in its folderFilenames you add to project_doc_fallback_filenames
Claude Code (2.1.277 and later)Your folder and every folder above it at launch; a subfolder's when Claude opens a file thereAll of them load, root first, so the nearest is read lastCLAUDE.md and CLAUDE.local.md, which by default replace AGENTS.md; .claude/rules/
CursorThe project root and any subfolderA nested file combines with its parents, and the more specific one takes precedence.cursor/rules/*.mdc, and CLAUDE.md in every chat
GitHub CopilotAny folder, in Chat in VS Code, the cloud agent, the Copilot CLI and code review on GitHubThe nearest AGENTS.md in the directory tree.github/copilot-instructions.md and .github/instructions/*.instructions.md; a root CLAUDE.md or GEMINI.md in the cloud agent, CLI and code review; REVIEW.md in code review on GitHub

How Codex finds AGENTS.md

Codex builds its instruction chain once per run, or once when a TUI session starts. First your Codex home: ~/.codex/AGENTS.override.md if it exists, otherwise ~/.codex/AGENTS.md. Then each folder from the project root, usually the Git root, down to your current directory, taking at most one file per folder: AGENTS.override.md, else AGENTS.md, else a name from project_doc_fallback_filenames.

The files are joined root first, so the nearest one comes last and wins a conflict. Two details catch people out. A file in a folder below the one you started in isn't loaded; Codex's base instructions only tell the model to look for one when it works there. And all project files share one budget, project_doc_max_bytes, 32 KiB by default: past it Codex cuts the text and warns that it loaded only part of the file.

/init in the Codex CLI writes a starter AGENTS.md in the current folder.

  • Start Codex in the folder whose rules you need, for example codex --cd services/payments, so that folder's file is on the path.
  • Delete a global AGENTS.override.md when you're done with it, and Codex goes back to ~/.codex/AGENTS.md.
  • A project you marked trust_level = "untrusted" in ~/.codex/config.toml loads no project AGENTS.md at all, according to Codex's source.
  • Set CODEX_HOME to give Codex another home folder, for example for an automation user.
Ask Codex what it loaded (OpenAI's check)
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
~/.codex/config.toml: extra filenames and a 64 KiB budget
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Does Claude Code read AGENTS.md?

Yes, since version 2.1.277, as long as no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in your working folder or any folder above it. Claude Code then loads every AGENTS.md from your folder upward at launch, adds a subfolder's file when it opens a file in that subfolder, and says so in the session: no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.

The trap is CLAUDE.local.md. Create one for your own uncommitted notes and it counts as a CLAUDE.md, so Claude stops reading the team's AGENTS.md for you. Your ~/.claude/CLAUDE.md and .claude/rules/ don't count. Claude Code never reads AGENTS.override.md, AGENTS.local.md or anything under .agents/, and /memory lists the files it did load.

To change the rule, open /config and set Project instructions:

  • claude-md-or-agents-md, the default: CLAUDE.md files, or AGENTS.md when there are none.
  • claude-md-and-agents-md: both, each folder's CLAUDE.md first, and no AGENTS.md loaded twice.
  • claude-md: CLAUDE.md files only.
  • managed-only: just your organization's managed CLAUDE.md and auto memory at launch.

AGENTS.md vs CLAUDE.md: one file for every agent

Make AGENTS.md the file you edit. Codex, Cursor and Copilot read it directly, and Claude Code does too while there's no CLAUDE.md.

Two files kept by hand drift apart. One of our repos had a CLAUDE.md and an AGENTS.md side by side, about 4,000 lines between them. Merged into one AGENTS.md on September 26, 2026, they came to about 640, and the merge turned up rules that no longer matched the repo, such as where pull requests deploy.

Plan for Cursor and Copilot: Cursor applies a CLAUDE.md in every chat, and Copilot's cloud agent, CLI and code review read a root CLAUDE.md, so Claude-only lines in it reach them too. The @AGENTS.md line is only a pointer there, which is fine, since Cursor loads AGENTS.md on its own. Codex is the reverse. It ignores CLAUDE.md unless you add it to project_doc_fallback_filenames, and then reads it only in folders that have no AGENTS.md.

If you need Claude-specific lines, or some engineers run a Claude Code older than 2.1.277, add a CLAUDE.md that imports AGENTS.md. A symlink (ln -s AGENTS.md CLAUDE.md) works too, except for anyone on Windows: Git checks a committed symlink out as a one-line text file unless core.symlinks is on. The import, as Anthropic writes it, reads AGENTS.md first and your Claude lines after:

CLAUDE.md
@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

How long should AGENTS.md be?

Shorter than most end up. Anthropic's target for a CLAUDE.md is under 200 lines, because a longer file costs context and gets followed less, and Cursor advises keeping a rule under 500. Codex has a hard limit: the 32 KiB budget above.

We found that limit in our own repo while writing this page. The merged AGENTS.md from the story above was 663 lines and 37,896 bytes on November 11, 2026. Under Codex's default budget the cut falls at line 573, so the last 90 lines, which hold our pull request review workflow, the summary block every pull request should end with and a Turborepo note, never reach Codex unless an engineer raises project_doc_max_bytes. The file's first section points readers to that workflow.

Two habits keep a file small. Link to details instead of pasting them: our main repo's root file points to docs/agents/commands.md for every build and test command in one line, and a plain Markdown link costs nothing until the agent opens it. And move long procedures into skills, which load only when a task needs them (Codex skills, Claude Code skills).

Does AGENTS.md actually help coding agents?

Not by much, in a 2026 study. Gloaguen and co-authors (arXiv 2602.11988, revised September 29, 2026) ran Claude Code, Codex on two models and Qwen Code on SWE-bench tasks and on 138 tasks from 12 repos that ship their own context files. Files the agents generated for themselves lowered success by 0.5% and 2% on the two sets and raised cost by 20% and 23%. Files the repos' developers wrote raised success by 2.4% on average, and cost by up to 19%. None of the success changes was statistically significant.

What held up: the agents did what the files told them, which is why runs got longer. What didn't help was the repository overview the generators are told to write. The authors' advice is to keep only what the codebase doesn't already say.

Our own repos show the limit from the other side. Both ask, in their instruction files, that every pull request an agent opens end with a short block about the session. Of the 1,570 pull requests merged from August 12 to October 4, 2026, 866 carried it, 55%, and about three in four of the rest still carry Claude Code's signature (the full study). Treat the file as advice: anything that must happen every time belongs in a hook or a CI check (Claude Code hooks).

What doesn't belong in AGENTS.md

Most of what makes the file long is something the agent already knows, or something that works better somewhere else:

  • Style rules your linter or formatter already enforces. Cursor's docs say to use a linter, and OpenAI leaves formatting and lint checks to CI even in review rules.
  • Commands every agent knows, like git or pytest. Name the unusual ones.
  • A tour of the folders. Repository overviews didn't help in the study above; point to the one file that shows the pattern instead of copying it.
  • Long procedures and rules for one corner of the repo. A skill, a path-scoped rule or a nested AGENTS.md loads them only where they apply.
  • Personal preferences. They go in ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md or Cursor's user rules.
  • Rules that must never break. Agents treat the file as context, not enforcement, so block the action with permissions or a hook.
  • Tokens, passwords, anything you wouldn't commit. The file lives in Git and goes into every session's context.

Seeing what an AGENTS.md change does to your team's sessions

Neither the vendors nor the study can tell you what an edit does in your repo. Zest's plugins for Claude Code and Codex record each session's model, tokens, cost, skills and tool calls, and the Zest GitHub App ties each session to the pull request it led to. Sessions from before and after an AGENTS.md change are there to compare per engineer: tokens per session, the tool calls the agent made, and how many ended in a merged pull request.

What Zest doesn't do: read or version your AGENTS.md, or show which instruction files an agent loaded. It uploads no code diffs, works with GitHub only, and its plugins are closed source. Setup is one plugin per agent (Codex, Claude Code).

TRY IT ON YOUR TEAM

See what your team ships with AI.

Starter is free (3 seats, no credit card). Pro is $49 a month with 5 seats and Max is $149 a month with 10 seats — priced per workspace, not per engineer, with extra seats at $19 a month. See pricing

A FEW THINGS TO KNOW

Questions

Should AGENTS.md be committed?+

Yes. It's written for everyone who works in the repo, and committing it means every engineer's agent starts from the same rules. Keep personal preferences out of it: those go in ~/.codex/AGENTS.md for Codex or ~/.claude/CLAUDE.md for Claude Code.

What is the difference between AGENTS.md and CLAUDE.md?+

They do the same job for different readers. AGENTS.md is the open format that Codex, Cursor, Copilot and many other agents read; CLAUDE.md is Claude Code's own file, with extra user, local and organization-wide scopes. Cursor reads both, and Claude Code by default reads AGENTS.md only when no CLAUDE.md or CLAUDE.local.md sits in your folder or above it.

What is AGENTS.override.md?+

A Codex file that takes the place of AGENTS.md in the same folder, or of your global file when it sits in ~/.codex. Use it for a temporary or team-specific override and delete it to go back. Claude Code doesn't read it.

Can a repo have more than one AGENTS.md?+

Yes, one per folder. When the agents.md site last counted, OpenAI's main repo had 88. Codex loads the files from the repo root down to the folder you started in; Cursor combines a nested file with its parents, the more specific one winning; Copilot follows the nearest one.

Do Gemini CLI and Aider read AGENTS.md?+

With one setting each, per the agents.md site: set context.fileName to AGENTS.md in .gemini/settings.json for Gemini CLI, and add read: AGENTS.md to .aider.conf.yml for Aider.