Introducing a new way to review your PRs.

Read the announcement

anthropics / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / telemetry-gating-environment-and-deployment

Telemetry gating, environment, and deployment

Overview

This area owns the privacy gates and runtime classifiers that decide whether telemetry may proceed and how sent rows describe their runtime. mods/…/register.ts wires the pieces into the engine: the first hook on telemetry.* calls Gate.served from mods/…/served.ts, and its catch handler calls Gate.caught from mods/…/caught.ts. Only calls whose next.origin.tier is in SERVED_TIERS (builtin or core, from mods/…/served-tiers.ts) are passed down to the telemetry implementation; other tiers receive the REFUSED sentinel from mods/…/refused.ts. A missing origin tier is treated as a malformed host call and throws, but the catch hook converts a pre-continuation gate failure into the same refusal. If the continuation had already been called, caught replays it so lower hook failures are preserved rather than rewritten as gate refusals.

Telemetry collection can still be stopped later at send time. mods/…/register.ts builds the Environment object by reading USER_TYPE, NODE_ENV, DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DO_NOT_TRACK, CLAUDE_CODE_CUSTOM_OAUTH_URL, CLAUDE_CODE_USE_GATEWAY, CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST, and the provider switches for Bedrock, Vertex, Foundry, Anthropic AWS, Anthropic Google Cloud, and Mantle. mods/…/telemetry-of.ts calls deps.environment() and deps.policy() before priming context and before each batch send, then passes them to mods/…/is-analytics-off.ts. If this check returns true, or if reading those inputs throws, context is not gathered for priming and queued rows are not sent.

isAnalyticsOff mirrors the CLI privacy rules with two small value interpreters. mods/…/is-env-set.ts treats any non-empty string as set, so DISABLE_TELEMETRY=0 and CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=0 still disable telemetry. mods/…/is-env-truthy.ts treats trimmed, case-insensitive 1, true, yes, and on as true. Analytics is off when NODE_ENV is test, either disable variable is set, DO_NOT_TRACK is truthy, a third-party provider switch is truthy without CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST being truthy, gateway mode is indicated by CLAUDE_CODE_USE_GATEWAY or managed policy pins, or CLAUDE_CODE_CUSTOM_OAUTH_URL is non-empty after trimming. When sending is allowed, telemetry-of.ts still uses environment.userType to label batches as ant only for USER_TYPE=ant; all other values are sent as external.

Deployment probing feeds row context rather than the privacy gate. mods/…/register.ts supplies deps.deployment() as a list of [deploymentName, signalHeld] pairs, using the same isEnvSet and isEnvTruthy helpers plus exact-value checks such as AWS_EXECUTION_ENV === AWS_ECS_FARGATE and an APP_URL suffix check for DigitalOcean App Platform. The canonical priority order lives in mods/…/deployments.ts; mods/…/deployment-of.ts returns the first deployment in that order whose signal is present, or unknown-<platform> when none match. mods/…/environment-fields-of.ts writes that result into the row's deploymentEnvironment field during context shaping. File-based deployment signals, currently described by mods/…/linux-files.ts as EC2 and Docker signals, share the same DeploymentSignal tuple type from mods/…/deployment-signal.ts and are merged into the probe before deploymentOf is applied.

Coverage and routing

This document owns:

  • mods/telemetry/hooks/is-analytics-off/** — analytics-off decision and environment value parsing.
  • mods/telemetry/hooks/gate/** — telemetry.* served-tier gate, refusal sentinel, and catch behavior.
  • mods/telemetry/hooks/environment/** — Environment shape consumed by the send-time privacy gate.
  • mods/telemetry/hooks/deployment/** — deployment names, signal tuple type, priority order, and deployment selection.

Coupling

  • If any analytics-off environment variable is added, renamed, or its semantics change in mods/…/is-analytics-off.ts, also update the reader in mods/…/register.ts and the Environment type in mods/…/environment.ts; telemetry-of.ts only sees the already-shaped Environment, so a missing field silently leaves telemetry enabled for that condition.
  • If changing truthiness or set-ness in mods/…/is-env-set.ts or mods/…/is-env-truthy.ts, check both privacy gating and context/deployment callers. register.ts uses isEnvSet to record presence-only facts such as session tokens and terminal markers, while deployment detection uses both helpers, so a privacy-motivated helper change can also alter row context.
  • If a new caller tier should be allowed to call $.telemetry, update mods/…/served-tiers.ts and verify the refusal text in mods/…/refused.ts; Gate.served uses a plain string membership check against next.origin.tier, so no type-level exhaustiveness check will catch a missed tier.
  • If adding a deployment name, update all three sides together: mods/…/deployments.ts for priority, mods/…/register.ts or the Linux-file probe for the signal source, and any row-context expectations around deploymentEnvironment. deploymentOf ignores signals whose names are not present in DEPLOYMENTS, and when multiple signals hold the earlier deployment in DEPLOYMENTS wins regardless of signal order.
  • If gateway policy fields change, verify mods/…/is-analytics-off.ts against the PolicyPins source. The privacy decision treats forceLoginMethod === 'gateway' and any defined forceLoginGatewayUrl as send blockers even when the runtime CLAUDE_CODE_USE_GATEWAY variable is absent.

Risks

  • mods/…/is-analytics-off.ts disables telemetry on any non-empty custom OAuth URL after trimming, but isEnvSet itself does not trim. If a future caller reuses isEnvSet directly for trimmed privacy switches, whitespace-only values may be treated inconsistently and either over-block or under-block sends.
  • mods/…/deployments.ts controls priority globally while mods/…/register.ts emits multiple signals for some platforms (coder, devpod, aws-cloud9, railway, fly.io, azure-app-service). If a broad signal such as ci, gcp, or kubernetes is moved earlier in DEPLOYMENTS, more specific deployments can be masked and rows will report the wrong deploymentEnvironment.