AGENTS.md vs CLAUDE.md: which file each AI coding tool reads
Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI, from each vendor's own docs. No single file covers all five by default.
As of September 30, 2026. Next full re-check due by December 29, 2026.
Short answer: write AGENTS.md. Codex, Cursor and GitHub Copilot's agent read it by default. Claude Code reads it when there's no CLAUDE.md, or through a one-line import. Gemini CLI needs one setting. The last section shows the setup.
| Tool | Reads CLAUDE.md | Reads AGENTS.md | Its own file |
|---|---|---|---|
| Claude Code | Yes | If there's no CLAUDE.md, or with a setting | CLAUDE.md |
| Codex | Not by default | Yes | AGENTS.md |
| Cursor | Its command-line tool does | Yes | .cursor/rules/*.mdc |
| GitHub Copilot | Agent and CLI | Yes | .github/copilot-instructions.md |
| Gemini CLI | Not by default | With a setting | GEMINI.md |
Tool by tool
Claude Code reads CLAUDE.md first, and AGENTS.md when there's none or a setting says so
Anthropic's memory docs: "By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it." A CLAUDE.local.md counts as a CLAUDE.md for that check. The Project instructions option in /config can make it read both. AGENTS.md support arrived in version 2.1.277.
Codex reads AGENTS.md, up to 32 KiB of it by default
OpenAI's AGENTS.md docs chain the files: a global one in ~/.codex/, then one per directory from the repository root down. An AGENTS.override.md beats an AGENTS.md in the same directory. The combined size is capped at 32 KiB, about 32,000 characters. CLAUDE.md isn't read unless you list it in project_doc_fallback_filenames.
Cursor reads AGENTS.md, and its command-line tool also reads CLAUDE.md
Cursor's rules docs: "Cursor supports AGENTS.md in the project root and subdirectories." Its own rules are .mdc files in .cursor/rules/. The CLI docs add: "The CLI also reads AGENTS.md and CLAUDE.md at the project root (if present)." The editor's docs don't mention CLAUDE.md.
GitHub Copilot's agent and CLI read AGENTS.md, CLAUDE.md and GEMINI.md
GitHub's instructions support table lists all three for the Copilot coding agent and Copilot CLI. Copilot Chat in VS Code gets AGENTS.md only. Copilot's own file is .github/copilot-instructions.md. With several AGENTS.md files, "the nearest" one in the directory tree takes precedence.
Gemini CLI reads GEMINI.md unless you change one setting
GEMINI.md is the default in the Gemini CLI docs. The context.fileName setting in settings.json replaces that name with a list. Google's example lists AGENTS.md, CONTEXT.md and GEMINI.md. Without the setting, Gemini CLI reads neither AGENTS.md nor CLAUDE.md.
One set of instructions for all five
Write AGENTS.md, then point Claude Code and Gemini CLI at it
- Codex, Cursor, Copilot: AGENTS.md as is.
- Claude Code: a CLAUDE.md containing the line
@AGENTS.md. Anthropic's docs suggest this. - Gemini CLI: in
.gemini/settings.json, set"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}. List both, or GEMINI.md stops loading.
The New Way is written with AI. It gathers the day's stories, checks them against their sources and drafts every summary. A person decides what runs and reviews every issue before we hit send.