COMPATIBILITY TABLE

Which coding agents read which instruction files, checked against each vendor's own documentation. Last verified 2026-11-13.

Last verified 2026-11-13. Each row links to the vendor page it was checked against.

Zero retention: everything you type stays in this browser. Verify it yourself in DevTools.
Guide

Which Agents Read Which Files?

AgentAGENTS.mdCLAUDE.mdGEMINI.md.github/copilot-instructions.mdOwn format
Claude Code
Anthropic
Yes, with a conditionYes (primary)NoNoCLAUDE.local.md, ~/.claude/CLAUDE.md
OpenAI Codex
OpenAI
Yes (primary)NoNoNoAGENTS.override.md
GitHub Copilot
GitHub
Some surfacesSome surfacesSome surfacesYes (primary).github/instructions/*.instructions.md
Cursor
Anysphere
Yes, root and nestedNoNoNo.cursor/rules/*.mdc
Gemini CLI
Google
If configuredNoYes (primary)No~/.gemini/GEMINI.md
Windsurf
Cognition (docs now under Devin)
Yes, always onNoNoNo.devin/rules/*.md, legacy .windsurf/rules and .windsurfrules
Zed
Zed Industries
Yes, if first matchYes, if first matchYes, if first matchYes, if first match.rules
Cline
Cline
YesNoNoNo.clinerules/, .cline/rules/
Jules
Google
YesNot documentedNot documentedNot documentedNone documented
Aider
Aider
If you load itIf you load itIf you load itIf you load itCONVENTIONS.md (by convention)

"Own format" lists each tool's native or additional files. "Some surfaces" means support depends on where you use the tool; the details below say which.

What Are the Details for Each Agent?

Claude Code

Reads CLAUDE.md from the working directory and the directories above it, plus CLAUDE.local.md and your user file in ~/.claude/. CLAUDE.md can import other files with @path, up to four hops deep. From v2.1.277 it can read AGENTS.md, but by default only when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it; the Project instructions setting (claude-md-and-agents-md) loads both. A CLAUDE.md containing @AGENTS.md works on every version.

Source: code.claude.com/docs/en/memory, checked 2026-11-13.

OpenAI Codex

Reads AGENTS.md (or AGENTS.override.md, which wins in the same directory) from ~/.codex, then from the project root down to the working directory, concatenating them so the closest file comes last. Extra file names can be added as fallbacks. It stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default.

Source: developers.openai.com/codex/guides/agents-md, checked 2026-11-13.

GitHub Copilot

Every Copilot surface that supports custom instructions reads .github/copilot-instructions.md. Agent files (AGENTS.md, CLAUDE.md, GEMINI.md) are read by the Copilot cloud agent, Copilot code review on github.com (which also reads REVIEW.md) and the Copilot CLI. Copilot Chat in VS Code reads AGENTS.md. Copilot Chat on github.com, in Visual Studio, JetBrains, Eclipse and Xcode does not read agent files, which is why the Copilot file should carry the essentials itself.

Source: docs.github.com/en/copilot/reference/custom-instructions-support, checked 2026-11-13.

Cursor

Project rules are .mdc files in .cursor/rules with description, globs and alwaysApply frontmatter; plain .md files in that folder are ignored. AGENTS.md is supported in the project root and in subdirectories, where nested files combine with their parents and the more specific one wins. The single .cursorrules file is documented as legacy.

Source: cursor.com/docs/rules, checked 2026-11-13.

Gemini CLI

Reads GEMINI.md from ~/.gemini and from the project directories, and GEMINI.md can import other files with @file.md. The file name is configurable: set context.fileName in settings.json to a list such as ["AGENTS.md", "GEMINI.md"] to have it read AGENTS.md as well.

Source: geminicli.com/docs/cli/gemini-md/, checked 2026-11-13.

Windsurf

AGENTS.md, AGENTS.local.md and AGENT.md are always-on rules, read at the workspace root and in each directory down to the one being worked on. Finer rules go one per file in .devin/rules/*.md with trigger frontmatter (always_on, model_decision, glob, manual). The legacy .windsurf/rules/*.md, .windsurf/global_rules.md and .windsurfrules files are still imported.

Source: docs.windsurf.com/windsurf/cascade/agents-md, checked 2026-11-13.

Zed

Uses only the first file it finds, in this order: .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md. A leftover .cursorrules therefore hides your AGENTS.md from Zed. A personal ~/.config/zed/AGENTS.md also applies; project files win on conflict.

Source: zed.dev/docs/ai/instructions, checked 2026-11-13.

Cline

Reads rule files in .clinerules/ or .cline/rules/, AGENTS.md, and a cross-tool global ~/.agents/AGENTS.md. It also detects .cursorrules and .windsurfrules.

Source: docs.cline.bot/customization/cline-rules, checked 2026-11-13.

Jules

Listed as AGENTS.md-compatible on agents.md. The Jules documentation site did not render without JavaScript when we checked, so we have not read its own wording; confirm on jules.google before relying on details.

Source: agents.md/, checked 2026-11-13.

Aider

Reads no instruction file automatically. You load one with /read CONVENTIONS.md, aider --read, or a read: entry in .aider.conf.yml. Pointing that at AGENTS.md works the same way.

Source: aider.chat/docs/usage/conventions.html, checked 2026-11-13.

What Does This Mean for Your Repository?

One AGENTS.md reaches most agents directly. Three groups need help:

  • Claude Code prefers CLAUDE.md. A CLAUDE.md containing the line @AGENTS.md imports the shared file on every version.
  • Gemini CLI reads GEMINI.md by default. Either import AGENTS.md from it, or set context.fileName to include AGENTS.md.
  • Copilot Chat on github.com, in Visual Studio, JetBrains, Eclipse and Xcode reads only copilot-instructions.md, so that file needs the essentials inline, not just a pointer.

The generator writes exactly these bridges.

Which Mistakes Does the Table Help You Avoid?

  1. Keeping a .cursorrules after migrating: Zed reads the first file it finds, and .cursorrules comes before AGENTS.md in its list, so your AGENTS.md is silently ignored there.
  2. Adding AGENTS.md next to an existing CLAUDE.md and expecting Claude Code to read both: by default it reads AGENTS.md only when no CLAUDE.md exists.
  3. Assuming a Copilot pointer file is enough: several Copilot chat surfaces never read AGENTS.md.
  4. Letting AGENTS.md grow past 32 KiB: Codex stops reading project instructions at that size by default.

How Is This Table Verified?

Every row was checked on 2026-11-13 by reading the vendor's own documentation page, linked under each agent above, rather than blog posts or forum threads. Where a vendor's page could not be read directly, the row says so instead of guessing. Agent tools change monthly; we re-check this table regularly and update the date with every change. If you spot something out of date, use the feedback buttons below.

  • Primary sources only: vendor documentation.
  • One date for the whole table, updated with each check.
  • Unverified details are labeled, not stated.

Frequently Asked Questions

Which AI coding agents read AGENTS.md?

OpenAI Codex, Cursor, Windsurf, Cline, Jules and Zed read AGENTS.md directly. GitHub Copilot reads it in the cloud agent, code review, the CLI and VS Code chat. Claude Code reads it only when no CLAUDE.md exists, by default. Gemini CLI reads it if configured.

Does Claude Code read AGENTS.md?

Since version 2.1.277 it can, but by default only when there is no CLAUDE.md or CLAUDE.local.md. A CLAUDE.md that contains the line @AGENTS.md imports it on every version and is the reliable approach.

Does GitHub Copilot read AGENTS.md?

Some surfaces do: the Copilot cloud agent, Copilot code review on github.com, the Copilot CLI and Copilot Chat in VS Code. Copilot Chat on github.com, in Visual Studio and in JetBrains reads only copilot-instructions.md.

Does Cursor still read .cursorrules?

Cursor documents .cursorrules as legacy. Current projects should use .cursor/rules/*.mdc files or AGENTS.md, which Cursor reads in the root and in subdirectories.

How often is this table updated?

It is re-checked against vendor documentation regularly and the date at the top changes with each check. Tools change often, so verify against the linked vendor page before relying on a detail.

Was this helpful?