Claude Code 2.1.277 only reads AGENTS.md when telemetry is enabled

Feature flag gating AGENTS.md loading

Claude Code 2.1.277 introduced built‑in support for reading an AGENTS.md file when a project lacks a CLAUDE.md file.

The loader is implemented as a plugin named agents‑md that registers in the 2.1.280 bundle with an isOnByDefault flag set to false.

The plugin’s availability depends on a remote feature flag called tenguagentsmd_mod, which defaults to false if the request fails.

When the flag cannot be retrieved, the plugin remains unavailable and the local AGENTS.md file is never read, even though reading a markdown file does not require network access.

This gating behavior means that telemetry must be enabled for the feature to activate.

The issue was first reported in GitHub issue #95690, where the author noted that AGENTS.md never loaded with telemetry disabled.

Testing methodology and results

To verify the claim, the author created an empty repository containing only an AGENTS.md file with a distinctive canary word.

The test command claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.' was run in two separate sessions to isolate flag fetching from flag usage.

In the first session the model attempts to fetch the feature flag; in the second session it relies on the cached result.

Setting the environment variable CLAUDECODEDISABLENONESSENTIALTRAFFIC=1 prevented the feature from loading, confirming the flag’s role.

Likewise, setting DISABLE_TELEMETRY=1 also blocked the AGENTS.md read, matching the behavior described in the issue.

Resetting either variable to 0 did not re‑enable the feature, because the plugin retains the blocked state for the duration of the process.

The documentation for these variables states that any non‑empty value counts as true, a nuance that can be missed when attempting to enable the feature.

Adding the same variables with empty strings to a project‑level .claude/settings.json file had no effect on the gating logic.

No warning or diagnostic message is emitted when the plugin skips loading the file, leaving users unaware of the silent failure.

Third‑party gateways such as Amazon Bedrock and Google Vertex encounter the same limitation because they cannot resolve the remote flag to true.

A session‑level override that clears both environment variables does succeed, but only from the second session onward, after the flag has been fetched.

The override command claude --settings '{"env":{"DISABLETELEMETRY":"","CLAUDECODEDISABLENONESSENTIAL_TRAFFIC":""}}' demonstrates that the plugin respects explicit runtime settings.

Workaround using @path import

Because the feature cannot be toggled on a per‑repository basis, developers need an alternative approach to provide project instructions without telemetry.

Claude Code supports @path imports inside a CLAUDE.md file, and these imports do not depend on the remote feature flag.

By creating a minimal CLAUDE.md that contains a single line @AGENTS.md, the AGENTS.md content becomes reachable even when telemetry is disabled.

The author confirmed that the canary word is correctly returned when the @path import is used, despite CLAUDECODEDISABLENONESSENTIALTRAFFIC remaining set to 1.

This workaround adds only one extra file to the repository, preserving the intended project instruction workflow.

However, it also reintroduces a CLAUDE.md file, which some teams may have intentionally omitted to keep configuration minimal.

The underlying design illustrates how Anthropic’s reliance on server‑side feature flags can unintentionally couple local file loading to telemetry settings.

Users who require deterministic project instruction loading should either keep telemetry enabled or adopt the @path import strategy.

Future revisions of Claude Code could expose a direct opt‑in flag for AGENTS.md, reducing the need for workarounds.

Monitoring upcoming releases and the GitHub issue tracker will help developers stay informed about any changes to this behavior.

Why This Matters