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:
mods/telemetry/.claude-plugin/**- mods/…/README.md
- mods/…/hooks.json
- mods/…/index.ts
- mods/…/register.ts
mods/telemetry/hooks/telemetry-deps/**mods/telemetry/hooks/telemetry-of/**mods/telemetry/hooks/policy-pins/**mods/telemetry/hooks/context/**mods/telemetry/hooks/facts/**mods/telemetry/types/**
Coupling
- If mods/…/index.d.ts changes the
Telemetryentry 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.
telemetryOfandContext.contextOfdo 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/policyreaders 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
factsbuilder in mods/…/register.ts and the reducers undermods/telemetry/hooks/context/**that shape those facts. Secret or user/host-identifying variables should continue to be reduced to booleans before enteringFacts. - 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.createlayering 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, orcommand -vis unavailable or times out, platform becomesunknownand package-manager/runtime fields become empty, which then affects platform-dependent environment fields in mods/…/environment-fields-of.ts.