anthropics / anthropics/claude-code
[BUG] AGENTS.md loading is intermittent on 2.1.278: same directory and flag state, some sessions load the files and some silently do not
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 147k
- Forks
- 24k
- PR merge metrics
- PR metrics pending
Description
Preflight Checklist
- I have searched existing issues. Closest: #89825 (root
AGENTS.mdnot auto-loaded when noCLAUDE.mdexists, 2.1.246 / Windows, filed before AGENTS.md support shipped in 2.1.277). That report describes a consistent failure; this one is about the same feature after it shipped, failing intermittently: on one machine, in one directory, some sessions load the files and some do not. - This is a single bug report
- I am using the latest version of Claude Code (2.1.278)
What's Wrong?
With AGENTS.md present and no CLAUDE.md anywhere, whether the instruction files are loaded varies from session to session. Same binary (2.1.278), same directory, same files, same settings, same feature flag state, sessions minutes apart.
Eight sessions in the same directory within 45 minutes:
| started | launched | instructions recorded in transcript |
|---|---|---|
| 04:17 | interactive | none |
| 04:22 | interactive | none |
| 04:27 | claude -p |
AGENTS.md x 3 |
| 04:38 | claude -p |
AGENTS.md x 3 |
| 04:38 | interactive (pty) | AGENTS.md x 3 |
| 04:40 | interactive (pty) | AGENTS.md x 3 |
| 04:46 | interactive | loaded (startup notice shown) |
| 05:03 | interactive | none |
"Recorded in transcript" means an attachment of "type": "instructions" in ~/.claude/projects/<slug>/<session-id>.jsonl, which is where a loaded CLAUDE.md was recorded on this machine before the files were renamed.
The sessions that load print a notice at startup:
agents-md: no CLAUDE.md found; AGENTS.md loaded: <home>/.claude/AGENTS.md, <project>/AGENTS.md, <project>/.claude/AGENTS.md
The sessions that do not load print nothing. There is no error and no warning. The session looks exactly like a project with no instruction files, and the model runs without any of the project's rules until someone notices the behavior is off.
This is not the feature being inactive for the account. cachedGrowthBookFeatures.tengu_agents_md_mod in ~/.claude.json reads true, and cachedGrowthBookFeaturesAt shows it was refreshed at the startup of a session that then failed to load.
What Should Happen?
Loading is deterministic: a session either loads the AGENTS.md files it finds, every time, or says that it found them and skipped them.
Steps to Reproduce
- A project with a root
AGENTS.md(optionally.claude/AGENTS.md), and noCLAUDE.mdin the project, in any parent, or in~/.claude/. - No
instructionFilesand noprojectInstructionsin any settings file. - Start a session, send any message, and look for the
agents-md: ... AGENTS.md loaded: ...notice, or inspect that session's transcript for anattachmentof"type": "instructions". - Repeat several times. Some sessions load the files and some do not.
Note for step 3: the attachment is written together with the first user message, so a session where nothing has been sent yet shows no attachment whether or not it loaded. Send one message before checking.
Environment
- Claude Code 2.1.278 (native install), macOS 26, zsh
- Default
instructionFiles(not set in any settings file) - Files present:
~/.claude/AGENTS.md,<project>/AGENTS.md,<project>/.claude/AGENTS.md; noCLAUDE.mdanywhere tengu_agents_md_mod: true
Additional Note
In the sessions that do load, the user-level ~/.claude/AGENTS.md is recorded with "type": "Project", while the equivalent ~/.claude/CLAUDE.md was recorded as "type": "User". Minor, but it looks like the fallback path loses the user/project distinction.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce repeated sessions with the listed AGENTS.md layout, then compare the startup notice with instruction attachments in ~/.claude/projects//.jsonl and the feature state in ~/.claude.json. Done means AGENTS.md loading is deterministic, or a session explicitly reports that discovered files were skipped.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- cli
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100