# AGENTS.md

[4 · Read](/category/read/)

| AGENTS.md |
| --- |
| Category | [Read](/category/read/) |
| Governed by | Agentic AI Foundation (AAIF), a Linux Foundation project |
| Status | "An open format... regardless of which coding agent you use"; explicitly not proprietary to any one tool |
| Phase | living |
| Implementation | multi-implementation |
| Adoption | claimed — agents.md (site claims over 60,000 AGENTS.md files across open-source GitHub repositories, via a `path:AGENTS.md NOT is:fork NOT is:archived` code search) |
| Version | current site guidance (living document) (2026-09) |
| Specification | [https://agents.md](https://agents.md) |
| Found at | AGENTS.md |
| Acronym collisions | AGENT.md (legacy pre-merge filename some tools symlink for backward compatibility) |
| Last checked | 2026-09-06 |

[Read](/category/read/) AGENTS.md is an open convention for a markdown file placed at a repository's root (or nested inside subpackages) that gives coding agents the operational context a human-facing README would clutter: build and test commands, code-style rules, security considerations, and PR conventions [[1]](#ref-1). It complements, rather than replaces, README.md: the README stays focused on human contributors while AGENTS.md carries agent-specific detail [[1]](#ref-1).

## Overview
It solves the problem of giving many different coding agents — Codex, Claude Code, Cursor, Copilot, and dozens of others — one predictable, tool-agnostic place to find per-repository instructions, instead of every vendor inventing its own proprietary rules file (.cursorrules, CLAUDE.md, etc., some of which are still separately supported alongside it). It has no required fields or schema: "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide" [[1]](#ref-1). In a monorepo, nested AGENTS.md files are supported and the closest file to the edited path wins, letting each subproject carry tailored instructions; the OpenAI repository itself reportedly has 88 such files [[1]](#ref-1).

It does not enforce anything: whether an agent actually runs the test commands it lists is a matter of each tool's own behavior, and explicit user chat instructions always override the file's contents [[1]](#ref-1). It is not a machine-readable manifest (no capability declarations, no discovery well-known path) — it is read as freeform prose, closer to documentation than to a protocol.

Current state: the format launched in August 2025, originating from OpenAI's Codex team working with Amp, Google's Jules, Cursor, and Factory [[1]](#ref-1)[[2]](#ref-2)[[3]](#ref-3). As of this verification (September 2026) it is stewarded by the Agentic AI Foundation (AAIF), a Linux Foundation project, and is supported by more than two dozen coding tools and agents, including several that also support a proprietary rules file of their own alongside it (Zed, Windsurf, RooCode, Kilo Code, opencode) [[1]](#ref-1). The project's own site claims over 60,000 AGENTS.md files exist across public, non-fork, non-archived GitHub repositories, based on a GitHub code search rather than an independent crawl [[1]](#ref-1).

What is disputed or unknown: the 60,000+ figure is a claim by the format's own stewards, not an independently reproduced count, and no third-party adoption study analogous to the llms.txt Tranco studies was found during this verification. It is also unclear how much of AAIF's governance is substantive versus a naming step shortly after Linux Foundation involvement was announced (2026), since the specification text itself has not visibly changed in structure since the original release.

## Discovery and probe

Fixed filename at a repository's root; agents read the nearest AGENTS.md up the directory tree from the file being edited, so a nested file in a monorepo package takes precedence over the root file · AGENTS.md

```
GET {origin}/AGENTS.md (repository-root fetch, e.g. raw.githubusercontent.com///HEAD/AGENTS.md)
parse:     200 response containing markdown text; presence alone is the signal since there are no required fields or schema
on absent: No repository-level agent instructions are declared; an agent falls back to inferring conventions from the codebase or README
```

Live check run by [the MCP probe](/mcp/server-card): GET /AGENTS.md. AGENTS.md has no required fields; a non-empty document at the site root is the signal.

```
{
 "path": "/AGENTS.md",
 "expect": {
  "text_match": "\\S"
 },
 "note": "AGENTS.md has no required fields; a non-empty document at the site root is the signal."
}
```

## History
- 2026-09-05 — seeded from Exa Agent research run
- 2026-09-06 — verified against agents.md, OpenAI's harness-engineering post, and a secondary account of the August 2025 launch

## Instances

- [Zed](https://zed.dev/docs/ai/instructions) · Recorded 2026-09-06 · site
- [Windsurf (Cognition)](https://windsurf.com/) · Recorded 2026-09-06 · site
- [Warp](https://docs.warp.dev/knowledge-and-collaboration/rules#project-scoped-rules-1) · Recorded 2026-09-06 · site
- [VS Code](https://code.visualstudio.com/docs/editor/artificial-intelligence) · Recorded 2026-09-06 · site
- [temporalio/sdk-java](https://github.com/temporalio/sdk-java/blob/-/AGENTS.md) · Recorded 2026-09-06 · site
- [RooCode](https://roocode.com/) · Recorded 2026-09-06 · site
- [opencode](https://opencode.ai/docs/rules/) · Recorded 2026-09-06 · site
- [openai/codex](https://github.com/openai/codex/blob/-/AGENTS.md) · Recorded 2026-09-06 · site
- [OpenAI Codex](https://openai.com/codex/) · Recorded 2026-09-06 · site
- [Kilo Code](https://kilocode.ai/) · Recorded 2026-09-06 · site
- [JetBrains Junie](https://jetbrains.com/junie) · Recorded 2026-09-06 · site
- [goose (Block)](https://github.com/block/goose) · Recorded 2026-09-06 · site
- [Google Jules](https://jules.google/) · Recorded 2026-09-06 · site
- [GitHub Copilot coding agent](https://gh.io/coding-agent-docs) · Recorded 2026-09-06 · site
- [Factory](https://factory.ai/) · Recorded 2026-09-06 · site
- [Devin (Cognition)](https://devin.ai/) · Recorded 2026-09-06 · site
- [Cursor](https://cursor.com/) · Recorded 2026-09-06 · site
- [Augment Code](https://docs.augmentcode.com/cli/overview) · Recorded 2026-09-06 · site
- [apache/airflow](https://github.com/apache/airflow/blob/-/AGENTS.md) · Recorded 2026-09-06 · site
- [Amp](https://ampcode.com/) · Recorded 2026-09-06 · site
- [Aider](https://aider.chat/docs/usage/conventions.html#always-load-conventions) · Recorded 2026-09-06 · site

Every instance with its source is listed on the [instances page](/instances/).

## See also

- Not to be confused with: AGENT.md (legacy pre-merge filename some tools symlink for backward compatibility)

## References

- Full AGENTS.md rationale, format (no required fields, closest-file-wins precedence), FAQ, migration guidance, and current list of 25+ adopting tools (Codex, Amp, Jules, Cursor, Factory, Devin, Aider, goose, Ona, VS Code, Zed, Windsurf, GitHub Copilot coding agent, Warp, Junie, RooCode, Phoenix, Augment Code, Kilo Code, opencode, and more). "AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation". — [https://agents.md](https://agents.md) (2026-09) VERIFIED
- AGENTS.md was released by OpenAI in August 2025, emerging from collaboration across OpenAI Codex, Amp, Jules (Google), Cursor, and Factory — [https://blog.stackademic.com/agents-md-the-readme-your-ai-coding-agent-actually-reads-e634b7e2de34](https://blog.stackademic.com/agents-md-the-readme-your-ai-coding-agent-actually-reads-e634b7e2de34) (2026) REPORTED
- OpenAI's own harness-engineering writeup for the Codex repository references "the initial AGENTS.md file that directs agents how to work in" the repo, corroborating OpenAI's originating role — [https://openai.com/index/harness-engineering/](https://openai.com/index/harness-engineering/) (2026) REPORTED

[JSON](/data/protocols/agents-md.json) · [Markdown](/protocols/agents-md/index.md)