feat: anonymous install, version and per-feature usage events (1.8.2)
What
Anonymous, opt-out usage events for the plugin, so launch posts can be measured: distinct installs per day or week, plugin and altimate-code versions, OS, and how often each panel and gate is used. They go through the altimate-code CLI's existing telemetry (altimate tool report-event). The plugin opens no network connection of its own.
Depends on AltimateAI/altimate-code#1775, which adds the two actions to tool report-event with a field allow-list. Until that release is installed, the CLI refuses them and nothing is sent or shown.
Design
Events. Two new actions for altimate tool report-event, sent by the Claude Code plugin:
| Event | When | Fields (the whole payload) |
|---|---|---|
plugin_session_start | each Claude Code session start | plugin_version, altimate_code_version (stamped by the CLI), host_os (macos, linux, windows, wsl, unknown; apart from the os other events carry as process.platform), install_id |
plugin_feature_used | a person opened a panel or command, or a gate held or allowed a command | plugin_version, install_id, feature, outcome |
featureis one oflineage,dbt_show,profile_ctes,scan_cost,comments,sql_graph,health,runs,to_model,cost_gate,health_push_gate.outcomeis one ofopened,failed(the panel could not open, or Claude Code could not place it),held,allowed.install_idis a random UUID the plugin creates on first run and keeps in its own Claude Code plugin store. It is not derived from the machine, the user or the project.
Allow-list. The CLI builds each event from these fields only, each checked against a fixed pattern or enum: plugin_version is a SemVer 2.0 version of up to 64 characters (any number of digits per part) (or unknown), install_id a lowercase v4 UUID, and os, feature and outcome enums. The plugin actions take no --session, and each action refuses a flag it does not take. Anything else, including any other flag, is refused with exit 1 and nothing is tracked. No project names, SQL, paths, column names or session text can reach the event.
Transport and anonymity. The events go through the CLI's existing telemetry (Telemetry.track to Azure Application Insights, flushed on exit). No new network host. They are unlinkable: unlike every other CLI event, they carry no account (user_id, tenant), no machine id, no project id, no session id and no launch_id, which the same process's first_launch row would share. ai.user.id is the plugin's install id, so they cannot be joined to a signed-in row. Only cli_version, client and source come from the envelope.
Opt-out. ALTIMATE_TELEMETRY_DISABLED (or OPENCODE_DISABLE_TELEMETRY) and telemetry.disabled in the altimate-code config turn it off in the CLI, as for every other event. The plugin also checks ALTIMATE_TELEMETRY_DISABLED / OPENCODE_DISABLE_TELEMETRY itself and then starts no CLI process and creates no install id.
Older CLI. An altimate-code without these actions exits 1 with a message on stderr. The plugin runs every event in the background (scheduled with later, never awaited by a hook), ignores the exit code and output, and shows nothing: no toast, no log line outside the debug log.
Where each event comes from
hooks/usage.ts(new) hassessionStarted($),featureUsed($, feature, outcome),openTracked($, feature, open),usageOff($)andinstallId($).- Each event is scheduled with
laterand never awaited. The helpers never throw into the hook that calls them. - No session id is sent.
- The plugin version is read from
${$.plugin.root}/.claude-plugin/plugin.json. It must be SemVer, as the CLI reads it, or it is sent asunknown. - The OS comes from
$.session.info().platform. - The install id is kept under
usage.installIdin$.store. One lookup is in flight per plugin load, so events sent together on a first run share it. After writing, the stored value is read back, so sessions starting at the same moment converge on one id. A stored value that is not a v4 UUID is replaced.
- Each event is scheduled with
integrations.tsx:sessionStarted($)insession.start.- Panels go through
openTracked:openedonce the pane opens, orfailedwhen$.ui.openthrows or answersisPlaced: false./lineageand the task summary's Open lineage button (lineage.tsxopenPane)./dbt-show(dbt-mods.tsx)./commentsand the band's Open button (features/comments.tsx)./runs(a list that cannot be read counts asfailed),/sql-graph,/profile-ctesand/to-model(its pane, once the mapping is in).- Panes the plugin opens on its own (the lineage pane following Claude, Query results after Claude's
dbt show) are not counted: these count a person's use.
/healthand/scan-costanswer in text, so they sendopenedwhen run.features/cost.tsx:cost_gate heldfor every refusal of the gate. That covers over the limit, an estimate still coming in, and a project that could not be read.cost_gate allowedis sent when/allow-scanallows the held command, and nothing when nothing is held.features/health.tsx: with "Project health blocks git push" on,health_push_gate heldorallowedfor eachgit pushthe gate decides. Nothing is sent with the gate off, or for a command that is not a push.task-impact.tsx: the existinglineage_reportevents now check the same opt-out, so no CLI is started for them under it.PRIVACY.mdhas a new "Plugin usage events" section listing every event and field. Its short version, the "What the plugin does" paragraph, the lineage report section and the change log are updated too. The plugin README's "Data handling" covers the events as well.- Version 1.8.2 in
plugin.jsonand.claude-plugin/marketplace.json, with a CHANGELOG entry.
Verification
claude plugin test plugins/altimate-code: 1225 pass, 1 fail at the head (earlier runs of this branch: 0 fail). The one failure isfeatures/runs.test.tsxāŗ "a dbt call that starts while another call reads its artifact". That test waits on two 20 ms real-time sleeps and fails on main too: 2 of 6 runs of main'sruns.test.tsxalone, and once in a full run of main's sources with this PR's tests. Every other test passes on each run; earlier full runs of this branch had 0 fail.- The new tests on main's sources: every test that expects an event fails, and so does the lineage opt-out test. The opt-out tests for the cost check and the push gate pass on main, since nothing is sent there.
- Review fixes: each regression test failed on the head before its fix: every cost hold, the comments band's Open, Open lineage,
/to-modelcounting only its pane, an unplaced pane counting asfailed, one install id for events sent together, no session id, and version and UUID rules. - Tests by acceptance item:
- One
plugin_session_startper session start, with the plugin version, the OS and a v4 install id that matches the store, and no session id (usage.test.tsx).- A second session sends the same id. An id kept from before is reused. A path, a version 0 UUID or a number in the store is replaced.
- Events sent while the first id is still being made share it.
- The OS and version cases:
wsl,1.8.2+build.7, and1.8.2-01āunknown.
- One
plugin_feature_usedper panel and command:/lineage,/dbt-show,/profile-ctes,/scan-cost,/comments,/sql-graph,/health,/runsand/to-modeleach send exactly one, with their feature name andopened.- A pane that throws, or that Claude Code could not place, sends
failed. A bad argument before any pane sends nothing. - Open lineage (
task-impact.test.tsx) and the comments band's Open each send one. The pane following Claude's edit sends none. - Cost gate (
cost.test.tsx): held over the limit, held while the estimate is still coming in,/allow-scanallowed,/scan-costopened, and nothing when nothing is held. - Push gate (
health.test.tsx): a push held,/healthopened, a push allowed, and nothing with the gate off.
- A pane that throws, or that Claude Code could not place, sends
- Opt-out:
ALTIMATE_TELEMETRY_DISABLEDset totrue,1orTRUE, orOPENCODE_DISABLE_TELEMETRY=1, starts no CLI for any event and makes no install id. The cost and health gates still hold under it and send nothing. The lineage report still opens and sends nolineage_report.falseand0leave usage on, as the CLI reads them. The CLI's own opt-out is proven end to end in AltimateAI/altimate-code#1775. - Payload allow-list: in a project at
/work/acme_secret_project, with a modelfct_orders, a columnsecret_columnand SQL passed to/dbt-show, every event's argv has only the allowed flags, each value matching its pattern. None contains the project, model, column, SQL, path or session id. On the CLI side, the events are sent without account, machine id, project or session, and are keyed to the install id (#1775). - Older CLI: an altimate-code that exits 1 with "the action must be one of ā¦" leaves the command's answer unchanged. There is no toast and nothing in the log outside debug. The same holds with no
altimateon PATH and analtimate-codewithoutreport-event. - Fire-and-forget: a CLI that never answers holds neither the session start nor
/runs.
- One
claude plugin validate --strict .passes. The env reads it lists areALTIMATE_TELEMETRY_DISABLED,OPENCODE_DISABLE_TELEMETRYandWSL_DISTRO_NAME.bash tests/*.sh: all 8 pass.- End to end with the CLI from #1775 and its telemetry pointed at a local sink: see that PR. The sink receives both events with exactly the allow-listed fields, and nothing when the opt-out is set.
š¤ Generated with Claude Code