Claude Code reads AGENTS.md only when telemetry is on

blog.szypowi.cz · Hitchhiking through raw bits ·

5 min read Original article ↗

Claude Code 2.1.277 announced support for AGENTS.md. In a project with no CLAUDE.md, it is supposed to read AGENTS.md instead. I keep telemetry off in my shell, and in my repos the file never loaded. Issue #95690 explains why, and I added my own measurements to it. This post collects them in one place.

Where the gate is

The loader ships as a built-in plugin called agents-md. Its registration in the 2.1.280 bundle looks like this:

var W = !1;
var B = () => Oa("tengu_agents_md_mod", W);
var H =
  "AGENTS.md as project instructions: by default loaded where the project has no CLAUDE.md; ...";

W is the plugin’s isOnByDefault value and it is false. B is isAvailable, and it asks a remote feature flag called tengu_agents_md_mod, with false as the fallback. When Claude Code cannot fetch the flag, the plugin is unavailable, and the local file is never read. Reading a markdown file from the working directory needs no network at all, but here it waits on a server-side switch.

How I tested it

I made an empty directory that holds only an AGENTS.md with a canary word in it, and asked claude -p for the word. Each setup ran in two sessions, because the first session in a new configuration only fetches the flag and the second one uses it.

echo 'The canary word is PERIWINKLE.' > AGENTS.md
claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'

What I measured

  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 blocks the feature, as the issue says.
  • DISABLE_TELEMETRY=1 blocks it too. With either variable set, AGENTS.md never loaded, so I had to clear both.
  • Setting either variable to 0 does not help. The block stays in place. The environment variable docs say that any value counts, but that is easy to miss when you try to turn a feature on.
  • An env block in the project’s .claude/settings.json that clears both variables has no effect. There is no way to turn the feature on for a single repo.
  • A session-level override does work from the second session on:
claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'

None of these cases print a warning. The session starts, the model answers without the project instructions, and nothing tells you that a file was skipped. The issue also points out that third-party gateways, Bedrock and Vertex have the same problem, because the flag cannot resolve to true there either.

The workaround

CLAUDE.md supports @path imports, and those do not depend on the flag. A one-line CLAUDE.md next to the AGENTS.md loads it with telemetry off:

echo '@AGENTS.md' > CLAUDE.md

With that file in place, the same canary test returns the word with CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 still set. The cost is one extra file per repo, which is what the AGENTS.md support was supposed to remove.

Why I think this is unacceptable

I turned telemetry off on purpose, and I expect that choice to cost me some diagnostics and nothing else. Here it silently costs me a feature that reads a file from my own disk. A remote flag can make sense for a feature that talks to a server, but the only input this one needs is already in the working directory.

The gate also hits the people who are most likely to care about AGENTS.md. Someone who keeps one instruction file for several agents is usually careful about what each tool sends home, and teams on Bedrock, Vertex or a gateway often disable nonessential traffic by policy. They all get a feature that is announced as available and then does nothing.

The silence is the worst part. I confirmed the cause with a canary word and a string search through the binary, and most people will not do that. They will conclude that the model ignores their instructions, and they will spend time on prompts when the file never reached the model in the first place.

A privacy setting should never quietly switch off unrelated local behavior. If Anthropic wants a staged rollout, the fallback for a flag that cannot be fetched should be the documented behavior, or at least a visible message that says what was skipped and why.

What I would like to see

  • Reading a local file should not depend on telemetry. If the gate has to stay for a gradual rollout, a startup warning when an AGENTS.md is present and skipped would save people the time I spent on a canary test.
  • A global AGENTS.md. 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, and the /import command in Claude Code can copy it into the user CLAUDE.md, but the copy does not follow later edits. If you keep one set of personal instructions for several agents, you still need an @ import in the user CLAUDE.md that points at the shared file.
  • Native support for shared agent skills. Codex reads skills from .agents/skills in the project and from ~/.agents/skills in the home directory. Claude Code 2.1.280 knows those paths only in /import, which copies the skills into .claude/skills. I put a canary skill in .agents/skills and Claude Code did not list it, but it listed the same skill from .claude/skills in the same repo. A copy drifts from the source, so I link .claude/skills to ../.agents/skills instead, and Claude Code follows that symlink.

Until then, I use the one-line CLAUDE.md for instructions and a symlink for skills.