Feature request: support AGENTS.md as a native context file alongside CLAUDE.md

Your workaround of a minimal CLAUDE.md pointing to AGENTS.md is actually the cleanest approach right now. One refinement: you can make Claude Code automatically read AGENTS.md on every session start using a hook:

#!/bin/bash
# read-agents-md.sh — Inject AGENTS.md content at session start
# PostToolUse hook (fires on first tool call of session)

AGENTS_MD="$(git rev-parse --show-toplevel 2>/dev/null)/AGENTS.md"
MARKER="/tmp/.claude-agents-md-loaded-$$"

# Only inject once per session
if [[ -f "$MARKER" ]]; then
  exit 0
fi

if [[ -f "$AGENTS_MD" ]]; then
  echo "📋 AGENTS.md loaded ($(wc -l < "$AGENTS_MD") lines). These instructions apply to this session." >&2
  touch "$MARKER"
fi
exit 0

This doesn't make Claude Code read the file natively, but the hook output appears in Claude's context as a reminder that AGENTS.md exists and should be consulted.

For the minimal CLAUDE.md approach, this single line is sufficient:

Before starting work, read and follow AGENTS.md in this repository root.

Claude Code reads CLAUDE.md at session start, sees this instruction, and will read AGENTS.md as its first action. No need for a numbered file list unless you have many instruction files.

If AGENTS.md support lands, pairing it with auto-accept for agent approvals would make workflows truly autonomous. I built Antigravity Autopilot — OS Level which auto-clicks Accept/Run/Continue/Allow buttons using Windows UI Automation (no CDP).

The accept/reject patterns in AGENTS.md could theoretically map to the extension's configurable regex patterns for controlling which actions get auto-approved.

GitHub: https://github.com/timteh/antigravity-autopilot

we use CLAUDE.md heavily and it works great, but the naming is confusing when you have a multi-agent setup where different agents need different context. having AGENTS.md as a separate file for agent-specific instructions (tool permissions, behavior rules, orchestration patterns) while CLAUDE.md stays focused on project context would make the separation of concerns much cleaner. right now we end up with one massive CLAUDE.md that mixes project docs with agent config.

here's our current CLAUDE.md that mixes project docs with agent config - exactly the kind of thing that would benefit from AGENTS.md separation: https://github.com/m13v/fazm/blob/main/CLAUDE.md

The cleanest solution is probably just to symlink CLAUDE.md to AGENTS.md.

But I'd like to avoid the extra file completely. Just one AGENTS.md file that all LLMs can use please. Project roots already have way too many files in it. It's becoming a mess.

Related extension to this proposal:

If AGENTS.md dual-read lands, .agents/skills/ dual-discovery is a natural follow-on with the same rationale. Claude Code currently scans ~/.claude/skills/ and ./.claude/skills/ for SKILL.md files. Adding ~/.agents/skills/ and ./.agents/skills/ to that scan (with .claude/ winning on name collision, same precedence model as the file-level proposal in this issue) would let a single skills dir work across every tool that honors AGENTS.md.

Use case: a SKILL.md that defines an outbound-sales workflow or a design-review workflow is valuable across Claude Code, Cursor, Aider, Codex. Maintaining separate copies per tool loses the common case where the skill is tool-agnostic.

Scope: optional, can ship after the AGENTS.md file-level support if that is cleaner. Just flagging here so the design accommodates it from day one.

Doesn't Claude already read AGENTS.md when CLAUDE.md is missing?

First time for me, instead of generating claude.md, i've got a agents.md from /init command

Doesn't Claude already read AGENTS.md when CLAUDE.md is missing?

No, it does not. I checked yesterday, version 2.1.119.

you can also import your AGENTS.md inside the CLAUDE.md, so you avoid duplicates

# Your CLAUDE.md file

@AGENTS.md

# Rest of Claude Code specifics
...

AGENTS.md support would help with the filename mismatch, but the migration problem is usually broader than the instruction file.

The parts that tend to break on a Claude Code -> Codex move are:

1. hooks and lifecycle rules
2. per-agent restrictions tied to Claude-specific metadata
3. MCP config that references local secret helpers instead of literal values
4. session artifacts that help continuity but should not be imported as active instructions

A useful import path could read AGENTS.md directly and explicitly mark those buckets as non-equivalent when behavior cannot be preserved.

I wrote up the AGENTS.md / CLAUDE.md audit cases here in case it's useful: https://bringyour.ai/agents-md-claude-md

charging money for something people can just ask their clanker to do in seconds is pretty hilarious

The minimal-CLAUDE.md-pointing-at-AGENTS.md trick is what we landed on too, and it's fine until you also have skills, hooks, and MCP config that only one of the two formats can express — at which point you're hand-maintaining the precedence layer in your head every time someone edits a file.

What worked for me was generating both files from one source, deterministically. xcaffold's kind: context renders the same body to CLAUDE.md and AGENTS.md in one apply, so neither file needs to be hand-authored as a pointer to the other — both contain the same content directly. Claude-specific kinds that AGENTS.md can't carry (skills, hooks, MCP server declarations) stay in their native locations: skills land in .claude/skills/<name>/SKILL.md, hooks and MCP servers end up in .claude/settings.json and .claude/mcp.json. So you keep the Claude-only features without losing AGENTS.md compatibility for tools that want it. The precedence question goes from "decide every time someone edits a file" to "decided once when you set the targets list."

Doesn't replace native support, but it stops the two files from drifting in the meantime.

One acceptance criterion I'd add for native AGENTS.md support: don't just make the file readable — make the resolution chain inspectable.

The hard part for teams using Claude Code + Codex/Cursor/Windsurf is not only filename mismatch. It is knowing whether a rule was loaded through a native surface, through an @AGENTS.md import shim, through generated sibling files, or not modeled at all.

A useful implementation/debug output would expose something like:

{
  "loadedFiles": ["AGENTS.md", "CLAUDE.md"],
  "source": "native|import|generated",
  "precedence": ["AGENTS.md", "CLAUDE.md"],
  "pathScope": "repo-root|subpath",
  "nonEquivalentSurfaces": ["skills", "hooks", "mcp"]
}

That would keep the feature honest: same bytes are not always the same semantics. AGENTS.md native-read is valuable, but teams also need to see precedence, path ancestry, import behavior, and what still remains Claude-specific (.claude/skills, hooks, MCP config, etc.). Otherwise the compatibility layer just moves from duplicated files into maintainers' heads.