Root AGENTS.md not auto-loaded at session start when no CLAUDE.md exists
Status Open
Reported on v2.1.246
Maintainer reply None cached
Workaround ✓ Mentioned in description ↑
Activity 3 comments · opened Aug 26, 2026
Bug description
A root AGENTS.md is not loaded into context at session start, even though the repository contains no CLAUDE.md anywhere and no claudeMd/claudeMdExcludes settings. Per the documented fallback behavior, AGENTS.md should be read in place of CLAUDE.md when the latter is absent.
The model confirmed no project-instruction content was injected at startup — the AGENTS.md contents only entered context after being explicitly @-mentioned by the user.
Environment
- Claude Code version: 2.1.246
- OS: Windows 11 Enterprise (10.0.26200)
- Shell: PowerShell
- Model: Fable 5
Steps to reproduce
- Create a repository with a root
AGENTS.md(project instructions) and noCLAUDE.mdin the repo or any parent directory. - No project
.claude/settings.json/settings.local.json(nothing excluding memory files). - Start a Claude Code session in that directory (Windows, PowerShell).
- Ask Claude what project instructions it has in context.
Expected behavior
Root AGENTS.md is loaded at session start, exactly as a root CLAUDE.md would be (documented CLAUDE.md-fallback behavior).
Actual behavior
No memory/system-reminder injection of AGENTS.md content occurs. /context shows no project instructions loaded. The file is only read when explicitly @-mentioned.
Additional notes
- The repository also has nested
AGENTS.mdfiles (cli/AGENTS.md,cmd/AGENTS.md); the issue observed is about the root file at session start. - Workaround: adding a root
CLAUDE.mdcontaining@AGENTS.mdworks as expected.
3 Comments
See #77136 and Three Writers, One Order -- what the parallel loops prove about our own consensus
I'm not sure whether one can find any official documentation that claims reading AGENTS.md directly is supported.
AGENTS.md is explictly unsupported, see https://code.claude.com/docs/en/memory#agents-md
The request to support AGENTS.md was rejected in https://github.com/anthropics/claude-code/issues/6235#issuecomment-5311479502.
It's a shame that Claude doesn't support AGENTS.md