AGENTS.md

AGENTS.md is a simple, open Markdown-based format that gives AI coding agents a dedicated, predictable place to receive project context and instructions. It emerged from collaborative efforts across the AI software development ecosystem—including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory—and is now stewarded by the Agentic AI Foundation under the Linux Foundation. The project is open source under the MIT License and hosted on GitHub, where it has accumulated over 21,000 stars.

What It Is

AGENTS.md is a convention, not a proprietary tool: a file you place at the root of your repository (or inside subpackages) that AI coding agents read to understand how to work on your project. Think of it as a README for agents—separate from the human-facing README so that agent-specific instructions (build steps, test commands, code style guidelines, security considerations) don't clutter documentation meant for human contributors. The format is plain Markdown with no required fields or schema; agents simply parse the text you provide.

How It Works

The workflow is straightforward:

• Create an AGENTS.md file at the repository root. Most supported coding agents can scaffold one for you on request.
• Add sections covering what matters: project overview, build and test commands, code style guidelines, testing instructions, security considerations, PR conventions, and deployment steps.
• Use nested files in monorepos: place an AGENTS.md inside each package directory. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence. The project notes that the main OpenAI repository has 88 AGENTS.md files as an example.
• Override behavior: explicit user chat prompts override file instructions; the closest file to the edited file wins when instructions conflict.

Ecosystem Compatibility

The project's website lists a broad and growing set of AI coding agents and tools that support the format, including Semgrep, Zed, Warp, GitHub Copilot's coding agent, JetBrains Junie, Goose, Windsurf (from Cognition), Gemini CLI (Google), OpenAI Codex, opencode, Aider, Augment Code, Jules (Google), VS Code, RooCode, UiPath Autopilot, Phoenix, Kilo Code, Amp, Cursor, Devin (Cognition), and Factory. Configuration for specific tools like Aider (via .aider.conf.yml) and Gemini CLI (via .gemini/settings.json) is documented on the project site.

Adoption Signal

The GitHub repository reports over 21,500 stars and more than 1,500 forks as of the data available. The project's examples page links to real-world AGENTS.md files in repositories such as openai/codex, apache/airflow, and temporalio/sdk-java, and notes that over 60,000 examples are searchable on GitHub. The format is positioned as a community standard rather than a vendor-specific solution.

Current Status

The repository was created in August 2025 and last pushed to in March 2026, with ongoing open issues indicating active community engagement. Governance has been formalized under the Agentic AI Foundation (part of the Linux Foundation), signaling a commitment to maintaining the format as a neutral, open standard for the broader developer community.