Claude Code skips AGENTS.md when telemetry is off

What broke, and who it hit

Claude Code's new AGENTS.md support does not run when telemetry is off, and it gives no warning. Przemek Szypowicz's write-up shows that the loader sits behind a remote feature flag. Setting DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC stops Claude Code fetching flags, so the loader never switches on and the agent never sees your project instructions. The post reached the Hacker News front page on September 23 with 393 points and 221 comments in about six hours.

This matters because of who it hits: people who chose privacy, and people who never made a choice at all. That means teams on Bedrock or Vertex, anyone behind a third-party gateway, and anyone with DO_NOT_TRACK in a shell profile. Their agent ran without the project's instructions and said nothing. The Claude Code engineer who built the feature says a fix is coming in 2.1.281, but when this was written it had not reached the version most people install. So this piece shows how to check your setup and how to make your instructions load on any version.

The feature itself is new. The 2.1.277 changelog entry says Claude Code reads AGENTS.md instead of CLAUDE.md "in a project with no CLAUDE.md". The same entry says the feature is "not yet on Bedrock, Vertex or Foundry". According to the npm registry, 2.1.277 was published on September 18.

How the gate works

Szypowicz went through the 2.1.280 bundle. AGENTS.md loading is a built-in plugin called agents-md, and its isOnByDefault is set to false. Whether it is available depends on a remote flag, tengu_agents_md_mod. If Claude Code can't fetch that flag, the plugin stays off.

His test is easy to copy. Put a canary word in AGENTS.md and ask claude -p for it:

echo 'The canary word is PERIWINKLE.' > AGENTS.md
claude -p "What is the canary word? Answer with one word."

If the agent answers PERIWINKLE, the file loaded. If it doesn't know, the file never reached the context.

Here is what he found:

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 and DISABLE_TELEMETRY=1 each block loading.
"Setting either variable to 0 does not help." Having the variable set at all seems to be enough.
An env block in the project's .claude/settings.json that clears both variables "has no effect".
None of these cases prints a warning.

His workaround is a CLAUDE.md that imports the file with @AGENTS.md, because @path imports do not depend on the flag. His central claim is one worth pinning above any feature-flag system: "A privacy setting should never quietly switch off unrelated local behavior."

GitHub issue #95690 was opened on September 20 under the title "Claude Code's AGENTS.md Support: A Local Feature Locked Behind a Remote Switch". It says third-party gateway, Bedrock and Vertex users are affected too. It asks Anthropic to remove server-side gating from what is purely a local file operation.

The Anthropic engineer mpoteat replied in the HN thread:

Sorry folks, this is a rollout artifact, we needed a way to turn this off remotely via feature flags if it broke something, and with telemetry off you don't get those. It's already been fixed as part of v2.1.281 releasing today.

Later in the same comment he wrote: "this was a fully human error on my part - I should've found a better way to launch with a kill-switch."

In fairness, the limitation was written down from the start. Anthropic's memory docs say that "In some sessions, such as those on Amazon Bedrock or with telemetry disabled, Claude can't read AGENTS.md". They also say AGENTS.md is skipped in the first session after an install or upgrade. For those cases they recommend importing @AGENTS.md from a CLAUDE.md. But a line in the docs is not a runtime warning, and few people reread the memory page after each upgrade.

Telemetry off turns off more than AGENTS.md

The bug is narrow, but the design behind it is not. Anthropic's environment variable docs say flag fetching is skipped in three kinds of session:

any session with DISABLE_GROWTHBOOK, DISABLE_TELEMETRY, DO_NOT_TRACK or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set
any session on a third-party provider such as Bedrock, Google Cloud's Agent Platform or Microsoft Foundry
any Claude apps gateway session

With fetching off, AGENTS.md is one of more than a dozen features that become unavailable. Others on the list include default auto mode, Remote Control, claude import, the advisor tool, synced skills and plugins, and filtering out MCP tools whose schema the API would reject. That last one is a guard rather than a convenience, so losing it means losing a safety net, not just a feature.

"Telemetry off" in Claude Code means more than "send less data". It also means a smaller product, and nothing on screen tells you so. Many developers set DO_NOT_TRACK once, across all their tools, and expect it to limit what leaves the machine. Teams usually pick Bedrock or Vertex for billing, procurement or data-handling reasons. Neither group agreed to give up features in exchange.

