Engineers building with AI coding assistants often assume that disabling telemetry only stops data collection. In at least one popular tool—Anthropic's Claude Code—turning off telemetry also silently disables critical configuration features. This article explains the mechanics of that dependency, why it exists, and what builders should demand from AI tools going forward.
How Claude Code reads (or skips) AGENTS.md based on telemetry state
Claude Code uses a file called AGENTS.md to store project-level instructions that shape how the assistant behaves. Think of it as a custom system prompt for your codebase—rules about style, architecture, or domain-specific conventions.
When telemetry is enabled, Claude Code parses AGENTS.md and incorporates those instructions into every interaction. When telemetry is disabled, the tool skips reading the file entirely. The configuration still exists on disk, but the agent ignores it.
This is a design choice, not a bug. By tying agent customization to telemetry state, the tool enforces a binary: share usage data or lose project-specific intelligence. No middle ground, no granular controls.
If your AI assistant only works when it phones home, you're not configuring a tool—you're opting into a data exchange.
The technical justification is that telemetry data feeds model improvements, and custom agents benefit from those improvements. But the architectural coupling is stronger than necessary. Nothing about reading a local Markdown file requires a network round trip or aggregate usage analytics.
Privacy vs. functionality: the telemetry tax in AI coding assistants
Most developer tools treat telemetry as opt-in analytics—helpful for product teams, harmless to skip. Crash reports, feature usage, anonymous performance metrics. Decline it, and the tool still works.
AI coding assistants blur that line. Telemetry often includes prompt text, code snippets, and interaction logs—not just anonymous click counts. That data trains future models, which in turn improves the assistant. In theory, everyone benefits from the collective corpus.
In practice, this creates a privacy tax: users who decline telemetry subsidize their own degraded experience. They get the base model, but not the tailored behavior that comes from reading project config files. The assistant becomes less useful, not because the user chose poorly, but because the tool's architecture conflates two unrelated concerns.
Compare this to traditional compilers or linters. Disable telemetry in Rust's rustc, and the tool still respects .cargo/config.toml. Turn off VS Code's telemetry, and workspace settings still load. The configuration layer and the data-collection layer operate independently.
AI tools should follow the same principle. Telemetry informs product direction; configuration shapes runtime behavior. They don't need to be joined at the hip.
Reproducing and validating the telemetry-config dependency claim
To verify this behavior in Claude Code, test it yourself in about five minutes. This assumes Claude Code is installed and a project is initialized.
Step 1: Enable telemetry (typically via settings or a config.json file). Create an AGENTS.md file in the project root with a simple directive:
Always use snake_case for variable names in this project.
Step 2: Start a coding session and ask Claude to write a function. Observe whether it follows the naming convention from AGENTS.md. It should.
Step 3: Disable telemetry, restart the tool, and repeat the same prompt. If the coupling exists, Claude will ignore AGENTS.md and default to its base behavior—likely camelCase for variable names in a JavaScript context.
The difference is stark. With telemetry on, the assistant reads project rules and adapts. With telemetry off, it acts as if the file doesn't exist.
This is not speculative. Developers in the Claude community forums have reported exactly this pattern, and Anthropic's documentation implies (though doesn't always explicitly state) that some features require telemetry to be enabled.
What AGENTS.md does and why it matters for agent behavior
The AGENTS.md file is Claude Code's mechanism for persistent context. Instead of pasting the same instructions into every conversation, write them once and the tool ingests them automatically.
Think of it as the difference between telling someone your preferred coffee order every morning versus writing it on a sticky note by the machine. One scales, one doesn't.
Typical use cases include:
- Code style rules beyond what a linter enforces ("prefer functional composition over class inheritance").
- Domain constraints ("this codebase handles medical data; never log patient identifiers").
- Architecture decisions ("migrating from REST to GraphQL; suggest GraphQL resolvers, not Express routes").
Without AGENTS.md, the tool relies on in-conversation memory, which resets every session and degrades as context windows fill. With it, there is stateful intelligence that persists across sessions and scales across team members who share the same project.
| Approach | Persistence | Overhead | Consistency |
|---|---|---|---|
| Manual prompts per session | None | High | Low |
AGENTS.md (telemetry on) | Permanent | One-time write | High |
AGENTS.md (telemetry off) | File exists, ignored | One-time write | None |
When telemetry disables AGENTS.md, the file sits in version control, other developers assume it works, and the assistant silently ignores it.
Designing AI tools that don't force privacy-feature trade-offs
The telemetry-config coupling in Claude Code is not inevitable—it's a design artifact. Better architectures are possible, and builders should demand them.
Separate configuration reads from telemetry pipelines. Reading a local file and respecting its contents should never require a network call or usage logging. If the tool needs to know that AGENTS.md was used (for product analytics), log a boolean flag, not the file's contents.
Make telemetry granular. Instead of a single on/off switch, let users choose what to share: crash reports yes, prompt text no; feature usage yes, code snippets no. This is standard practice in desktop software (Firefox, VS Code, IntelliJ) and should extend to AI tools.
Default to local-first behavior. The assistant should function fully offline with local models or cached prompts. Telemetry can enhance the experience—suggest better completions, inform future models—but the core loop (read config, generate response, write output) should never depend on it.
Privacy and functionality are not opposites. They're orthogonal axes, and good tools let you choose independently on both.
Engineers building the next generation of AI assistants should study how traditional dev tools handle this. The GNU Compiler Collection (GCC) doesn't need source code to compile it. An editor doesn't need keystrokes to apply syntax highlighting. AI tools should follow the same principle: respect configuration locally, collect data optionally.
What this means for builders
If using Claude Code or similar tools, audit telemetry settings and understand what is being traded. If AGENTS.md matters to the workflow, accepting telemetry may be necessary—for now. Document that dependency in team onboarding, so new developers don't waste time troubleshooting why their config is ignored.
If building AI coding assistants, architect them so configuration and telemetry are decoupled from day one. Load project settings from disk as a separate step from logging usage. Use feature flags to enable advanced capabilities (like cloud-synced context or team-wide agents), but never gate local file reads on remote services.
If evaluating tools for adoption, ask vendors directly: Does this tool require telemetry for core features? Can telemetry be disabled while keeping project-specific configurations? If the answer is no, consider it a red flag—not because telemetry is inherently bad, but because tight coupling reveals a lack of architectural hygiene.
The broader lesson: as AI tools become infrastructure, they need to meet the same standards expected from compilers, version control, and operating systems. Privacy should not cost functionality, and configuration should not depend on data collection.
Conclusion
The telemetry-config dependency in Claude Code is a small detail with large implications. It reflects a broader tension in AI tooling: how to balance the collective benefits of usage data against individual control over what gets shared.
The solution is not to ban telemetry—it's to design tools where privacy and functionality are independent choices. Read config files locally, log usage optionally, and let engineers decide what they're comfortable sharing. That's not idealism; it's engineering discipline.
As AI assistants move from novelty to necessity, the teams that get this right will earn trust. The ones that don't will force users to choose between intelligence and autonomy—a false trade-off that doesn't need to exist.