Claude Code loads AGENTS.md only when telemetry is enabled

Claude Code 2.1.277 shipped support for AGENTS.md, so a project without a CLAUDE.md should fall back to the alternative instruction file. A follow-up investigation published on blog.szypowi.cz shows that this support quietly depends on telemetry and other nonessential network traffic being enabled.

The loader waits on a remote flag

The AGENTS.md loader ships as a built-in plugin called agents-md. In the 2.1.280 bundle its registration sets isOnByDefault to false and resolves availability through a remote feature flag, tengu_agents_md_mod, with false as the fallback. When the flag cannot be fetched, the plugin stays unavailable and the local file is never read — even though reading a markdown file from the working directory needs no network at all. The author traced the cause to GitHub issue #95690 and added measurements of his own.

Canary tests with telemetry off

The test was minimal: an empty directory holding only an AGENTS.md with a canary word, plus a prompt asking the CLI for that word and telling it not to read files. Each setup ran twice, because the first session only fetches the flag.

With CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 or DISABLE_TELEMETRY=1 set, the file never loaded; both variables had to be cleared. Setting either to 0 does not help, since any value counts. An env block in the project's .claude/settings.json had no effect, so the feature cannot be turned on for a single repository. A session-level override passed with --settings does work, from the second session on. No warning is printed in any of these cases. Third-party gateways, Bedrock and Vertex hit the same wall, because the flag cannot resolve to true there either.

The workaround

CLAUDE.md supports @path imports, and those are not gated. A one-line CLAUDE.md next to the AGENTS.md loads it with telemetry disabled — the same canary test returns the word with the block still in place. The cost is one extra file per repository, the very overhead the AGENTS.md support was supposed to remove.

Why the silence matters

The author argues that turning telemetry off should cost diagnostics and nothing else, and that a remote switch makes little sense for a feature whose only input already sits on disk. The gate falls hardest on the users most interested in AGENTS.md: people who keep one instruction file for several agents, and teams that disable nonessential traffic by policy. Since nothing is logged, most will conclude that the model ignored their instructions. He asks for a startup warning when an AGENTS.md is present but skipped, and for a user-level AGENTS.md and native support for the shared .agents/skills path that Codex already reads. Until then he keeps the one-line CLAUDE.md and a symlink for skills.