Claude Code Adds AGENTS.md Support After 13 Months and 5,200 Votes: Mods Are the Real Story

Anthropic shipped Claude Code version 2.1.277 on September 18, resolving the most-upvoted feature request in the tool's history: native support for AGENTS.md, the cross-tool instruction format used by OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Devin, and more than 60,000 open-source projects. The fix took 13 months and accumulated over 5,200 GitHub votes before Anthropic acted. But the AGENTS.md change is not the most consequential part of the release. Beneath it, Anthropic simultaneously shipped the first public demonstration of Claude Code mods — a TypeScript middleware layer that lets developers intercept and reshape how the tool loads context, processes tool output, and renders its interface.

A 13-Month Standoff Over a File That Every Other Coding Agent Already Read

Both AGENTS.md and CLAUDE.md are Markdown files that sit in a repository root and serve as persistent instruction documents for AI coding agents. Each session, the agent reads the file before doing anything else — build commands, testing conventions, directory layout, style requirements, and any other project-specific rules. The difference between the two formats has never been technical content. It has been which tools read which file.

CLAUDE.md is Anthropic's proprietary format, read exclusively by Claude Code. AGENTS.md was released by OpenAI alongside Codex in August 2025 as a tool-agnostic alternative. By December 2025, when OpenAI and Anthropic jointly contributed the format to the Linux Foundation's new Agentic AI Foundation (AAIF), more than 60,000 open-source repositories had adopted it. Cursor, Copilot, Gemini CLI, Devin, Amp, Jules, and VS Code all read AGENTS.md natively. Claude Code did not.

Teams running Claude Code alongside any other major coding agent faced a sustained maintenance tax: keep two near-identical instruction files in sync, update both whenever project conventions changed, and rely on workarounds that Anthropic itself documented — symlink CLAUDE.md to AGENTS.md on POSIX systems, or use an @-import line. A company was shipping workarounds for its own product limitation while GitHub issue #6235 climbed past 5,200 votes with no official response. By August 2026, commentary summarizing Anthropic's position was circulating under the headline "Anthropic Said No to the Most-Requested Feature in Claude Code."

Read more: Claude Code's AI-drafted failure reports signal a shift in agentic quality feedback

Four Instruction Modes Replace the Binary CLAUDE.md / Nothing Choice

Version 2.1.277 does not simply add AGENTS.md as a fixed parallel read. Instead, it introduces four configurable instruction modes accessible through "Project instructions" in the /config menu.

The default mode — claude-md-or-agents-md — reads CLAUDE.md when present and falls back to AGENTS.md when no CLAUDE.md exists. A second mode, claude-md-and-agents-md, loads both files simultaneously. A third mode restores previous behavior, reading only CLAUDE.md. A fourth mode, intended for enterprise deployments, loads only centrally managed organization instructions. The fallback behavior means a repository already configured for Codex, Cursor, or Copilot works in Claude Code without any additional setup. The dual-load mode addresses teams that want AGENTS.md for cross-tool compatibility while keeping Claude-specific instructions in a separate file.

Anthropic's documentation also notes that a repository's own .claude/settings.json cannot set the mode options — only user settings, the --settings flag, or managed settings can do so. That design prevents code checked into a project from controlling an individual's or organization's instruction-loading policy.

How the Mods System Works: TypeScript Middleware Inside Claude Code's Pipeline

Claude Code engineer Thariq Shihipar announced that the AGENTS.md implementation was built using Claude Code mods — Anthropic's upcoming mechanism for customizing the tool's harness. The agents-md loader is the first built-in mod, with source code and documentation published in the official anthropics/claude-code repository.

The harness is the software layer that wraps the model: it assembles context from instruction files, skills, and conversation history; calls tools; manages the session loop; enforces permissions; and drives the terminal interface. Until now, that layer was entirely Anthropic's code. Skills injected instructions into context. MCP connections added external tools. Neither mechanism let developers alter how context was assembled or how tool results were processed before the model saw them. Mods change that.

According to Anthropic's mods documentation, each mod exports a register(on, options) function whose handlers receive the engine interface, the current event, and a continuation through the remaining handler chain — a design that mirrors Express or Koa middleware, the same composition model used in Node.js web servers, now applied to an AI coding tool's runtime pipeline. The agents-md mod specifically hooks into three events: session.start, prompt.context, and tool.call on Read operations, inserting AGENTS.md files into the same project-instruction framing that Claude Code uses for CLAUDE.md.

The implications are concrete. A mod can intercept tool output before the model reads it, filter sensitive data out of shell results, maintain session state, or open a UI pane beside the transcript. Mods nest: the first registered mod wraps all subsequent ones, so organization administrators can prepend security-enforcing mods that constrain what user-installed mods can invoke. Four built-in mods ship in the repository: the AGENTS.md loader, a diff panel showing uncommitted changes beside the transcript, a telemetry module for plugin analytics, and an organization security mod for managed enterprise deployments. Custom mods require enabling an experimental function hooks flag and are not yet available on Bedrock, Vertex, or Foundry deployments.

Read more: Anthropic adds first-party plugin evals to Claude Code with six graders and a CI gate

The Competitive Shift and What Comes Next

Both Anthropic and OpenAI are platinum members of the Agentic AI Foundation and sit alongside each other on the same standards body — while Claude Code spent 13 months as the only major coding agent that did not recognize the cross-vendor format both companies had contributed to that foundation. The resolution was architectural rather than political: Anthropic built the mods system first, then implemented AGENTS.md support as a mod. That sequencing matters. Future instruction-format extensions — additional cross-tool conventions, organization-specific context schemas, or alternative project structures — can follow the same path without requiring Anthropic to ship a dedicated release for each.

For teams currently using Claude Code, the immediate change is concrete: a repository with an AGENTS.md and no CLAUDE.md now works without modification. For developers building tooling on top of Claude Code, the mods architecture is worth studying now through the agents-md mod source, which is the most complete available documentation of how hooks compose with the engine interface.

The developer community's reaction to the announcement was broadly positive. OpenAI's Thibault Sottiaux, who leads core product work on Codex, welcomed the move publicly. Whether the mods system that made AGENTS.md support possible also draws tool builders toward a shared Claude Code extension ecosystem is the more consequential question the release opens.