Claude Code reads AGENTS.md only when telemetry is on

A developer named Przemek Szypowicz discovered and documented a hidden gate inside Claude Code 2.1.277 that silently prevents AGENTS.md from loading when telemetry is disabled. The source article is rich with technical detail — version numbers, a feature-flag name, canary test methodology, exact environment variables, and a working workaround. The prompt asks for a product_update-style article with a before/after table and copy-paste commands. However, this is a bug report / behavior analysis post rather than a product launch, so I'll structure it appropriately using the exact verbatim headings required, note that there are no version benchmark numbers to put in a before/after table (but I can use the telemetry-on vs. telemetry-off behavior as the table), and include the real copy-paste commands from the source.

Anthropic shipped AGENTS.md support in Claude Code 2.1.277, promising that the tool would read project instructions from that file whenever no CLAUDE.md was present in the same directory. The feature was designed to let developers maintain a single instruction file shared across multiple AI coding agents — Claude Code, Codex, and others — without maintaining duplicates. What Anthropic did not document is that the loader for AGENTS.md is gated behind a remote feature flag called tengu_agents_md_mod, and that flag cannot resolve to true when telemetry or nonessential traffic is disabled.

This piece covers the mechanism behind the gate, exactly which environment variables trigger the silent skip, the workaround available today, and what Anthropic would need to change to make the feature reliable. It is aimed at developers who keep telemetry off by habit or policy, teams running Claude Code through Bedrock, Vertex, or a third-party gateway, and anyone who has noticed their project instructions disappearing without an error message.

What shipped in Claude Code reads AGENTS.md only when

Claude Code 2.1.277 added a built-in plugin called agents-md that looks for AGENTS.md and .claude/AGENTS.md in the current project directory and loads whichever it finds when no CLAUDE.md is present. The plugin appeared in the 2.1.280 bundle with isOnByDefault set to false. Its isAvailable check calls a remote flag resolver, passing tengu_agents_md_mod as the flag name and false as the fallback value. That fallback is the critical detail: if the flag cannot be fetched, the plugin is treated as unavailable rather than falling back to the documented behavior of reading the local file.

The feature was announced as a cross-agent compatibility improvement. Codex already reads a global ~/.codex/AGENTS.md; Claude Code's plugin was supposed to let teams share one file across both tools at the project level. The remote-flag architecture turns that promise conditional: the file is read only when Claude Code can reach Anthropic's flag service and receive a true response.

What improved in Claude Code reads AGENTS.md only when

The gap between the announced behavior and the measured behavior is stark. Przemek Szypowicz confirmed the conditions with a canary test — a directory containing only an AGENTS.md with a unique word inside, queried via claude -p asking for that word without reading files directly.

Setting either variable to 0 does not re-enable the feature: the environment variable documentation notes that any non-empty value activates the block, a detail easy to miss when troubleshooting. There is also no per-repository override through .claude/settings.json.

What you gain from Claude Code reads AGENTS.md only when

Developers who keep telemetry on and run Claude Code directly against Anthropic's API gain a genuine cross-agent instruction file. If AGENTS.md is present and the flag resolves, Claude Code reads it automatically and the model behaves as if a CLAUDE.md with the same content were in the directory. Teams using a shared AGENTS.md for both Codex and Claude Code get consistency without duplication, which is the actual value the feature was designed to deliver.

For everyone else — privacy-conscious developers, enterprise teams on Bedrock or Vertex, and anyone routing through a gateway that blocks nonessential outbound traffic by policy — the net gain is currently zero. The feature is announced, present in the binary, and silently inactive. The practical result is that the model answers without the project instructions and nothing in the session output explains why.

How to get Claude Code reads AGENTS.md only when

The only reliable workaround today is a one-line CLAUDE.md that imports AGENTS.md using Claude Code's @path import syntax, which does not depend on the remote flag at all.

echo '@AGENTS.md' > CLAUDE.md

That file in the project root causes Claude Code to read AGENTS.md through the import mechanism even when CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 is still set. The trade-off is one extra file per repository, which is precisely what AGENTS.md support was meant to eliminate. To keep the session-level override for cases where clearing the environment variables is acceptable from the second session onward:

claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'

For shared agent skills, the agents-md plugin looks for .agents/skills and ~/.agents/skills only inside /import, which copies skills into .claude/skills. A symlink avoids copy drift:

ln -s ../.agents/skills .claude/skills

Updating Claude Code to its latest version first ensures the agents-md plugin is present in the bundle:

claude update

What to watch after Claude Code reads AGENTS.md only when

The filed issue is GitHub issue #95690 on the anthropics/claude-code repository. The most important fix would be changing the fallback for tengu_agents_md_mod from false to the documented behavior — reading a local file needs no network contact, so the flag-unavailable case should not block it. A less complete but still valuable fix would be a startup warning when an AGENTS.md is present in the working directory but the plugin is inactive, giving developers the diagnostic that the canary-word approach currently provides manually.

A secondary gap worth watching is the absence of a global user-level AGENTS.md. Codex resolves ~/.codex/AGENTS.md automatically; Claude Code 2.1.280 has no equivalent path outside the @-import workaround in the user CLAUDE.md. If Anthropic resolves the flag-dependency issue and also adds a home-directory search path, the multi-agent shared-instructions workflow the feature was designed for would actually work without workarounds.