Claude Code skips AGENTS.md when telemetry is off

Claude Code shipped AGENTS.md support in version 2.1.277, and it does nothing in sessions with telemetry turned off. A developer laid this out in a September 23 post on Szypowi. The loader asks a remote feature flag for permission to run. When Claude Code can’t fetch that flag, the file on your disk is never read, and you get no warning.

The author keeps telemetry off in their shell and noticed that AGENTS.md never loaded in their repos. They found the explanation in a GitHub issue, added their own measurements there, and collected them in the post. The feature is a fallback by design: Claude Code reads AGENTS.md only when there is no CLAUDE.md in the working directory or any parent, and you can change that under “Project instructions” in /config. The release note warned that the feature was “not yet on Bedrock, Vertex or Foundry”. It turns out sessions with telemetry disabled belonged on that list too.

Where the gate sits

The loader is a built-in plugin called agents-md. In the 2.1.280 bundle, its registration sets var W = !1, which is the plugin’s isOnByDefault value, so the plugin is off by default. It defines isAvailable as var B = () => Oa("tengu_agents_md_mod", W);. That line asks a remote flag named tengu_agents_md_mod whether the plugin is available and falls back to false. If the flag can’t be resolved, the plugin is unavailable, even though its own description string still says AGENTS.md is “by default loaded where the project has no CLAUDE.md”.

“Reading a markdown file from the working directory needs no network at all, but here it waits on a server-side switch,” the author wrote.

How it was measured

The test directory was empty except for an AGENTS.md containing one line: The canary word is PERIWINKLE. The author then ran claude -p and asked for the canary word from the project instructions, with orders to answer NONE if there were none and not to read any files. Each setup ran in two sessions. In a new configuration, the first session only fetches the flag and the second one actually uses it. The results:

• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 blocks the feature, as the issue reported.
• DISABLE_TELEMETRY=1 blocks it as well, so both variables had to be cleared.
• Setting either variable to 0 doesn’t lift the block. The environment variable docs say any value counts, which is easy to miss when you’re trying to turn something on.
• Clearing both variables in an env block in the project’s .claude/settings.json has no effect, so you can’t enable the feature for a single repo.
• A session-level override works, but only from the second session on: claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'.

None of these cases prints a warning. The session starts and the model answers without the project instructions. According to the issue, third-party gateways, Bedrock and Vertex have the same problem, because the flag can’t resolve to true there either.

The one-line workaround

CLAUDE.md supports @path imports, and those don’t depend on the flag. So a CLAUDE.md that holds a single line, created with echo '@AGENTS.md' > CLAUDE.md, pulls AGENTS.md in. With that file in place, the canary test returned the word while CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 was still set. The cost is one extra file per repo, “which is what the AGENTS.md support was supposed to remove,” as the author put it.

The post argues that the gate hits the people most likely to want AGENTS.md. Developers who keep one instruction file for several agents tend to watch what each tool sends home, and teams on Bedrock, Vertex or a gateway often turn off nonessential traffic as a matter of policy. “I turned telemetry off on purpose, and I expect that choice to cost me some diagnostics and nothing else,” the author wrote. The author confirmed the cause with the canary and a string search through the binary. Most users won’t do either, they added, and will instead “conclude that the model ignores their instructions”, then spend time tuning prompts for a file that never reached the model. The fix they asked for: if Anthropic wants a staged rollout, a flag that can’t be fetched should fall back to the documented behavior, or at least to a message saying what was skipped and why.

What changed in 2.1.281

Later, a commenter on the original AGENTS.md feature request on GitHub quoted the 2.1.281 changelog: “Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled”. The commenter said that version number comes from Anthropic and not from their own bisect. They also said they had no Bedrock, Vertex or Foundry access to test with.

Their tests on 2.1.282 came out clean. AGENTS.md loaded in 3 of 3 runs with no variables set, and also with each of CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, DISABLE_TELEMETRY=1, DO_NOT_TRACK=1 and DISABLE_GROWTHBOOK=1. A control directory with neither file returned 0 of 3. In the telemetry-off runs, cachedGrowthBookFeatures in ~/.claude.json was empty and had no fetch timestamp, so the file loaded with no flags cached at all.

The same commenter found a first-run problem in older builds. On 2.1.278, a first-run probe reported plugins: [] and 0 of 18 loads, and things only recovered on the second run in the same configuration. They connected this to CI, where every job starts in a fresh container and is always a first run. On 2.1.282, AGENTS.md loaded on 5 of 5 first runs, and agents-md@builtin showed up in the first stream-json event.

They also flagged a settings trap. A top-level key written as "env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1" did not turn telemetry off: the flag cache filled up with 715 entries. The nested {"env": {...}} form brought it to zero. Per the commenter, 2.1.282 adds a startup notice that lists any telemetry variables in a settings file that were ignored.

A global file and shared skills

Two gaps from the post’s wishlist concern 2.1.280 and are separate from the flag. First, the plugin looks for AGENTS.md and .claude/AGENTS.md in project directories only, and there is no user-level file next to the user CLAUDE.md. Codex reads a global ~/.codex/AGENTS.md. Claude Code’s /import can copy that file into the user CLAUDE.md, but the copy doesn’t pick up later edits. So anyone who keeps one set of personal instructions for several agents still needs an @ import in the user CLAUDE.md that points at the shared file.

Skills have the same gap. Codex reads them from .agents/skills in the project and ~/.agents/skills in the home directory. Claude Code 2.1.280 knows those paths only inside /import, which copies the skills into .claude/skills. The author put a canary skill in .agents/skills and Claude Code didn’t list it, while the same skill in .claude/skills in the same repo did show up. A copy drifts from its source, so the author links .claude/skills to ../.agents/skills instead, and Claude Code follows that symlink.