surshar / 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.

Built by Anthropic · github.com/anthropics

claude-code / mods / telemetry / README.md

Alice T'PoteatMerge pull request #93244 from anthropics/poteat/mods-telemetry-fixes fb63c4a · on Sep 10, 2026 History

51 lines · 2.5 KBPreview CodeRaw

1	# telemetry
2
3	Plugin analytics as a plugin: one `engine.create` step adds `$.telemetry`
4	to the engine interface every plugin above it is handed, built over the
5	`$.session` and `$.http` nouns beneath. `$.telemetry.log({ event, props })`
6	sends one event as one first-party row, `tengu_plugin_<event>`;
7	`$.telemetry.mark({ feature, kind, reason? })` marks one use of a feature as
8	the CLI's own feature events do, `tengu_feature_<kind>` with a
9	`feature_name`. Each call is one POST to the event-logging ingest with the
10	session's own credential (`$.session.authorize()`, resolved at each call),
11	one attempt, nothing batched; a session with no first-party credential, or
12	an ingest that refuses, rejects the caller's promise.
13
14	It sends nothing wherever the CLI's own analytics are off: under
15	`DISABLE_TELEMETRY`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or
16	`DO_NOT_TRACK`, on any third-party provider (Bedrock, Vertex, Foundry and
17	kin), and on a deployment with its own OAuth URL. Each is read through
18	`$.env` at every call, rows go one after another, and the credential is
19	authorized afresh right before each POST, so a session that has since moved
20	to a third-party provider or a cloud gateway sends nothing more. The row's
21	`user_type` is `ant` when `USER_TYPE` says so, else `external`.
22
23	Nothing free-form reaches a row. An event name and every property key is a
24	snake_case token; a value is a finite number, a boolean, or a Choice (a
25	string named together with the list it is chosen from); `mark` takes `ok`,
26	`sad` or `bad`, with a `reason` required on the last two and refused on the
27	first. An entry that breaks a rule is refused before anything is sent.
28
29	`hooks/register.ts` is the module; `hooks/telemetry-types/` is the noun's
30	type as a caller sees it.
31
32	## What it hooks
33
34	`engine.create`: `{ ...await next(e), telemetry }`, so the noun is added and
35	nothing beneath is replaced.
36
37	## What it calls on `$`
38
39	`session.authorize`, `session.id`, `session.model`, `http.fetch`, `env.get`
40	(the switches above and `USER_TYPE`, by literal name), each on the
41	interface the fold handed it.
42
43	## Where it runs
44
45	This plugin is seated by the CLI itself, on internal builds whose own
46	analytics are on, and nowhere else: `session.authorize` exists only there,
47	and the rows it writes join tables only the CLI's own events reach. It is
48	not meant to be installed or loaded with `--plugin-dir`; the folder has a
49	manifest so it reads like every other plugin, not so it can stand alone. A
50	plugin that calls `$.telemetry` where this one is absent finds no such noun
51	and should treat that as "no analytics here".