AGENTS.md: the README for coding agents

Updated Oct 26, 2026 · Sources listed at the end

AGENTS.md is a plain Markdown file in your repository that tells AI coding agents how to work on the project: setup commands, how to run tests, code style and conventions. Its site calls it “a README for agents” and says it is used by over 60,000 open-source projects.¹

Why a separate file

README.md is for humans. AGENTS.md holds the extra detail agents need (build steps, tests, conventions) that would clutter a README, in “a clear, predictable place”. The format is deliberately not tied to one vendor.¹

Example

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons

(From the example on agents.md.)¹

Which tools read it

The AGENTS.md site lists, among others, OpenAI Codex, Google Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, JetBrains Junie, Amp, Cursor, Gemini CLI, Kilo Code, GitHub Copilot’s coding agent and Augment Code.¹ Cursor documents AGENTS.md as a simple alternative to .cursor/rules.² Claude Code reads AGENTS.md when there is no CLAUDE.md on the project path.³

Tools mentioned

• OpenAI Codex: free plan, paid from $8/mo
• Jules: free plan, paid from Free
• Aider: free plan, paid from Free
• goose: free plan, paid from Free
• OpenCode: free plan, paid from $10/mo
• Cursor: free plan, paid from $8/mo
• Claude Code: paid from $20/mo

Sources

1. AGENTS.md
2. Cursor docs: Rules
3. Claude Code docs: How Claude remembers your project (CLAUDE.md)