Claude Code's AGENTS.md Telemetry Gate: What Broke and What Fixed It (2026)

Quick answer: In Claude Code v2.1.277, support for AGENTS.md project instructions shipped inside a built-in mod gated by a remote Statsig feature flag named tengu_agents_md_mod. Developers who disabled telemetry via DISABLE_TELEMETRY=1 or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, along with teams routing through Amazon Bedrock, Google Vertex, Microsoft Foundry, or air-gapped proxies, had their local AGENTS.md files silently ignored without warnings. Anthropic engineer mpoteat confirmed on Hacker News that the gate was an unintentional rollout artifact, and Anthropic fixed the issue in v2.1.281 released on September 24, 2026.

You spend an hour writing repository rules for an autonomous coding agent. You define the exact command to run test suites, forbid editing generated database migrations, and block commits containing secrets. You put those guidelines in AGENTS.md so that teammates running different coding agents can share the same configuration. You launch the agent, give it a prompt, and watch it rewrite a protected migration script while guessing at your test commands.

The model did not disobey your rules. The CLI client checked a remote feature flag, failed to resolve it because you turned off network telemetry, and skipped reading the file before assembling the prompt.

An honest early disclosure: you are reading this on the blog of SaaSCity, a startup directory featuring a live city map and human editorial review. If you build software, you know that discovery requires deliberate declaration. A product does not get picked up by buyers or indexed by AI search engines by accident; it needs an explicit, machine-readable, human-reviewed listing. SaaSCity offers a free listing page and a building on our map. Adding the SaaSCity badge to your site earns a dofollow backlink from a domain rated DR 47 to 56 at our latest Ahrefs refresh, plus a slot in our Monday launch cohort. Quick Pass ($19.99) approves listings within 24 hours. Premium ($99.99) includes an editorial launch post with three dofollow links. AI agents can also submit listings directly using our free MCP server.

That parallel explains why this bug matters: whether you configure an AI agent or launch software for distribution, relying on implicit background discovery fails without notice. Systems need explicit contracts.

The canary test: how silent exclusion behaves

On September 23, 2026, developer Przemek Szypowicz published an analysis showing how instructions vanished. In a fresh directory containing only an AGENTS.md, he added the canary word PERIWINKLE:

# Project Instructions
The canary word for this project is: PERIWINKLE.

He then ran a non-interactive query:

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

The prompt instructed Claude to answer strictly from its preloaded project instructions without running shell commands or opening files. Szypowicz ran the command twice per configuration because the first session in a new configuration only fetches and caches the flag.

The test produced three outcomes across configurations:

1. Telemetry on, default settings: On the second session run, Claude returned PERIWINKLE.
2. Telemetry off (DISABLE_TELEMETRY=1 or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1): Claude answered NONE.
3. Cloud provider endpoints (Bedrock, Vertex, Foundry): Claude answered NONE.

The failure produced zero terminal output, no warnings, and no log entries. The tool started normally while dropping repository rules from context.

The code: the Statsig gate in mods/agents-md

On September 20, 2026, developer Prefee filed GitHub issue #95690 in the public anthropics/claude-code repository, titled "[MODEL] Claude Code's AGENTS.md Support: A Local Feature Locked Behind a Remote Switch".

The issue cited the v2.1.277 changelog line from the official changelog:

"Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config (not yet on Bedrock, Vertex or Foundry)"

Rather than loading through the base configuration parser, the feature was built as an internal mod named agents-md, referenced alongside memory features in the Claude Code memory documentation.

The plugin source code sits under mods/agents-md in the public repository.

In the compiled distribution bundle for v2.1.277 through v2.1.280, the plugin registered with isOnByDefault = false and evaluated an isAvailable check:

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; ...";

Here, W is the fallback false. The function Oa queries Statsig, a feature-flagging platform Anthropic uses for staged deployments. If the client reaches Statsig, the lookup returns true and Claude Code parses AGENTS.md. Without telemetry, the check falls back to false and skips the file without an error.

Both DISABLE_TELEMETRY and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC are presence-based flags: setting either to 0 still counts as an opt-out. An env block in .claude/settings.json clearing both variables does not enable the feature. Only a session-level launch override works: claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}', which takes a second session to apply once cached.

Environment impact matrix

The failure selectively broke environments configured for privacy, security, or corporate compliance:

Environment / Configuration	AGENTS.md Loaded (v2.1.277 to v2.1.280)	Behavior Details	Status in v2.1.281
Default CLI (consumer API, telemetry on)	Loaded (after 1st session)	First run downloads flag; second session parses AGENTS.md.	Fixed per Anthropic in v2.1.281
DISABLE_TELEMETRY=1	Skipped silently	Statsig client disabled; mod falls back to false.	Fixed per Anthropic in v2.1.281
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1	Skipped silently	Nonessential traffic blocked; flag unreachable.	Fixed per Anthropic in v2.1.281
Amazon Bedrock provider endpoints	Skipped silently	Cloud providers bypass Anthropic Statsig endpoints.	Fixed per Anthropic in v2.1.281
Google Vertex AI provider endpoints	Skipped silently	Cloud service architecture lacks Statsig integration.	Fixed per Anthropic in v2.1.281
Microsoft Foundry provider endpoints	Skipped silently	Cloud service architecture lacks Statsig integration.	Fixed per Anthropic in v2.1.281
Air-gapped enterprise proxy / VPC	Skipped silently	Network firewalls drop requests to external flag servers.	Fixed per Anthropic in v2.1.281
Project-level .claude/settings.json env block	Skipped silently	Clearing variables in project settings has no effect.	Fixed per Anthropic in v2.1.281

