Claude Code: The Telemetry Gate for AGENTS.md [Resolved]

Originally posted on blog.szypowi.cz by Przemek, focusing on performance, CLI tools, and byte-level web movement.

---

🚩 The Core Issue

Starting with version 2.1.277, Claude Code introduced support for AGENTS.md. The intended logic is simple: if no CLAUDE.md exists, the tool should fall back to reading AGENTS.md.

However, there is a catch. The loader for this file is locked behind a remote feature flag. If you have disabled telemetry or blocked non-essential traffic, Claude Code silently ignores your local AGENTS.md without any warning.

🔍 Where the Gate is Located

The functionality is handled by a built-in plugin named agents-md. In the 2.1.280 bundle, the registration logic looks like this:

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

Essentially, the availability of the feature is defined by the logic: $\text{Feature Enabled} = \text{Remote Flag}(\text{tengu\_agents\_md\_mod}) \lor \text{Default}(\text{false})$

If the tool cannot reach the server to verify the flag, it defaults to false. It is paradoxical that reading a local file requires a network request.

---

🧪 Testing Methodology

To verify this, I created a controlled environment:

1. An empty directory.
2. A file named AGENTS.md containing a specific "canary" word.
3. A prompt asking Claude to identify that word without reading other files.

The Test Command:

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

Note: I ran each setup across two sessions, as the first session fetches the flag and the second applies it.

📊 Measurement Results

I tested various configurations to see what blocked the loader:

Crucially: In every failure case, there was no warning. The model simply answered without the instructions, leaving the user to wonder why. This also affects users on Bedrock and Vertex, where these flags often fail to resolve to true.

---

🛠️ The Workaround

Since CLAUDE.md supports @path imports—and these imports do not depend on the remote flag—you can bypass the gate with a one-line file:

echo '@AGENTS.md' > CLAUDE.md

By adding this, the canary test passes even with CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 active. The downside? You now have to maintain an extra file per repository, which is exactly what AGENTS.md support was meant to eliminate.

---

🗯️ Why This is Unacceptable

"A privacy setting should never quietly switch off unrelated local behavior."

I intentionally disable telemetry to limit diagnostics, not to lose local functionality. Using a remote flag for a feature that only requires a local disk read is poor design.

This specifically penalizes the "power users" who are most likely to use AGENTS.md (those managing multiple agents across different tools) and enterprise teams on Bedrock/Vertex who disable non-essential traffic by policy. Most users won't perform a binary string search or a canary test; they will simply assume the model is ignoring them and waste hours tweaking prompts.

---

🎯 Desired Improvements

I would like to see the following changes implemented:

• Decouple local file reading from telemetry/remote flags.
• Implement warnings: If a flag prevents AGENTS.md from loading, notify the user at startup.
• Global Support: Allow a user-level AGENTS.md (similar to how Codex handles ~/.codex/AGENTS.md).

A Note on Skills and Symlinks

Claude Code's /import command copies skills into .claude/skills, but this leads to version drift.

My Solution: Instead of copying, I use a symlink to keep my project skills synced: ln -s ../.agents/skills .claude/skills

Until the telemetry gate is removed, I will continue using the one-line CLAUDE.md and symlinked skill directories.