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

Open
#95,589 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:core bug has repro platform:macos
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.md not auto-loaded when no CLAUDE.md exists, 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
  1. A project with a root AGENTS.md (optionally .claude/AGENTS.md), and no CLAUDE.md in the project, in any parent, or in ~/.claude/.
  2. No instructionFiles and no projectInstructions in any settings file.
  3. Start a session, send any message, and look for the agents-md: ... AGENTS.md loaded: ... notice, or inspect that session's transcript for an attachment of "type": "instructions".
  4. 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; no CLAUDE.md anywhere
  • 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.