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
| 1 | /** |
| 2 | * The `$.telemetry` noun as every caller sees it: the one contract for the |
| 3 | * noun, its types exported here and the noun declared on `EngineInterface`. |
| 4 | * |
| 5 | * The telemetry mod adds the noun in the `engine.create` fold and checks its |
| 6 | * return against `EngineInterface['telemetry']`; its hooks import these types |
| 7 | * from this folder, a mod that calls the noun and a test that answers it read |
| 8 | * them by including it in their tsconfig, and the engine's repository imports |
| 9 | * the folder by path. Nothing here is imported, so it stands on its own. |
| 10 | */ |
| 11 | |
| 12 | /** |
| 13 | * A plugin's analytics, queued through `$.telemetry` and sent in batches. |
| 14 | * |
| 15 | * The telemetry mod adds the noun in the `engine.create` fold wherever the |
| 16 | * CLI seats it, which is every build whose own analytics are on, and serves |
| 17 | * the plugins built into the CLI alone: a call from an installed plugin |
| 18 | * rejects. Where the mod is off or absent there is no `$.telemetry`. |
| 19 | */ |
| 20 | export type Telemetry = { |
| 21 | /** |
| 22 | * Queues one event, `tengu_plugin_<event>`, as one first-party row, sent |
| 23 | * with the next batch; resolves once queued, rejects a malformed entry. |
| 24 | * |
| 25 | * The calling mod names itself in `event`; one already named `tengu_…` is |
| 26 | * sent as named. A value is a finite number, a boolean or a |
| 27 | * TelemetryChoice; free text is refused. One input, as every op on `$` |
| 28 | * takes. Whether a batch went out is a line in the debug log. |
| 29 | * |
| 30 | * @param entry the event's name, a snake_case token, and its properties by |
| 31 | * snake_case key |
| 32 | * @example |
| 33 | * await $.telemetry.log({ |
| 34 | * event: "suggest_learning_survey_answered", |
| 35 | * props: { |
| 36 | * answer: 2, |
| 37 | * page: { value: "ready", of: ["ready", "later"] }, |
| 38 | * }, |
| 39 | * }) |
| 40 | */ |
| 41 | log: (entry: TelemetryLogEntry) => Promise<void> |
| 42 | |
| 43 | /** |
| 44 | * Marks one use of a feature as the CLI's own feature events do, one |
| 45 | * `tengu_feature_<kind>` row queued for the next batch; resolves once |
| 46 | * queued, rejects a malformed entry. |
| 47 | * |
| 48 | * The row carries `feature_name`, `error_code` on sad or bad (`reason`, |
| 49 | * required there and refused on ok) and the entry's `props`, checked as |
| 50 | * `log`'s are; it joins the product-wide feature surface, so no prefix. |
| 51 | * |
| 52 | * @param entry the feature, how it went, why when not ok, and the row's |
| 53 | * properties by snake_case key |
| 54 | * @example |
| 55 | * await $.telemetry.mark({ feature: "learn_page", kind: "ok" }) |
| 56 | * await $.telemetry.mark({ |
| 57 | * feature: "learn_page", |
| 58 | * kind: "sad", |
| 59 | * reason: "blocked", |
| 60 | * }) |
| 61 | */ |
| 62 | mark: (entry: TelemetryMarkEntry) => Promise<void> |
| 63 | } |
| 64 | |
| 65 | /** |
| 66 | * What `$.telemetry.log` takes: the event's name after the prefix, and its |
| 67 | * properties by snake_case key. |
| 68 | */ |
| 69 | export type TelemetryLogEntry = { |
| 70 | event: string |
| 71 | props?: Readonly<Record<string, TelemetryProp>> |
| 72 | } |
| 73 | |
| 74 | /** |
| 75 | * What `$.telemetry.mark` takes: the feature, how it went, why when not |
| 76 | * ok, and the properties the row carries beside them by snake_case key. |
| 77 | */ |
| 78 | export type TelemetryMarkEntry = { |
| 79 | feature: string |
| 80 | kind: TelemetryMarkKind |
| 81 | reason?: string |
| 82 | props?: Readonly<Record<string, TelemetryProp>> |
| 83 | } |
| 84 | |
| 85 | /** |
| 86 | * How a feature went, as the CLI's own feature events count it. |
| 87 | * |
| 88 | * `ok`: used, the person got what they asked. `sad`: degraded, a fallback |
| 89 | * or a partial, the person still got something. `bad`: failed, the person |
| 90 | * got nothing. |
| 91 | */ |
| 92 | export type TelemetryMarkKind = 'ok' | 'sad' | 'bad' |
| 93 | |
| 94 | /** |
| 95 | * A property's value: a finite number, a boolean, or a TelemetryChoice; |
| 96 | * never free text. |
| 97 | */ |
| 98 | export type TelemetryProp = number | boolean | TelemetryChoice |
| 99 | |
| 100 | /** |
| 101 | * A string property: the value and the list it is chosen from, declared |
| 102 | * beside it, so no free text reaches the row. |
| 103 | * |
| 104 | * Every member of `of` is a lowercase token of letters, digits, `_` and |
| 105 | * `-`, which may start with a digit, at most 32 of them; `value` is one of |
| 106 | * them. |
| 107 | */ |
| 108 | export type TelemetryChoice = { value: string; of: readonly string[] } |
| 109 | |
| 110 | declare module 'claude-code' { |
| 111 | interface EngineInterface { |
| 112 | /** |
| 113 | * A built-in plugin's analytics, first-party rows sent in batches; |
| 114 | * present where the telemetry mod is seated, refused to installed plugins. |
| 115 | */ |
| 116 | telemetry: Telemetry |
| 117 | } |
| 118 | } |