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
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

  1. Create a repository with a root AGENTS.md (project instructions) and no CLAUDE.md in the repo or any parent directory.
  2. No project .claude/settings.json / settings.local.json (nothing excluding memory files).
  3. Start a Claude Code session in that directory (Windows, PowerShell).
  4. 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.md files (cli/AGENTS.md, cmd/AGENTS.md); the issue observed is about the root file at session start.
  • Workaround: adding a root CLAUDE.md containing @AGENTS.md works as expected.

View original on GitHub ↗

3 Comments

marcindulak · 2 days ago

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

Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them.

The request to support AGENTS.md was rejected in https://github.com/anthropics/claude-code/issues/6235#issuecomment-5311479502.

hustcer · 2 days ago

It's a shame that Claude doesn't support AGENTS.md