Teams running Claude Code in continuous integration pipelines, automated review bots, or private cloud environments operated without project instructions.

Telemetry events versus file contents

When developers discovered the feature gate, initial discussions on social media raised concerns that Anthropic was uploading local markdown files to analytics servers.

That assumption was inaccurate. Claude Code's telemetry system, defined in mods/telemetry, gathers operational health metrics. It tracks execution times, command names like /commit or /config, and closed configuration choices. It does not inspect file paths, project source code, or the markdown content inside AGENTS.md.

The issue was not data exfiltration. The failure was a local feature that waited on a network call. Connecting local filesystem parsing to an external telemetry ping created fragile behavior for developers operating under strict privacy settings.

Hacker News discussion and Anthropic's response

On September 23, 2026, the issue reached the front page of Hacker News on thread 49814947, generating roughly 470 points and 270 comments.

An Anthropic engineer working on Claude Code, posting under the username mpoteat, addressed the thread directly:

"Sorry folks, this is a rollout artifact, we needed a way to turn this off remotely via feature flags if it broke something, and with telemetry off you don't get those. It's already been fixed as part of v2.1.281 releasing today."

He added:

"Apologies again folks, this was a fully human error on my part - I should've found a better way to launch with a kill-switch."

The engineer explained that AGENTS.md support was implemented through a new Claude Code extensibility system called Mods, which he described as "a plugin with a new type of hook, which we call a function hook", noting that Mods is "launching soon-ish". The repository contains other built-in mods in the mods directory, including diff, telemetry, and sec-default. Community feedback on the system is tracked in GitHub issue #91870. On September 24, 2026, Anthropic published Claude Code v2.1.281, addressing the rollout artifact.

The ancestor directory trap: four instruction modes

Claude Code offers four operational modes under "Project instructions" in /config:

Mode	Resolution Behavior	Primary Use Case
claude-md	Loads CLAUDE.md exclusively; ignores all AGENTS.md files.	Projects using Claude-specific instructions only.
claude-md-or-agents-md (Default)	Reads AGENTS.md only when no CLAUDE.md exists in workspace or ancestor paths.	Standard migration path for repos adopting cross-agent rules.
claude-md-and-agents-md	Loads both files, merging instructions into context.	Setups sharing general rules in AGENTS.md and tool commands in CLAUDE.md.
managed-only	Discards local and user files; enforces organizational policy.	Corporate setups governed by centralized enterprise rules.

The default mode, claude-md-or-agents-md, creates a trap. If no CLAUDE.md exists in the project root, Claude Code walks up parent directories. Finding a personal file at ~/CLAUDE.md or in an ancestor monorepo folder causes it to load that file and skip the local AGENTS.md. Developers who never disabled telemetry can still miss instructions under this behavior. To parse both files, set the mode to claude-md-and-agents-md.

The explicit import pattern: a permanent solution

Claude Code's markdown parser supports an @path import syntax to inline referenced files into context. Place a one-line CLAUDE.md next to AGENTS.md:

# Repository Instructions
@AGENTS.md

Generate it with:

echo '@AGENTS.md' > CLAUDE.md

This pointer bypasses remote feature flags through the core parser, prevents ancestor file conflicts, and functions across Bedrock, Vertex, and Foundry.

Cross-tool conventions still require attention. OpenAI Codex reads global rules from ~/.codex/AGENTS.md, whereas Claude Code lacks user-level AGENTS.md support. Codex also searches for skills in .agents/skills/, while Claude Code expects .claude/skills/. Symlinking .claude/skills to ../.agents/skills resolves that path difference without duplicating files.

For modular rule architectures, see our guide to CLAUDE.md templates and examples. For scaling across large repositories, read our breakdown of handling massive codebases with Claude Code, and consult our walkthrough of Claude Code skills and plugins.

The procurement lesson for engineering teams

When you install a command-line tool, you expect local operations to run on local compute. Wrapping a local file read in a remote analytics feature flag breaks that expectation. When network analytics are blocked, the feature fails without error messages or log output.

A vendor can alter developer tool behavior between releases without a version bump, leaving teams unable to observe the change until an agent violates repository constraints. As examined in our analysis of better models and worse tooling for SaaS builders, engineering teams must ask vendors how local features fail, and whether those failures are visible.

Repository audit checklist

Take thirty minutes to audit how your repositories interact with coding agents:

1. Update your CLI: Run npm install -g @anthropic-ai/claude-code@latest and verify that claude --version shows 2.1.281 or higher.
2. Run the canary verification: Add the word PERIWINKLE to AGENTS.md and confirm that claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.' outputs PERIWINKLE on the first attempt.
3. Audit ancestor paths: Inspect ~ and parent workspace folders for stray CLAUDE.md files that might suppress local AGENTS.md instructions under the default mode.
4. Standardize on explicit imports: Place echo '@AGENTS.md' > CLAUDE.md in repository roots to ensure rules load consistently across CI pipelines, cloud gateways, and local workstations.

Verifying your configuration takes under five minutes and prevents hours of debugging silent prompt failures.

Contracts require verification

AI coding agents are only as reliable as the boundaries we establish for them. When an agent ignores repository rules, edits locked files, or skips tests, your team absorbs the cleanup cost.

Instruction files are contracts that bring deterministic guardrails to probabilistic models. When client software gates those contracts behind remote switches, reliability disappears. Anthropic shipped v2.1.281 on September 24, 2026, fixing the rollout artifact after public discussion on Hacker News.

The broader responsibility belongs to engineering teams. Never assume an agent read your instructions simply because a markdown file exists on disk. Run the canary test, verify parser output, and use explicit configurations that work regardless of network state.