Which files each coding agent reads
Instruction, rules, skills, hooks and MCP config files for seven coding agents: where each one looks, which file wins when several are present, and the version a behaviour started, with a link to the vendor's own docs for every cell.
Every cell checked against current vendor docs and changelogs on . Machine-readable: /api/agent-files.json. Spotted something out of date? Tell us in the notes field.
At a glance: does it read this file?
Project files only, with the agent started at the repo root. "Opt-in" means only after you change a setting; "Partly" means only in some cases (hover or read the note).
| File | Claude Code | Codex CLI | Cursor | Gemini CLI | Antigravity CLI | GitHub Copilot | Hermes Agent |
|---|---|---|---|---|---|---|---|
AGENTS.md | Partly Only when there is no CLAUDE.md (v2.1.277+), or via @AGENTS.md | Yes Main instruction file | Yes Root and nested | Opt-in Only if listed in context.fileName | Yes Root, .agents/ and subdirectories | Yes Nearest one wins on GitHub | Yes Unless .hermes.md or AGENTS.override.md is present |
CLAUDE.md | Yes Main instruction file | Opt-in Only via project_doc_fallback_filenames | No Not in Cursor's rules docs | Opt-in Only if listed in context.fileName | No Not in Antigravity's rules docs | Yes CLI; on GitHub a single root file | Partly Only when there is no .hermes.md or AGENTS.md |
GEMINI.md | No Not read | Opt-in Only via project_doc_fallback_filenames | No Not read | Yes Default context file | Yes Read alongside AGENTS.md | Yes CLI; on GitHub a single root file | No Not in Hermes' context file list |
.cursor/rules/*.mdc | No Only /init reads them to draft a CLAUDE.md | No Not read | Yes Project rules | No Not read | No Uses .agents/rules/*.md | No Uses .github/instructions/ | No Reads only a root .cursorrules, last in line |
.github/copilot-instructions.md | No Only /init reads it to draft a CLAUDE.md | No Not read | No Not read | No Not read | No Not read | Yes Repository-wide | No Not read |
.agents/skills/ | No Uses .claude/skills/ | Yes Project and ~/.agents/skills | Yes Also .cursor, .claude and .codex skills | Yes Beats .gemini/skills in the same tier | Yes Default skills folder | Yes Also .github/skills and .claude/skills | Opt-in Add it to skills.external_dirs |
Want one file every agent reads? One AGENTS.md for every agent sets that up.
Instructions
Plain Markdown read at the start of a session (AGENTS.md and friends).
| Agent | Project | User | Precedence and notes | Since | Source |
|---|---|---|---|---|---|
| Claude Code | CLAUDE.md.claude/CLAUDE.mdCLAUDE.local.mdAGENTS.md.claude/AGENTS.md | ~/.claude/CLAUDE.md | By default AGENTS.md is read only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above. If there is one, Claude reads that instead, unless the CLAUDE.md imports @AGENTS.md or Project instructions in /config is set to claude-md-and-agents-md. Files load from the filesystem root down, so the closest one is read last. Not read: AGENTS.local.md, AGENTS.override.md or anything under .agents/. Subdirectory files load when Claude opens a file there. | v2.1.277 reads AGENTS.md natively when there is no CLAUDE.md | code.claude.com |
| Codex CLI | AGENTS.override.mdAGENTS.md | ~/.codex/AGENTS.override.md~/.codex/AGENTS.md | Global file first, then one file per directory from the project root down to the working directory: AGENTS.override.md beats AGENTS.md, then any project_doc_fallback_filenames. Files are joined root first, so the closest wins. Stops at project_doc_max_bytes (32 KiB by default). CLAUDE.md and GEMINI.md are not read unless you add them to project_doc_fallback_filenames. | Not stated | developers.openai.com |
| Cursor | AGENTS.md (root and subdirectories) | None | Nested AGENTS.md files combine with their parents; the more specific file takes precedence. .cursorrules at the root is legacy and will be deprecated; Cursor's migration advice is an Always Apply rule in .cursor/rules. | Not stated | cursor.com also cursor.com |
| Gemini CLI | GEMINI.md (workspace directories and their parents, plus just-in-time in folders a tool touches) | ~/.gemini/GEMINI.md | Global first, then workspace files, then just-in-time files; all are concatenated. AGENTS.md is read only if you list it in context.fileName in settings.json. Imports use @./file.md. | Not stated | geminicli.com |
| Antigravity CLI | AGENTS.mdGEMINI.md.agents/AGENTS.md.agents/GEMINI.md | ~/.gemini/AGENTS.md~/.gemini/GEMINI.md~/.gemini/config/AGENTS.md~/.gemini/config/GEMINI.md | Cumulative: global, workspace and directory rules are all combined. When Antigravity reads or edits a file it walks up to the workspace root loading each level; on a conflict the more specific directory wins. | Not stated | antigravity.google |
| GitHub Copilot | .github/copilot-instructions.mdAGENTS.mdCLAUDE.md.claude/CLAUDE.md (CLI)GEMINI.md | ~/.copilot/copilot-instructions.md (CLI) | Copilot CLI combines every file that applies and drops identical copies, but sets no general precedence between them, so avoid conflicts. On GitHub, the nearest AGENTS.md in the tree takes precedence, and a single root CLAUDE.md or GEMINI.md can be used instead. @path includes work in copilot-instructions.md, AGENTS.md and CLAUDE.md, not in GEMINI.md. | Not stated | docs.github.com |
| Hermes Agent | .hermes.md / HERMES.mdAGENTS.override.mdAGENTS.mdCLAUDE.md.cursorrules (working directory only) | SOUL.md in HERMES_HOME (identity, always loaded) | One project context type per session, first match wins: .hermes.md → AGENTS.override.md → AGENTS.md → CLAUDE.md → .cursorrules. In a git repo, AGENTS.md files chain from the git root down to the working directory, deepest last. Outside a repo only the working directory is checked. | Not stated | hermes-agent.nousresearch.com |
Rules
Extra instruction files, often scoped to paths or loaded on demand.
| Agent | Project | User | Precedence and notes | Since | Source |
|---|---|---|---|---|---|
| Claude Code | .claude/rules/**/*.md | ~/.claude/rules/**/*.md | Rules without paths frontmatter load at launch with the same priority as .claude/CLAUDE.md. Rules with paths load when Claude reads or edits a matching file. User rules load before project rules; neither overrides the other. | Not stated | code.claude.com |
| Codex CLI | None | None | No separate rules folder: split instructions with nested AGENTS.md or AGENTS.override.md files. | Not stated | developers.openai.com |
| Cursor | .cursor/rules/**/*.mdc | User Rules in Customize → Rules (synced)~/.cursor/rules (this machine only) | Team Rules → Project Rules → User Rules; all applicable rules merge and earlier sources win a conflict. Only .mdc files count: a .md file in .cursor/rules is ignored. alwaysApply, globs and description decide when a rule loads. | Not stated | cursor.com also cursor.com |
| Gemini CLI | None | None | No separate rules folder: split GEMINI.md with @imports or nested GEMINI.md files. | Not stated | geminicli.com |
| Antigravity CLI | .agents/rules/*.md.agent/rules/*.md (legacy) | ~/.gemini/config/rules/*.md (YAML frontmatter required) | Same cumulative order as the instruction files. Only direct .md children of .agents/rules/ are scanned; subfolders are ignored unless registered. | Not stated | antigravity.google |
| GitHub Copilot | .github/instructions/**/NAME.instructions.md | None | Path-specific files with applyTo globs. When one matches and a repository-wide file exists, both are used. | Not stated | docs.github.com |
| Hermes Agent | None | None | No separate rules folder. A .cursorrules file is read only if no higher-priority context file exists. | Not stated | hermes-agent.nousresearch.com |
Skills
Folders with a SKILL.md, loaded when the agent decides a task needs one.
| Agent | Project | User | Precedence and notes | Since | Source |
|---|---|---|---|---|---|
| Claude Code | .claude/skills/<name>/SKILL.md | ~/.claude/skills/<name>/SKILL.md | Enterprise, personal and project skills; nested .claude/skills folders in subdirectories load once Claude works on files there. Files in .claude/commands/ still work and behave like skills. | Not stated | code.claude.com |
| Codex CLI | .agents/skills/<name>/SKILL.md (every directory from the working directory up to the repo root) | ~/.agents/skills/<name>/SKILL.md | Repository, user, admin and system locations are all scanned. Skills with the same name are not merged; both can appear. | Not stated | developers.openai.com |
| Cursor | .agents/skills/<name>/SKILL.md.cursor/skills/<name>/SKILL.md.claude/skills/.codex/skills/ | ~/.agents/skills/~/.cursor/skills/~/.claude/skills/~/.codex/skills/ | Claude and Codex skill folders load for compatibility. Skills in nested project folders only surface for files under that folder. | Not stated | cursor.com |
| Gemini CLI | .agents/skills/<name>/SKILL.md.gemini/skills/<name>/SKILL.md | ~/.agents/skills/~/.gemini/skills/ | Built-in < extension < user < workspace. Within a tier, .agents/skills beats .gemini/skills. | Not stated | geminicli.com |
| Antigravity CLI | .agents/skills/<name>/SKILL.md.agent/skills/ (legacy) | ~/.gemini/antigravity-cli/skills/ | Workspace and global skills; plugins add their own. Gemini CLI's .gemini/skills/ is not read: move it to .agents/skills/. | Not stated | antigravity.google |
| GitHub Copilot | .github/skills/.claude/skills/.agents/skills/ | ~/.copilot/skills/~/.agents/skills/ | Project and personal skills. | Not stated | docs.github.com |
| Hermes Agent | None | ~/.hermes/skills/skills.external_dirs in ~/.hermes/config.yaml (for example ~/.agents/skills/) | ~/.hermes/skills/ is the single source of truth; external directories are scanned alongside it. | Not stated | hermes-agent.nousresearch.com |
Hooks
Commands the agent runs at fixed points, such as before a tool call.
| Agent | Project | User | Precedence and notes | Since | Source |
|---|---|---|---|---|---|
| Claude Code | .claude/settings.json.claude/settings.local.json | ~/.claude/settings.json | Hooks are a "hooks" block in settings files; plugins can bundle hooks/hooks.json. When an event fires, every matching hook runs, in parallel. | Not stated | code.claude.com |
| Codex CLI | .codex/hooks.json[hooks] in .codex/config.toml | ~/.codex/hooks.json[hooks] in ~/.codex/config.toml | All matching hooks from every layer run; higher layers do not replace lower ones. Project hooks load only in trusted projects, and non-managed hooks must be reviewed and trusted before they run. | Not stated | developers.openai.com |
| Cursor | .cursor/hooks.json.claude/settings.json.claude/settings.local.json | ~/.cursor/hooks.json~/.claude/settings.json | Enterprise → Team → .cursor/hooks.json → ~/.cursor/hooks.json → Claude project local → Claude project → Claude user. All matching hooks run; on conflicting responses the higher source wins. Claude Code hooks load while Third-Party Imports is on (the default). | Not stated | cursor.com |
| Gemini CLI | .gemini/settings.json | ~/.gemini/settings.json/etc/gemini-cli/settings.json (system) | Project settings → user settings → system settings (highest to lowest). | Not stated | geminicli.com |
| Antigravity CLI | .agents/hooks.json | ~/.gemini/config/hooks.json | Workspace, global and plugin hooks.json. Hooks in ~/.gemini/antigravity-cli/settings.json are not loaded. | Not stated | antigravity.google |
| GitHub Copilot | .github/hooks/*.json | ~/.copilot/hooks/*.json (CLI) | Repository hooks for Copilot CLI and the cloud agent; personal hooks for the CLI only. | Not stated | docs.github.com |
| Hermes Agent | None | hooks: block in the profile config.yaml (shell hooks)~/.hermes/hooks/ (gateway hooks)plugins | For pre_tool_call, any valid block beats any approve; Python plugins register before shell hooks. | Not stated | hermes-agent.nousresearch.com |
MCP config
Where project and user MCP servers are declared.
| Agent | Project | User | Precedence and notes | Since | Source |
|---|---|---|---|---|---|
| Claude Code | .mcp.json | ~/.claude.json | Project servers in .mcp.json need approving the first time. Local and user servers live in ~/.claude.json. | Not stated | code.claude.com |
| Codex CLI | .codex/config.toml [mcp_servers.<name>] (trusted projects only) | ~/.codex/config.toml [mcp_servers.<name>] | TOML, not JSON. A project .codex/config.toml is read only when the project is trusted. | Not stated | developers.openai.com |
| Cursor | .cursor/mcp.json | ~/.cursor/mcp.json | Both files use mcpServers. Remote servers take tokens through config interpolation, not envFile. | Not stated | cursor.com |
| Gemini CLI | .gemini/settings.json mcpServers | ~/.gemini/settings.json mcpServers | HTTP servers use httpUrl; url means SSE. | Not stated | geminicli.com |
| Antigravity CLI | .agents/mcp_config.json | ~/.gemini/config/mcp_config.json | Remote servers must use Streamable HTTP: serverUrl (url also works). httpUrl and the old HTTP+SSE transport are not supported. | Not stated | antigravity.google |
| GitHub Copilot | .mcp.json.github/mcp.json.vscode/mcp.json (VS Code, "servers" key) | ~/.copilot/mcp-config.json (CLI) | Copilot CLI walks from the working directory to the repo root; .mcp.json beats .github/mcp.json in the same folder, closer files beat further ones, and project files beat ~/.copilot/mcp-config.json. | Not stated | docs.github.com |
| Hermes Agent | None | mcp_servers in ~/.hermes/config.yaml | hermes import-agent claude-code can bring servers across from ~/.claude.json. | Not stated | hermes-agent.nousresearch.com |
Versions read
The latest release at the time each row was checked, where the vendor publishes one. Cursor and Antigravity CLI docs do not pin a version, so those rows follow the current docs.
- Claude Code: 2.1.312, released
- Codex CLI: 0.165.0, released
- Cursor: current docs
- Gemini CLI: 0.66.0, released
- Antigravity CLI: current docs
- GitHub Copilot: 1.0.105 (Copilot CLI), released
- Hermes Agent: 0.22.5, released
Change log
Dated changes to what agents read, newest first.
- · Claude Code: Claude Code 2.1.285 renamed the built-in plugin that reads AGENTS.md to cc-plugin-agents-md@builtin (was agents-md@builtin); both IDs are accepted in settings. Source.
- · Claude Code: Claude Code 2.1.281: AGENTS.md also loads in sessions that could not read it before, such as Amazon Bedrock or with telemetry turned off. Source.
- · Claude Code: Claude Code 2.1.280: /memory and /context list an AGENTS.md that Claude read directly. Source.
- · Claude Code: Claude Code 2.1.277 reads AGENTS.md natively when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above. Change it with Project instructions in /config. Source.
- : Page published. Every cell read against current vendor docs and changelogs on this date.
Related
- One AGENTS.md for every agent: one instruction file with a one-line import for the agents that need it.
- Cursor rules that load: .mdc front matter and a linter.
- Why your agent hooks don't come with you: why one hooks file does not cover every agent.
- Why you shouldn't start a coding agent in Downloads: what an agent picks up from the folder you start it in.