The kill-switch reasoning itself holds up. A new loader that changes what goes into every session's context is exactly the kind of thing you want to be able to turn off remotely. The mistake was the default for when the flag can't be fetched. There are two defensible options: fall back to the documented behaviour, or show a warning. A silent no-op is not one of them. The loader's own README in the claude-code repo lists the telemetry events it emits (agents_md_mode, agents_md_load, agents_md_nested) and describes them as "Counts and closed choices only; no path and no file text." Keeping the feature working for telemetry-off users would not have required collecting anything more from them.

The pattern could spread. mpoteat said AGENTS.md support was built on "Mods", an upcoming extensibility system based on "function hooks". Issue #91870, opened on September 3, describes a mod as "just a plugin that uses function hooks" with early access through CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1. It says community response "likely dictates whether this ships or not." If more features arrive as mods that start switched off and wait for a remote flag, this failure will come back unless the default for an unreachable flag changes. Say so in the issue tracker while the design is still open.

"Fixed in 2.1.281" is still a promise

mpoteat said the fix was part of "v2.1.281 releasing today". Here is what the public record showed when this was written:

The npm registry lists 2.1.281, published on September 23 at 17:01 UTC, but only under the next dist-tag. latest still points to 2.1.280 (published September 22) and stable to 2.1.267. That explains why one HN commenter's claude update reported 2.1.280 as up to date.
The changelog's newest entry is 2.1.280. There is no 2.1.281 entry.
Issue #95690 is still open.
The memory docs still describe the gate.

None of this means the fix isn't real. It means that, for now, the only evidence for it is one engineer's comment. Its scope is also unclear. The 2.1.277 entry said AGENTS.md was "not yet on Bedrock, Vertex or Foundry", and nothing published so far says whether 2.1.281 changes that. Treat the fix as unconfirmed until your own canary test says otherwise.

A five-minute audit

1. See what is set. Check your shell, your CI runners and your dev containers, not only your laptop:

env | grep -E 'DISABLE_TELEMETRY|DO_NOT_TRACK|DISABLE_GROWTHBOOK|CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC'

If any of these variables is present, assume flag fetching is off. Szypowicz found that setting the two he tested to 0 does not help. Flag fetching is also off if you run on Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, or through a Claude apps gateway. Don't drop your privacy settings just to get AGENTS.md back. Step 4 works without touching them.

2. Run the canary test in your real environment. Use a scratch directory with no CLAUDE.md and the commands from the section above. Run it twice. The docs say AGENTS.md is skipped in the first session after an install or upgrade, so one miss right after updating proves nothing.

3. Look at the context. In an interactive session, /context shows what is loaded, including memory files. If AGENTS.md isn't listed, the agent isn't reading it.

4. Add the import. This is the fix that doesn't depend on the flag, the version or the provider. If the project has no CLAUDE.md yet, create one that holds only the import:

echo '@AGENTS.md' > CLAUDE.md

If a CLAUDE.md already exists, append the line instead of overwriting the file:

echo '@AGENTS.md' >> CLAUDE.md

The second case matters more than it looks. With the default setting, Claude Code reads AGENTS.md only in a project that has no CLAUDE.md. If your repo already has one, AGENTS.md was never being read, flag or no flag. Commit the file so everyone on the team gets the same behaviour.

The Project instructions setting (instructionFiles) takes four values: claude-md-or-agents-md (the default), claude-md-and-agents-md, claude-md and managed-only. Claude Code ignores it in project and local settings files, so you can't pin it per repo. The import remains the option that doesn't rely on the flagged loader.

5. Check the rest of the list. Go through the environment variable docs' list of flag-dependent features and decide which losses matter to you. If you run many MCP servers, the schema filtering is the one to think about.

6. Verify upgrades instead of trusting them.

npm view @anthropic-ai/claude-code dist-tags
claude --version

The fix is real for your setup once a 2.1.281-or-later release is on latest, has a changelog entry, and passes your canary test with your usual privacy settings. Keep the import even then. It's one line, and it keeps working whatever the next flag does.

If you ship feature flags in your own tools, take the broader lesson too. For every flagged feature, decide explicitly what happens when the flag service can't be reached. Then make that path either the documented behaviour or a message the user can see.