AGENTS.md vs CLAUDE.md: which file does each coding agent read?
Claude Code, Cursor, GitHub Copilot, Gemini CLI and Codex each load different instruction files. Here is what each one reads, and how to keep one source of truth.
Updated 2026-10-06
Most teams now use more than one coding agent. Each agent reads its own instruction files, and they do not agree on which ones. In our benchmark of public repositories, nearly half of those with agent instructions keep them in two or more tools’ formats, and many tool-specific files never see the shared one. The result is predictable: the copies drift, and agents follow different rules in the same repository.
What each agent loads
| Agent | Reads | Notes |
|---|---|---|
| Claude Code | CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md from the working directory up; .claude/rules; @imports | Reads AGENTS.md only when no CLAUDE.md exists (recent versions). Subdirectory files load on demand. |
| Cursor | .cursor/rules/*.mdc (description, globs, alwaysApply) and AGENTS.md | Legacy .cursorrules is no longer documented and may not load. |
| GitHub Copilot | .github/copilot-instructions.md and .github/instructions/*.instructions.md | AGENTS.md, CLAUDE.md and GEMINI.md are read by the cloud agent only, not by every Copilot surface. |
| Gemini CLI | GEMINI.md (or the names in context.fileName) at the root and ancestors; @imports | Subdirectory files load just in time and are concatenated. |
| Codex and other AGENTS.md readers | AGENTS.md at the root and in subdirectories, nearest file wins | Codex also honours AGENTS.override.md in the same directory. |
These summaries are taken from each tool’s documentation and dated on our tools page. Tools change often; run threadctx explain to see what applies to your repository today.
The pattern that works: one source, thin pointers
- Keep the real instructions in AGENTS.md: exact build, test and lint commands, and the conventions an agent cannot discover by reading the code.
- Make CLAUDE.md a pointer: a single line, @AGENTS.md, imports it, so Claude Code reads the same text.
- Point GEMINI.md at AGENTS.md the same way, or set context.fileName to AGENTS.md.
- Keep Cursor rules and Copilot path instructions for what is genuinely path-specific, and do not restate the shared rules in them.
# CLAUDE.md
@AGENTS.md
# Claude-only notes, if any, go below the import.Check it
threadctx shows what each agent actually receives for a given file, and flags the drift: conflicting package managers, scripts that do not exist, copies that diverged, and tool-specific files that never see the shared one.
npx threadctx explain src/server.ts --tool all
npx threadctx diff
npx threadctx fix --pr