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.

		@@ -9,7 +9,7 @@
9	9	\| --- \| --- \| --- \|
10	10	\| [`sec-default`](sec-default) \| Keeps an organization's classic hooks, prompt content, managed settings and tool policy out of reach of the plugins a person installs; adds no policy of its own. \| Outermost, on a machine with managed settings or for a Team or Enterprise organization, unless managed `prependPlugins` says otherwise \|
11	11	\| [`diff`](diff) \| `/diff`: the session's uncommitted changes in a pane beside the transcript, file by file with their hunks, refreshed as Claude edits files and runs commands. \| Built in \|
12		-\| [`telemetry`](telemetry) \| Adds `$.telemetry` (`log`, `mark`) in the `engine.create` fold so a plugin can record an event as a first-party analytics row; sends nothing wherever Claude Code's analytics are off. \| Built in \|
	12	+\| [`telemetry`](telemetry) \| Adds `$.telemetry` (`log`, `mark`) in the `engine.create` fold so a built-in plugin can record an event as a first-party analytics row, sent in batches; refuses installed plugins; sends nothing wherever Claude Code's analytics are off. \| Built in \|
13	13	\| [`agents-md`](agents-md) \| `AGENTS.md` as project instructions, by one option: loaded where the project has no `CLAUDE.md` of its own (`claude-md-or-agents-md`, the default) or beside it (`claude-md-and-agents-md`), placed and framed exactly as the engine places `CLAUDE.md`, nested ones on a `Read`; or the project's and the person's instruction files dropped and the organization's kept (`managed-only`); or `CLAUDE.md` alone, as the engine reads it (`claude-md`). \| Built in \|
14	14
15	15	Each folder is a complete plugin: `.claude-plugin/plugin.json`, a

		@@ -1,7 +1,7 @@
