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-registration-and-dependencies

Telemetry registration and dependencies

Overview

The telemetry mod exposes built-in plugin analytics as a Claude Code plugin. Its manifest at mods/…/plugin.json names the plugin, points TypeScript consumers at mods/…/index.d.ts, and mirrors the README's contract: $.telemetry.log and $.telemetry.mark queue first-party analytics rows. The hook manifest at mods/…/hooks.json loads mods/…/register.ts, while mods/…/index.ts re-exports the public hook modules, including registration, dependency construction, context/facts, policy pins, and telemetry construction.

mods/…/register.ts is the runtime entrypoint. It installs a telemetry.* gate, concrete telemetry.log and telemetry.mark handlers, session.start/session.end hooks, and an engine.create fold. The gate delegates to mods/…/served.ts, which permits only origins whose next.origin.tier is builtin or core as declared in mods/…/served-tiers.ts; missing origin data throws and is converted by mods/…/caught.ts into the refusal from mods/…/refused.ts. This means installed or admin-listed plugins get a denial before the telemetry-specific handlers queue anything.

The engine.create hook in mods/…/register.ts calls await next(e) first, then constructs a sender with telemetryOf from mods/…/telemetry-of.ts. It adapts the engine nouns beneath into the TelemetryDeps interface from mods/…/telemetry-deps.ts: session authorization, id/model/surfaces/cwd/repo/version, environment reads, policy settings, fs reads/lists/existence, one process run with Context.PROBE_TIMEOUT_MS, HTTP fetch, clock timers/sleeps, and debug logging. It returns { telemetry, ...beneath }, so a telemetry noun already supplied by a lower engine layer wins; otherwise this mod adds the noun.

telemetryOf owns queueing and sending. log and mark validate inputs through the entries layer and push a pending row with a random event id and timestamp. Batches flush after BATCH_WINDOW_MS from mods/…/batch-window-ms.ts, immediately at BATCH_ROWS from mods/…/batch-rows.ts, and on session.end via sender.flush() in mods/…/register.ts. Each send rereads the analytics switches and policy pins, obtains a fresh authorization handle with deps.authorize(), shapes rows with the session context, posts to the ingest URL, retries once for failed requests or retriable HTTP statuses, and writes success/failure to the debug log. The telemetry.log hook passes entries with to: 'collector' down to hooks beneath; telemetry.mark is always this mod's first-party feature event path.

The public noun contract lives in mods/…/index.d.ts. It declares Telemetry, TelemetryLogEntry, TelemetryMarkEntry, TelemetryDestination, TelemetryMarkKind, TelemetryProp, and TelemetryChoice, and augments claude-code's EngineInterface with telemetry. log accepts an event name and optional props, with to defaulting to anthropic and collector meaning “leave it to the collector beneath.” mark accepts a feature, ok/sad/bad, an error reason only for non-ok marks, and optional props. Values are intentionally limited to finite numbers, booleans, or declared choices; bare strings are not allowed.

Context is gathered once per session by mods/…/context-of.ts, which calls probeOf in mods/…/probe-of.ts and then shapes identity, session fields, environment fields, and remote hash. The Facts type in mods/…/facts.ts lists environment variables read once to describe the session, while mods/…/environment.ts lists variables reread before every batch to decide whether analytics may be sent. Identity comes from .claude.json through mods/…/identity-of.ts and mods/…/global-config-path.ts; account/organization ids pass only length plausibility checks and email is kept only when USER_TYPE marks the build internal. Machine data comes from Windows environment variables or one sh -c probe built by mods/…/probe-script.ts, normalized by arch-of and platform-of. Linux-only context reads /etc/os-release, /proc/version, /sys/hypervisor/uuid, and /.dockerenv through mods/…/linux-files-of.ts.

The row environment block is built in mods/…/environment-fields-of.ts. It derives client type and entrypoint from mods/…/client-type-of.ts and mods/…/entrypoint-of.ts, terminal and shell from closed lists in mods/…/terminal-of.ts and mods/…/shell-of.ts, deployment from environment/file signals, GitHub Actions metadata only when GITHUB_ACTIONS is truthy, VCS markers from mods/…/vcs-of.ts, and a repository remote hash from mods/…/remote-hash-of.ts. The remote hash normalizes git scp/URL remotes to host/path, lowercases them, hashes with SHA-256, and keeps the first 16 hex digits.

Policy pins are typed by mods/…/policy-pins.ts as the managed settings keys forceLoginMethod and forceLoginGatewayUrl. mods/…/is-analytics-off.ts uses those pins together with batch-time environment reads to suppress sending under tests, DISABLE_TELEMETRY, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DO_NOT_TRACK, unmanaged third-party provider switches, gateway use, or a custom OAuth URL. If those reads or policy reads fail, telemetryOf logs that analytics switches could not be read and sends nothing.

Coverage / routing

This document owns the registration, metadata, dependency, type, context, facts, and policy surfaces for:

Coupling

  • If mods/…/index.d.ts changes the Telemetry entry shapes, also update mods/…/checked-fields.ts, mods/…/checked-mark.ts, and mods/…/register.ts: callers compile against the declaration, but the hooks validate unknown runtime input and reject mismatches with { deny }.
  • If mods/…/telemetry-deps.ts adds or renames a dependency, update the adapter in mods/…/register.ts and the context/sender call sites that consume it. telemetryOf and Context.contextOf do not reach $ directly; missing adapter wiring silently leaves the sender unable to gather or send.
  • If the host's origin tiers change, verify mods/…/served-tiers.ts and mods/…/served.ts: this gate is the only barrier that keeps installed plugins from using first-party telemetry.
  • If analytics-off policy or environment semantics change, update both mods/…/is-analytics-off.ts and the batch-time environment/policy readers in mods/…/register.ts. mods/…/telemetry-of.ts treats unreadable switches as “send nothing,” so new switches must be wired into the dependency object before they can suppress batches.
  • If environment fact fields in mods/…/facts.ts change, update the facts builder in mods/…/register.ts and the reducers under mods/telemetry/hooks/context/** that shape those facts. Secret or user/host-identifying variables should continue to be reduced to booleans before entering Facts.
  • If the ingest schema changes, verify mods/…/event-data-of.ts, mods/…/wire-of.ts, and mods/…/batch-of.ts: rows are constructed with camelCase internally and recursively respelled to snake_case only at the final wire boundary.
  • If engine.create layering changes, verify the spread order in mods/…/register.ts. The current { telemetry, ...beneath } intentionally preserves a telemetry noun supplied beneath; reversing it would replace an engine-native telemetry implementation.

Risks

  • mods/…/register.ts contains a long hand-built map from environment variable names into Environment, Facts, deployment signals, and config location. If a variable is misspelled or added only to a type in mods/…/facts.ts or mods/…/environment.ts, the corresponding context column or analytics-off switch will be absent without a compile-time guarantee that the intended host variable was read.
  • mods/…/probe-of.ts gathers context once and mods/…/telemetry-of.ts caches it after the first successful gather. If session-level facts such as cwd, repo, terminal, or global config identity change mid-session, later batches keep the original context while only analytics-off switches and authorization are reread.
  • mods/…/machine-of.ts runs a shell probe from mods/…/probe-script.ts on non-Windows platforms. If sh, uname, or command -v is unavailable or times out, platform becomes unknown and package-manager/runtime fields become empty, which then affects platform-dependent environment fields in mods/…/environment-fields-of.ts.