CLAUDE.md vs AGENTS.md vs GEMINI.md: How Each CLI Reads Project Context

If your team uses more than one AI coding CLI, you have probably hit this: you wrote a careful instructions file, switched tools, and the new agent ignored it completely. That is not a bug. Claude Code, OpenAI Codex CLI, and Gemini CLI each look for a different filename, discover it differently, and cap its size differently. Get the filename or the precedence wrong and the agent simply doesn't see your rules.

This guide covers how each CLI reads project context, whether the tools read each other's files, and how to maintain one source of truth without drift.

The three files at a glance

The headline: AGENTS.md is the only one that's a real cross-tool standard. The other two are tool-specific names.

Claude Code: CLAUDE.md

Claude Code reads CLAUDE.md files (not AGENTS.md). These are Markdown instruction files loaded into the context window at the start of every session. Worth knowing: they're delivered as a user message after the system prompt, not as part of the system prompt itself.

There are four scope tiers, loaded broadest to most-specific:

1. Managed policy — /Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux/WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows)
2. User — ~/.claude/CLAUDE.md
3. Project — ./CLAUDE.md or ./.claude/CLAUDE.md
4. Local — ./CLAUDE.local.md (gitignored)

Discovery walks up the directory tree from where you launched, concatenating every file it finds (it does not override). Content is ordered root-down, so instructions closest to your launch directory are read last. Within a directory, CLAUDE.local.md is appended after CLAUDE.md. Subdirectory CLAUDE.md files are not loaded at launch — they load on demand when Claude reads files in those directories.

CLAUDE.md supports importing other files with @path/to/import syntax (relative or absolute), recursively up to four hops deep. Imported files load in full at launch alongside the referencing file.

Keep each CLAUDE.md under roughly 200 lines. CLAUDE.md is always loaded in full regardless of length, so a bloated file silently eats context and degrades instruction adherence. The 200-line / 25 KB cap you may have heard about applies to the separate auto-memory MEMORY.md, not to CLAUDE.md.

Two adjacent systems are easy to confuse with CLAUDE.md:

• Auto memory — Claude writes its own notes under ~/.claude/projects/<project>/memory/ with a MEMORY.md index. It's on by default (v2.1.59+) and is distinct from your hand-authored CLAUDE.md.
• Path-scoped rules — .claude/rules/*.md files with YAML frontmatter. A paths glob field loads instructions only when Claude touches matching files. Rules without a paths field load at launch at the same priority as .claude/CLAUDE.md.

Does Claude Code read AGENTS.md?

No, not natively. The official workarounds:

# Option A: import it from CLAUDE.md
echo "@AGENTS.md" > CLAUDE.md

# Option B: symlink (needs Admin/Developer Mode on Windows)
ln -s AGENTS.md CLAUDE.md

Running /init in a repo that already has AGENTS.md will read it and incorporate the relevant parts (it also reads .cursorrules, .devin/rules/, and .windsurfrules).

Codex CLI: AGENTS.md

OpenAI Codex CLI reads AGENTS.md (and AGENTS.override.md or configured fallback names) — not CLAUDE.md. Its discovery order:

1. ~/.codex/AGENTS.override.md if it exists, else ~/.codex/AGENTS.md. Only the first non-empty file at this level is used.
2. From the Git project root walking down to your cwd, checking each directory for AGENTS.override.md, then AGENTS.md, then project_doc_fallback_filenames — at most one file per directory.

Files concatenate root-down, so files closer to cwd appear later in the combined prompt and effectively override earlier guidance.

The combined AGENTS.md size is capped at project_doc_max_bytes, which defaults to 32 KiB. You can raise it in config, or work around it by splitting instructions across nested directories. The project_doc_fallback_filenames setting lets you treat alternate filenames as instruction files.

Gemini CLI: GEMINI.md

Gemini CLI loads GEMINI.md context files hierarchically from three locations:

1. Global — ~/.gemini/GEMINI.md
2. Project hierarchy — searched from cwd upward to the project root (the .git folder)
3. Subdirectories — scanned below cwd, respecting .gitignore and .geminiignore

All discovered files are concatenated and sent with every prompt. Gemini supports @file.md imports (relative and absolute).

The genuinely useful part for multi-tool teams: Gemini CLI has a configurable context filename via settings.json (context.fileName), which accepts an array like ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]. So you can point Gemini CLI at AGENTS.md directly — it's the one mainstream CLI that reads the standard out of the box once configured.

Gemini CLI also ships /memory commands: /memory show displays the concatenated hierarchical content, /memory refresh reloads everything, and /memory add <text> appends to ~/.gemini/GEMINI.md.

What about Google Antigravity?

This is where the research gets thinner, so I'll hedge. Google Antigravity reads AGENTS.md for agent instructions and supports skills under .agents/skills/, mounting files into a sandbox. The Antigravity API docs do not mention GEMINI.md. Some secondary sources report Antigravity also uses GEMINI.md at the project root alongside .agents/ files, and that a 2026 release added AGENTS.md rules-file support capped at 12,000 characters each — but that's lower-confidence reporting. If you're targeting Antigravity, lead with AGENTS.md, which is documented.

AGENTS.md is the actual standard

AGENTS.md is an open format — "a README for agents" — stewarded by the Agentic AI Foundation under the Linux Foundation, born from collaboration across OpenAI Codex, Amp, Google Jules, Cursor, and Factory. It's plain Markdown with no required fields.

For monorepos, agents automatically read the nearest file in the tree: the closest AGENTS.md to the edited file takes precedence, and an explicit user prompt overrides everything. agents.md notes that OpenAI's main repo contains 88 AGENTS.md files and 60k+ open-source projects use the format. The supporting-tools list runs past 25, including Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, JetBrains Junie, Amp, Cursor, RooCode, Gemini CLI, GitHub Copilot Coding Agent, Windsurf, and Augment Code.

The recommended setup for multi-tool teams

Maintain one source of truth and avoid file drift. The practical pattern:

1. Write your real instructions in AGENTS.md (the cross-tool standard).
2. Point Claude Code at it: either @AGENTS.md inside CLAUDE.md, or ln -s AGENTS.md CLAUDE.md.
3. Configure Gemini CLI's context.fileName to include AGENTS.md.
4. Codex reads AGENTS.md natively — nothing to do.

Maintaining separate, independently-edited files is what causes inconsistent AI behavior across tools. One file, referenced everywhere.

What belongs in the file (and what doesn't)

Keep it short — best-practice sources converge on ~150 lines, with research across 2,500+ repos suggesting length beyond that gives diminishing returns and can raise inference costs ~20–23%. Recommended sections:

• Project overview
• Build / test commands
• Code style
• Testing instructions
• Security considerations
• Commit / PR guidelines
• Deployment steps

What does not belong: anything that's better expressed as a path-scoped rule (Claude's .claude/rules/*.md), a reusable skill, or a hook. The context file is for always-on, project-wide guidance — not for instructions that only apply to one directory or one workflow.

Bottom line

Three CLIs, three filenames, three discovery rules. Claude Code reads CLAUDE.md (walk up, concatenate, ~200-line target). Codex reads AGENTS.md (home file + walk down, 32 KiB cap). Gemini reads GEMINI.md but can be told to read AGENTS.md. None of them read each other's files automatically — except Gemini once configured.

AGENTS.md is the only real standard, so make it your single source of truth, then symlink or @import it into CLAUDE.md and add it to Gemini's context.fileName. Keep it under ~150 lines, put always-on guidance there, and push anything narrower into rules, skills, or hooks. Do that once and every agent on your team reads the same playbook.