1	1	{
2	2	"name": "telemetry",
3	3	"version": "0.1.0",
4		- "description": "Plugin analytics: adds $.telemetry in the engine.create fold, so a plugin logs an event or marks a feature's use as one first-party row per call, sent with the session's own credential.",
	4	+ "description": "Plugin analytics: adds $.telemetry in the engine.create fold, so a plugin logs an event or marks a feature's use as a first-party row, sent in batches with the session's own credential.",
5	5	"author": {
6	6	"name": "Anthropic"
7	7	},

		@@ -1,32 +1,55 @@
1	1	# telemetry
2	2
3	3	Plugin analytics as a plugin: one `engine.create` step adds `$.telemetry` to
4		-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?, props? })` marks one use of a
8		-feature as the CLI's own feature events do, `tengu_feature_<kind>` with a
9		-`feature_name` and the mark's properties beside it. Each call is one POST to
10		-the event-logging ingest with the session's own credential
11		-(`$.session.authorize()`, resolved at each call), one attempt, nothing
12		-batched; a session with no first-party credential, or an ingest that
13		-refuses, rejects the caller's promise.
	4	+the engine interface every plugin above it is handed, built over the nouns
	5	+beneath, and a hook on its own two events serves the plugins built into
	6	+Claude Code alone: a call from a plugin a person installed or an
	7	+administrator listed is refused with a reason (the host stamps every call
	8	+with the plugin that raised it, `next.origin`, and the gate reads its tier).
	9	+`$.telemetry.log({ event, props })` queues one event as one first-party
	10	+row, `tengu_plugin_<event>`; `$.telemetry.mark({ feature, kind, reason?,
	11	+props? })` marks one use of a feature as the CLI's own feature events do,
	12	+`tengu_feature_<kind>` with a `feature_name` and the mark's properties
	13	+beside it. Both resolve once the row is queued. Rows go out in batches: one
	14	+POST to the event-logging ingest with the session's own credential
	15	+(`$.session.authorize()`, resolved for each batch) a few seconds after the
	16	+first row was queued, at once when a hundred wait, and when the session
	17	+ends; a batch the ingest refuses with a server error, a timeout or a rate
	18	+limit is tried once more. A session with no first-party credential, or an
	19	+ingest that still refuses, drops the batch; each outcome is one line in the
	20	+debug log.
14	21
	22	+Each row carries what the CLI's own rows carry, gathered through `$` once
	23	+a session: an event id, the install's device id and the signed-in account's
	24	+ids from the CLI's global config, the session's id, model, client type,
	25	+entrypoint and interactivity, and an `env` block (platform and
	26	+architecture from one `uname` probe, terminal, shell, package managers and
	27	+runtimes, CI and GitHub Actions, the remote container, the deployment, the
	28	+Linux distribution and kernel, WSL, the working directory's version
	29	+control), with the repository's remote hash beside the row's properties.
	30	+What the engine alone knows (its version and build time, its runtime's
	31	+version, the process's memory, the request's betas, the subscription tier,
	32	+the calling agent) is not on `$`, and those columns stay empty.
	33	+
15	34	It sends nothing wherever the CLI's own analytics are off: under
16	35	`DISABLE_TELEMETRY`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or
17		-`DO_NOT_TRACK`, on any third-party provider (Bedrock, Vertex, Foundry and
18		-kin), and on a deployment with its own OAuth URL. Each is read through
19		-`$.env` at every call, rows go one after another, and the credential is
20		-authorized afresh right before each POST, so a session that has since moved
21		-to a third-party provider or a cloud gateway sends nothing more. The row's
22		-`user_type` is `ant` when `USER_TYPE` says so, else `external`.
	36	+`DO_NOT_TRACK`, in a test run, on any third-party provider (Bedrock,
	37	+Vertex, Foundry and kin) the host does not manage, on a cloud gateway
	38	+(the environment's switch or the managed policy's login pins), and on a
	39	+deployment with its own OAuth URL. Each is read through `$.env` and
	40	+`$.settings` before every batch, so a session that has since moved to a
	41	+third-party provider or a gateway sends nothing more; when the switches
	42	+cannot be read, nothing is sent either. The row's `user_type` is `ant`
	43	+when `USER_TYPE` says so, else `external`.
23	44
24	45	Nothing free-form reaches a row. An event name and every property key is a
25	46	snake_case token; a value is a finite number, a boolean, or a Choice (a
26	47	string named together with the list it is chosen from), under `log` and
27	48	`mark` alike; `mark` takes `ok`, `sad` or `bad`, with a `reason` required on
28	49	the last two and refused on the first. An entry that breaks a rule is
29		-refused before anything is sent.
	50	+refused before anything is queued. Of the environment, a variable whose
	51	+value is a secret, or names a person or a host, is read for whether it is
	52	+set and nothing more; a shell is its basename from a closed list.
30	53
31	54	`hooks/register.ts` is the module; `types/index.d.ts` is the noun's contract,
32	55	the one declaration of `$.telemetry` that this mod's hooks, a mod calling the
		@@ -35,20 +58,26 @@
35	58	## What it hooks
36	59
37	60	`engine.create`: `{ ...await next(e), telemetry }`, so the noun is added and
38		-nothing beneath is replaced.
	61	+nothing beneath is replaced. `telemetry.*`, the gate: a caller in the
	62	+built-in tier (or the engine) goes on, any other is refused, and a gate
	63	+that throws refuses too. `session.start`, to learn whether a person is at
	64	+the prompt; `session.end`, to send what still waits.
39	65
40	66	## What it calls on `$`
41	67
42		-`session.authorize`, `session.id`, `session.model`, `http.fetch`, `env.get`
43		-(the switches above and `USER_TYPE`, by literal name), each on the
44		-interface the fold handed it.
	68	+`session.authorize`, `session.id`, `session.model`, `session.surfaces`,
	69	+`session.cwd`, `session.repo`, `settings.read`, `env.get` (the switches and
	70	+the describing variables, by literal name), `fs.read`, `fs.list`,
	71	+`fs.exists`, `process.run` (one `sh -c` of `uname` and `command -v`),
	72	+`clock.after`, `clock.sleep`, `http.fetch` and `ui.log` (to the debug log),
	73	+each on the interface the fold handed it.
45	74
46		-## Where it runs
	75	+## Where it runs, whom it serves
47	76
48		-This plugin is seated by the CLI itself, on internal builds whose own
49		-analytics are on, and nowhere else: `session.authorize` exists only there,
50		-and the rows it writes join tables only the CLI's own events reach. It is
51		-not meant to be installed or loaded with `--plugin-dir`; the folder has a
52		-manifest so it reads like every other plugin, not so it can stand alone. A
53		-plugin that calls `$.telemetry` where this one is absent finds no such noun
54		-and should treat that as "no analytics here".
	77	+This plugin is seated by the CLI itself, on every build whose own analytics
	78	+are on, and nowhere else; it serves the plugins bundled with the CLI and
	79	+refuses every other caller. It is not meant to be installed or loaded with
	80	+`--plugin-dir`; the folder has a manifest so it reads like every other
	81	+plugin, not so it can stand alone. A built-in that calls `$.telemetry`
	82	+where this one is absent finds no such noun and should treat that as "no
	83	+analytics here".

		@@ -1,0 +1,5 @@
	1	+/**
	2	+ * The most rows one batch carries: a queue this full goes out at once
	3	+ * rather than on the timer.
	4	+ */
	5	+export const BATCH_ROWS = 100

		@@ -1,0 +1,3 @@
	1	+export * from './batch-rows.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,5 @@
	1	+/**
	2	+ * How long a queued row waits for company before its batch goes out, in
	3	+ * milliseconds; a session that ends sooner sends what waits then.
	4	+ */
	5	+export const BATCH_WINDOW_MS = 5000

		@@ -1,0 +1,3 @@
	1	+export * from './batch-window-ms.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,8 @@
	1	+export * from './batch-rows'
	2	+export * from './batch-window-ms'
	3	+export * from './is-retriable'
	4	+export * from './message-of'
	5	+export * from './pending-row'
	6	+export * from './retry-delay-ms'
	7	+
	8	+export * as default from '.'

		@@ -1,0 +1,6 @@
	1	+export * from './is-retriable.js'
	2	+export * from './status-request-timeout'
	3	+export * from './status-server-error'
	4	+export * from './status-too-many-requests'
	5	+
	6	+export * as default from '.'

		@@ -1,0 +1,15 @@
	1	+import { STATUS_REQUEST_TIMEOUT } from './status-request-timeout'
	2	+import { STATUS_SERVER_ERROR } from './status-server-error'
	3	+import { STATUS_TOO_MANY_REQUESTS } from './status-too-many-requests'
	4	+
	5	+/**
	6	+ * Whether an answer from the ingest is worth the one retry: a server error,
	7	+ * a timeout or a rate limit; anything else it refused stays refused.
	8	+ *
	9	+ * @param status the HTTP status the ingest answered
	10	+ * @returns true for 5xx, 408 and 429
	11	+ */
	12	+export const isRetriable = (status: number) =>
	13	+ status >= STATUS_SERVER_ERROR \|\|
	14	+ status === STATUS_REQUEST_TIMEOUT \|\|
	15	+ status === STATUS_TOO_MANY_REQUESTS

		@@ -1,0 +1,9 @@
	1	+/**
	2	+ * What a batch's failure says, for the refusal each of its rows rejects
	3	+ * with: the error's own message, or the value as text.
	4	+ *
	5	+ * @param error what sending the batch threw
	6	+ * @returns the message
	7	+ */
	8	+export const messageOf = (error: unknown) =>
	9	+ error instanceof Error ? error.message : String(error)

		@@ -1,0 +1,11 @@
	1	+import type Entries from '../../entries'
	2	+
	3	+/**
	4	+ * One row waiting for its batch: the checked fields, and the id and time
	5	+ * it was logged with.
	6	+ */
	7	+export type PendingRow = {
	8	+ fields: Entries.Fields
	9	+ eventId: string
	10	+ loggedAt: string
	11	+}

		@@ -1,0 +1,12 @@
	1	+/**
	2	+ * Where the CLI's global config file is, read off the environment; read to
	3	+ * find the file, never sent.
	4	+ *
	5	+ * The config directory when one is named, else the home directory (the
	6	+ * profile directory on Windows).
	7	+ */
	8	+export type ConfigLocation = {
	9	+ readonly configDir: string \| undefined
	10	+ readonly home: string \| undefined
	11	+ readonly userProfile: string \| undefined
	12	+}

		@@ -1,0 +1,12 @@
	1	+/**
	2	+ * The client types the CLI names by entrypoint alone: the SDKs, the VS Code
	3	+ * and desktop hosts, and the local agent.
	4	+ */
	5	+export const CLIENT_TYPE_BY_ENTRYPOINT: Readonly<Record<string, string>> = {
	6	+ 'sdk-ts': 'sdk-typescript',
	7	+ 'sdk-py': 'sdk-python',
	8	+ 'sdk-cli': 'sdk-cli',
	9	+ 'claude-vscode': 'claude-vscode',
	10	+ 'local-agent': 'local-agent',
	11	+ 'claude-desktop': 'claude-desktop',
	12	+}

		@@ -1,0 +1,4 @@
	1	+/**
	2	+ * HTTP 408: the ingest gave up waiting for the request; worth the one retry.
	3	+ */
	4	+export const STATUS_REQUEST_TIMEOUT = 408

		@@ -1,0 +1,3 @@
	1	+export * from './status-server-error.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,5 @@
	1	+/**
	2	+ * HTTP 500, the first server-side status: it and everything above is the
	3	+ * ingest's own failure and worth the one retry.
	4	+ */
	5	+export const STATUS_SERVER_ERROR = 500

		@@ -1,0 +1,4 @@
	1	+/**
	2	+ * HTTP 429: the ingest is shedding load; worth the one retry after a pause.
	3	+ */
	4	+export const STATUS_TOO_MANY_REQUESTS = 429

		@@ -1,0 +1,3 @@
	1	+export * from './message-of.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,3 @@
	1	+export type * from './pending-row.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,3 @@
	1	+export * from './retry-delay-ms.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,5 @@
	1	+/**
	2	+ * How long the one retry waits after a POST that failed or was answered with
	3	+ * a status worth retrying, in milliseconds.
	4	+ */
	5	+export const RETRY_DELAY_MS = 500

		@@ -1,0 +1,3 @@
	1	+export type * from './config-location.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,3 @@
	1	+export * from './client-type-by-entrypoint.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,26 @@
	1	+import type { Facts } from '../../facts'
	2	+import IsAnalyticsOff from '../../is-analytics-off'
	3	+import { CLIENT_TYPE_BY_ENTRYPOINT } from './client-type-by-entrypoint'
	4	+
	5	+/**
	6	+ * The row's `client_type` as the CLI decides it at start: a GitHub Action,
	7	+ * an SDK or host by entrypoint, `remote` with an ingress token, else `cli`.
	8	+ *
	9	+ * @param facts the variables as read once for the session
	10	+ * @returns the client type
	11	+ */
	12	+export function clientTypeOf(facts: Facts) {
	13	+ const isRemote =
	14	+ facts.entrypoint === 'remote' \|\|
	15	+ facts.hasSessionAccessToken \|\|
	16	+ facts.hasSessionIngressTokenFile \|\|
	17	+ facts.hasWebsocketAuthFileDescriptor \|\|
	18	+ IsAnalyticsOff.isEnvTruthy(facts.claudeCodeRemote)
	19	+
	20	+ const isGithubAction = IsAnalyticsOff.isEnvTruthy(facts.githubActions)
	21	+
	22	+ return isGithubAction
	23	+ ? 'github-action'
	24	+ : (CLIENT_TYPE_BY_ENTRYPOINT[facts.entrypoint ?? ''] ??
	25	+ (isRemote ? 'remote' : 'cli'))
	26	+}

		@@ -1,0 +1,4 @@
	1	+export * from './client-type-by-entrypoint'
	2	+export * from './client-type-of.js'
	3	+
	4	+export * as default from '.'

		@@ -1,0 +1,17 @@
	1	+import type { EnvironmentFields } from '../environment-fields'
	2	+import type { Identity } from '../identity'
	3	+import type { SessionFields } from '../session-fields'
	4	+
	5	+/**
	6	+ * Everything a row carries that holds for the whole session, gathered once
	7	+ * before the first batch.
	8	+ *
	9	+ * Who it is from, the session's constant fields, its `env` block, and the
	10	+ * repository's remote hash for the metadata.
	11	+ */
	12	+export type Context = {
	13	+ readonly identity: Identity
	14	+ readonly session: SessionFields
	15	+ readonly environment: EnvironmentFields
	16	+ readonly remoteHash: string \| undefined
	17	+}

		@@ -1,0 +1,3 @@
	1	+export type * from './context.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,30 @@
	1	+import type { TelemetryDeps } from '../telemetry-deps'
	2	+import type { Context } from './context'
	3	+import { environmentFieldsOf } from './environment-fields-of'
	4	+import { probeOf } from './probe-of'
	5	+import { sessionFieldsOf } from './session-fields-of'
	6	+
	7	+/**
	8	+ * Gathers and shapes what holds for the whole session, once: who the rows
	9	+ * are from, the session's fields, its `env` block and the remote hash.
	10	+ *
	11	+ * Nothing in it is a secret or a path: every field is the closed value the
	12	+ * CLI's own column holds.
	13	+ *
	14	+ * @param deps the calls on the nouns beneath
	15	+ * @param isInteractive whether a person is at the prompt
	16	+ * @returns the session's context for every batch after
	17	+ */
	18	+export async function contextOf(
	19	+ deps: TelemetryDeps,
	20	+ isInteractive: boolean,
	21	+): Promise<Context> {
	22	+ const probe = await probeOf(deps, isInteractive)
	23	+
	24	+ return {
	25	+ identity: probe.identity,
	26	+ session: sessionFieldsOf(probe.facts),
	27	+ environment: environmentFieldsOf(probe),
	28	+ remoteHash: probe.remoteHash,
	29	+ }
	30	+}

		@@ -1,0 +1,13 @@
	1	+/**
	2	+ * The row's `entrypoint` field: the variable as the CLI or its host set it
	3	+ * when spelled like one (a short lowercase token), else `other`.
	4	+ *
	5	+ * @param variable CLAUDE_CODE_ENTRYPOINT as read; undefined stays so
	6	+ * @returns the field, or undefined
	7	+ */
	8	+export function entrypointOf(variable: string \| undefined) {
	9	+ const isSpelled =
	10	+ variable === undefined \|\| /^[a-z][a-z0-9_-]{0,39}$/.test(variable)
	11	+
	12	+ return isSpelled ? variable : 'other'
	13	+}

		@@ -1,0 +1,3 @@
	1	+export * from './entrypoint-of.js'
	2	+
	3	+export * as default from '.'

		@@ -1,0 +1,41 @@
	1	+import type { GithubActionsFields } from './github-actions-fields'
	2	+
	3	+/**
	4	+ * The `env` block every row of the session carries, as the CLI's own rows
	5	+ * carry it, before its keys are spelled for the wire (Entries.wireOf).
	6	+ *
	7	+ * The machine, the terminal and shell, CI and GitHub Actions, the remote
	8	+ * container, the deployment. `isClaudeAiAuth` follows the credential each
	9	+ * batch is sent with and joins these then; an absent field is undefined.
	10	+ */
	11	+export type EnvironmentFields = {
	12	+ readonly platform: string
	13	+ readonly platformRaw: string
	14	+ readonly arch: string
	15	+ readonly terminal: string
	16	+ readonly shell: string
	17	+ readonly packageManagers: string
	18	+ readonly runtimes: string
	19	+ readonly isCi: boolean
	20	+ readonly isClaubbit: boolean
	21	+ readonly isGithubAction: boolean
	22	+ readonly isClaudeCodeAction: boolean
	23	+ readonly isClaudeCodeRemote: boolean
	24	+ readonly isLocalAgentMode: boolean
	25	+ readonly isConductor: boolean
	26	+ readonly deploymentEnvironment: string
	27	+ readonly remoteEnvironmentType: string \| undefined
	28	+ readonly claudeCodeContainerId: string \| undefined
	29	+ readonly claudeCodeRemoteSessionId: string \| undefined
	30	+ readonly tags: readonly string[] \| undefined
	31	+ readonly githubEventName: string \| undefined
	32	+ readonly githubActionsRunnerEnvironment: string \| undefined
	33	+ readonly githubActionsRunnerOs: string \| undefined
	34	+ readonly githubActionRef: string \| undefined
	35	+ readonly githubActionsMetadata: GithubActionsFields \| undefined
	36	+ readonly wslVersion: string \| undefined
	37	+ readonly linuxDistroId: string \| undefined
	38	+ readonly linuxDistroVersion: string \| undefined
	39	+ readonly linuxKernel: string \| undefined
	40	+ readonly vcs: string \| undefined
	41	+}

		@@ -1,0 +1,9 @@
	1	+/**
	2	+ * The GitHub Actions ids a row's `env` block carries when the session runs
	3	+ * in a workflow: the actor, the repository and its owner, by number.
	4	+ */
	5	+export type GithubActionsFields = {
	6	+ readonly actorId: string \| undefined
	7	+ readonly repositoryId: string \| undefined
	8	+ readonly repositoryOwnerId: string \| undefined
	9	+}

		@@ -1,0 +1,3 @@
	1	+export type * from './github-actions-fields.js'
	2	+
	3	+export * as default from '.'