Which coding agents read AGENTS.md: Claude Code, Codex, Cursor, Copilot, Windsurf and Gemini CLI?

Kayvan Zahiri · October 25, 2026

Codex, Cursor, GitHub Copilot and Windsurf read AGENTS.md as written. Claude Code reads it when the project has no CLAUDE.md (v2.1.277 or later); with a CLAUDE.md, add @AGENTS.md to it. Gemini CLI reads GEMINI.md by default and reads AGENTS.md once you add it to context.fileName. So one AGENTS.md at the root, plus a one-line CLAUDE.md, covers all six.

BuildGist is a Mac app for Claude Code, Cursor and Codex. Download for Mac.

Tool by tool

Codex reads a global file in ~/.codex (AGENTS.override.md first, then AGENTS.md), then one file per folder from the project root down to where you are. Files closer to you come later and win. The combined size is capped by project_doc_max_bytes, 32 KiB by default. Other file names can be added with project_doc_fallback_filenames.
Claude Code reads AGENTS.md when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above. With one of those present, it reads only those, unless they import @AGENTS.md. Imports go up to four levels deep.
Cursor reads AGENTS.md at the project root and in subfolders, as a plain-markdown alternative to .cursor/rules/*.mdc.
GitHub Copilot reads AGENTS.md files, and the nearest one to the file being worked on takes precedence. Support varies by editor and feature; GitHub keeps a table. It also has its own .github/copilot-instructions.md.
Windsurf (its documentation now says Devin Desktop) treats a root AGENTS.md as always on and one in a subfolder as a rule for that folder.
Gemini CLI reads GEMINI.md unless .gemini/settings.json lists other names: {"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}}.

The setup that works in all six

AGENTS.md                       shared rules: stack, commands, style, what never to touch
CLAUDE.md                       @AGENTS.md
.gemini/settings.json           {"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}}
packages/api/AGENTS.md          optional: rules for that folder only

Some people symlink instead, ln -s AGENTS.md CLAUDE.md. It works on a Mac, but an import keeps room for a few lines only Claude Code needs, and it survives tools and systems that handle symlinks badly.

What to put in it

How to install, build and run the tests, as exact commands.
Conventions an agent cannot infer: naming, where new files go, the error style.
What never to touch: generated folders, migrations already applied, secrets.
One line pointing to a task note, if you keep one: "If HANDOFF.md exists, read it first."

Keep it short. Anthropic suggests under 200 lines for CLAUDE.md, and Codex stops at 32 KiB by default. Long files cost context in every session.

Files in subfolders

A nested AGENTS.md adds rules for one part of the project, and each tool resolves it its own way. Codex joins files from the root down, so the one closest to your current folder comes last and wins. Cursor combines nested files with their parents, with the more specific one taking precedence. Windsurf applies a subfolder file only to files under that folder. Copilot uses the nearest file. In Claude Code, nested CLAUDE.md files load when Claude works in that folder.

Check what each tool loaded

Claude Code: /memory.
Gemini CLI: /memory show.
Codex: ask it to summarize its current instructions. Codex's guide suggests this check.
Cursor and Windsurf: the rules panel in settings lists what applies.

What AGENTS.md does not carry

It holds rules, not the task. It cannot say what you asked for an hour ago, what is half done, or what you already ruled out. That lives in each tool's own chat, which the others cannot read. A short handoff note covers it, and so does BuildGist's Continue between Claude Code, Cursor and Codex: start a new chat in one of them in the same project and the card offers the earlier task. Continue does not read or change AGENTS.md or CLAUDE.md. How the two approaches compare is in BuildGist vs CLAUDE.md, AGENTS.md and HANDOFF.md, and the full layout with a handoff note is in how to keep context across Claude Code, Cursor and Codex.

Questions

Does Claude Code support AGENTS.md?

Yes, from v2.1.277, when there is no CLAUDE.md in the working directory or above. Otherwise put @AGENTS.md in CLAUDE.md.

Does Gemini CLI read AGENTS.md?

When you list it in context.fileName in .gemini/settings.json. By default it reads GEMINI.md.

Should I symlink CLAUDE.md to AGENTS.md?

It works, but a CLAUDE.md that imports @AGENTS.md does the same job and leaves room for lines only Claude Code needs.

Sources

Codex AGENTS.md guide, Claude Code memory, Cursor rules, checked October 25, 2026.
GitHub Copilot repository instructions, Windsurf AGENTS.md and Gemini CLI GEMINI.md, checked October 25, 2026.

What you need

A Mac with Apple silicon and macOS 12 or later.
Claude Code, Cursor or Codex.
A Git project. No commit, push, remote or GitHub repository is needed.
A GitHub account, to sign in. BuildGist does not access your GitHub repositories.

Codex needs you to approve BuildGist once, in Codex. BuildGist shows the steps. Setup is in Getting started.

To explain a run, your computer sends BuildGist what that run needs, and BuildGist passes it to Anthropic. BuildGist does not keep this material. It does not send your whole repository, files the run did not change, or files named like secrets, such as .env files and keys. It keeps the explanation and short cited excerpts of changed code, at most 12 lines each. Secret masking is best-effort. Privacy has the full list.

Every account gets 7 days of BuildGist Pro free, with no card. The 7 days start at your first explanation or Continue handoff. Nobody is charged when the trial ends. After that, BuildGist Pro is $12 per month, plus any applicable tax shown at checkout. See pricing.

Try BuildGist Download for Mac

Apple silicon, macOS 12 or later. United States, 18 or older.

Questions: kayvanandre@gmail.com.