AI Tool Atlas
Rules & instructions Official

AGENTS.md

Open Markdown format that gives coding agents project instructions, a README for agents read by Codex, Cursor, Gemini CLI, Windsurf and more.

Author
AGENTS.md (Agentic AI Foundation, Linux Foundation)
Works with
Cursor, Gemini CLI, OpenAI Codex, Windsurf
Documented
Oct 2, 2026
Official docs ↗

What AGENTS.md is

AGENTS.md is a plain Markdown file placed in a repository to give coding agents build steps, tests and conventions. It has no required fields. Agents read the nearest file in the directory tree, so nested files serve monorepo subprojects. The site says it is stewarded by the Agentic AI Foundation under the Linux Foundation.

What it does

How AGENTS.md plugs in: which agents run it and what it addsRUNS INYour agentOpenAI CodexCursorGemini CLIWindsurf4 hosts documentedRULES · OFFICIALAGENTS.mdProject instructions the agent re…5 install stepsno extra permissions listedWHAT IT ADDSWhat it doesGives agents a predictable place…Keeps agent-focused detail out of…Supports nested AGENTS.md files;…Works across many agents with one…agent → extension → new capability · from the official repository or docs
Where AGENTS.md runs and what it adds, from its documentation
  • Gives agents a predictable place for setup, test and code-style instructions
  • Keeps agent-focused detail out of the human README
  • Supports nested AGENTS.md files; the closest one to the edited file wins
  • Works across many agents with one file instead of per-tool formats

When to use it

Good fit

  • You use more than one coding agent on the same repo
  • A monorepo needs per-package agent instructions
  • You want agents to run your listed test commands before finishing

Not for

  • Machine-enforced policy: it is guidance text, and explicit user chat prompts override it

How to install AGENTS.md

You need: An agent that reads AGENTS.md

  1. Create an AGENTS.md file at the repository root
  2. Add sections such as project overview, build and test commands, code style, testing and PR instructions
  3. For monorepos add another AGENTS.md inside each package
  4. To migrate: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
  5. Gemini CLI: set context.fileName to AGENTS.md in .gemini/settings.json; Aider: add read: AGENTS.md to .aider.conf.yml
Configuration example (from the official docs)
{
  "context": {
    "fileName": "AGENTS.md"
  }
}

Limitations

  • No required fields or schema; behavior depends on each agent
  • Conflicts resolved by nearest file, chat prompts override everything

Tools it extends

Coding Free plan
No user reviews yet

AI coding IDE, formerly Windsurf, now Devin Desktop: manage local and cloud coding agents inside a full IDE.

Free stops at: Light quota for agent usage, resets daily and weekly, Limited model availability

Listed Not yet reviewed

Verified windsurf.com (opens Devin Desktop (formerly Windsurf) website in a new tab)

Free · paid from $20/mo US · checked Sep 29

CompareAdded Devin Desktop (formerly Windsurf) Details about Devin Desktop (formerly Windsurf)

Frequently asked questions

Are there required fields in AGENTS.md?

No. It is standard Markdown; use any headings you like. source

What happens when AGENTS.md files conflict?

The closest AGENTS.md to the edited file wins, and explicit user chat prompts override everything. source

How do I make Gemini CLI read AGENTS.md?

Set context.fileName to AGENTS.md in .gemini/settings.json. source

Which agents support AGENTS.md?

The site lists Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf and others. source

Related guides

Sources and gaps

Not stated by the maintainers: Repo URL and license not fetched from the page; repo_url is the project's GitHub org repo, unverified; Codex-specific AGENTS.md discovery rules not read; Public source repository (closed source or not verified).

More extensions to look at