Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(telemetry): count npm installs, so the funnel has a top (#273)

anirudhkumar-nanonetsa0ae727b2218
diff --git a/TELEMETRY.md b/TELEMETRY.md
index 8d00e542..dcb57d75 100644
--- a/TELEMETRY.md
+++ b/TELEMETRY.md
@@ -16,6 +16,12 @@ Nothing is ever sent from a command you run. Events are appended to a local file
and a detached background process posts them at most once a day, so no `graft
ask` ever waits on the network.
+The one exception is the `install` event below, which the npm postinstall hook
+records and hands to that same detached process immediately — an install that
+never runs a command would otherwise never reach a flush, and "installed and
+never used" is a number we need to see. `npm install` itself still waits on
+nothing: the child is detached and its output discarded.
+
## What is sent
Every event carries only these common properties:
@@ -34,7 +40,8 @@ The events:
| Event | Extra properties | When |
| --- | --- | --- |
-| `first_run` | — | Once, the first time graft runs on a machine |
+| `install` | `global` (`true` for `npm i -g`, `false` for a project dependency) | The npm postinstall hook runs — once per machine per version |
+| `first_run` | — | Once, the first time a graft command runs on a machine |
| `init_completed` | `agents` (the ids you selected, sorted), `consent` | `graft init` finishes |
| `build_completed` | `files_bucket`, `langs`, `mode` (`fast`/`deep`), `duration_bucket`, `incremental` | A build succeeds |
| `build_failed` | `stage`, `code` — both fixed enums | A build throws |
diff --git a/scripts/postinstall.mjs b/scripts/postinstall.mjs
index 221237d8..8d4422d6 100644
--- a/scripts/postinstall.mjs
+++ b/scripts/postinstall.mjs
@@ -1,9 +1,48 @@
-// Prints a one-line nudge after install. Never fails the install.
+// Prints a one-line nudge after install, and records the anonymous `install`
+// event. Never fails the install.
+import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Record the install, then hand the queue straight to a detached child.
+ *
+ * Sending here rather than letting the daily flush pick it up is the entire
+ * point of the event: the machine we most want to count is the one that installs
+ * graft and never runs a command, and that machine never reaches a flush. The
+ * child is detached with stdio ignored, so npm waits on no socket and an offline
+ * install looks like any other.
+ *
+ * Every gate still applies — a fork or a local build has no key, and CI,
+ * `DO_NOT_TRACK` and `graft telemetry disable` all close it. See TELEMETRY.md.
+ */
+async function recordInstall() {
+ // `dist/` is absent when this runs from a clone, where `prepare` builds AFTER
+ // postinstall. Nothing to record there, and a fork has no key regardless.
+ const entry = join(root, 'dist', 'telemetry', 'index.js');
+ const cli = join(root, 'dist', 'cli.js');
+ if (!existsSync(entry) || !existsSync(cli)) return;
+ const mod = await import(pathToFileURL(entry).href);
+ // A `dist/` from an older version has no such export. Absent, not broken.
+ if (typeof mod.trackInstallIfNew !== 'function') return;
+ // npm sets this for `npm i -g`; only its value 'true' means global.
+ mod.trackInstallIfNew({ global: process.env.npm_config_global === 'true' });
+ const child = spawn(process.execPath, [cli, '_telemetry-flush'], {
+ detached: true,
+ stdio: 'ignore',
+ });
+ child.unref();
+}
+
try {
if (process.env.CI) process.exit(0);
- const { existsSync } = await import('node:fs');
- const { join } = await import('node:path');
const dir = process.env.INIT_CWD || process.cwd();
+ // Its own catch: the nudge is the part a user sees, and a telemetry fault must
+ // not be able to silence it.
+ try { await recordInstall(); } catch { /* telemetry is never worth an error */ }
if (existsSync(join(dir, '.claude', 'helpers', 'graft-statusline.cjs'))) process.exit(0);
console.log('\n Graft installed. Run `npx graft init` to enable the Claude Code integration (statusline + hooks + auto-sync).\n');
} catch {
diff --git a/src/telemetry/contract.ts b/src/telemetry/contract.ts
index f62884d3..10663153 100644
--- a/src/telemetry/contract.ts
+++ b/src/telemetry/contract.ts
@@ -30,7 +30,16 @@
* centrally by `track()` and are deliberately not repeated per event.
*/
export const EVENTS: Record<string, ReadonlySet<string>> = {
- /** Once per machine, when the install id is first minted. The denominator. */
+ /** Once per machine per version, from the npm postinstall hook. The real
+ * denominator: a machine that installs graft and never runs a command emits
+ * this event and no other, so it is the only place the "installed, never
+ * used" leak is visible at all. Version-scoped rather than once-ever so an
+ * upgrade counts; distinct install ids still give unique machines.
+ * `global` separates `npm i -g graft` from a project dependency, which is
+ * roughly the difference between a person and a lockfile. */
+ install: new Set<string>(['global']),
+ /** Once per machine, the first time a command actually runs. Paired with
+ * `install`, the gap between the two is the top of the funnel. */
first_run: new Set<string>(),
/** `graft init` completed. Tells us which agents people actually wire, and
* how many decline telemetry at the picker. */
diff --git a/src/telemetry/identity.ts b/src/telemetry/identity.ts
index a77f515f..042284a9 100644
--- a/src/telemetry/identity.ts
+++ b/src/telemetry/identity.ts
@@ -31,6 +31,13 @@ export interface TelemetryState {
enabled?: boolean;
/** ISO stamp of the one-time first-run notice, so it prints exactly once. */
noticeShownAt?: string;
+ /** ISO stamp of the `first_run` event. Its own field rather than "did this
+ * call mint the install id", because the postinstall hook now mints the id
+ * before any command runs — see `trackFirstRunIfNew`. */
+ firstRunAt?: string;
+ /** The version the `install` event was last sent for, so an upgrade counts as
+ * an install and a repeated `npm install` of the same version does not. */
+ installedVersion?: string;
/** Epoch ms of the last flush ATTEMPT, mirroring `UpdateCache.checkedAt`. */
flushedAt?: number;
}
diff --git a/src/telemetry/index.ts b/src/telemetry/index.ts
index eab62bac..0880932c 100644
--- a/src/telemetry/index.ts
+++ b/src/telemetry/index.ts
@@ -8,7 +8,7 @@
*/
export { EVENTS, COMMON_KEYS, isTrackedCommand, errorCode, filesBucket, durationBucket, countBucket, savedTokensBucket, langsValue } from './contract.js';
export type { AgentHost, Surface, TrackedCommand, BuildStage, ErrorCode } from './contract.js';
-export { track, trackFirstRunIfNew, detectHost } from './track.js';
+export { track, trackFirstRunIfNew, trackInstallIfNew, detectHost } from './track.js';
export type { QueuedEvent, TrackContext } from './track.js';
export { telemetryOn, offReason, explainOff } from './gate.js';
export { maybeFlushInBackground, runFlush } from './flush.js';
diff --git a/src/telemetry/track.ts b/src/telemetry/track.ts
index f60a5a54..e57f8fb1 100644
--- a/src/telemetry/track.ts
+++ b/src/telemetry/track.ts
@@ -21,7 +21,7 @@ import { EVENTS } from './contract.js';
import type { AgentHost } from './contract.js';
import { enqueue } from './queue.js';
import { telemetryOn } from './gate.js';
-import { installId, repoId } from './identity.js';
+import { installId, patchState, readState, repoId } from './identity.js';
import { runningVersion } from '../upkeep.js';
/** One queued event, exactly as it will be sent. */
@@ -115,14 +115,41 @@ export function track(
}
/**
- * The `first_run` event, fired the once. Separate from `track` because it is the
- * only event whose trigger is "the id did not exist a moment ago", which only
- * `installId()` can know.
+ * The `first_run` event, fired the once. Separate from `track` because its
+ * trigger is a comparison against persisted state rather than anything a call
+ * site knows.
+ *
+ * Gated on `firstRunAt` and NOT on `installId().firstRun`, which is the whole
+ * reason this field exists: the npm postinstall hook mints the install id before
+ * any command runs, so "did this call mint the id" is false on the genuine first
+ * command and would have silenced this event permanently.
*/
export function trackFirstRunIfNew(ctx: TrackContext = {}): void {
try {
if (!telemetryOn(ctx.home, ctx.env)) return;
- if (!installId(ctx.home).firstRun) return;
+ if (readState(ctx.home)?.firstRunAt) return;
track('first_run', {}, ctx);
+ patchState({ firstRunAt: new Date().toISOString() }, ctx.home);
+ } catch { /* never */ }
+}
+
+/**
+ * The `install` event, fired from the npm postinstall hook.
+ *
+ * Once per machine per version: an upgrade is a real install and worth counting,
+ * a second `npm install` of a version already recorded is not. Unique machines
+ * are then distinct install ids, exactly as for every other event.
+ *
+ * Nothing here is an exception to the gates — a fork with no key, CI,
+ * `DO_NOT_TRACK` and `graft telemetry disable` all still close it. It is only a
+ * call site that happens to run outside a command.
+ */
+export function trackInstallIfNew(ctx: TrackContext & { global?: boolean } = {}): void {
+ try {
+ if (!telemetryOn(ctx.home, ctx.env)) return;
+ const version = runningVersion();
+ if (readState(ctx.home)?.installedVersion === version) return;
+ track('install', { global: String(ctx.global ?? false) }, ctx);
+ patchState({ installedVersion: version }, ctx.home);
} catch { /* never */ }
}
diff --git a/test/telemetry-contract.test.ts b/test/telemetry-contract.test.ts
index 423d3c79..a9c65200 100644
--- a/test/telemetry-contract.test.ts
+++ b/test/telemetry-contract.test.ts
@@ -73,9 +73,10 @@ test('every event carries the common properties, and no identifier beyond them',
assert.match(ev.distinct_id, /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
});
-test('the contract lists exactly the six documented events', () => {
+test('the contract lists exactly the seven documented events', () => {
assert.deepEqual(Object.keys(EVENTS).sort(), [
- 'build_completed', 'build_failed', 'first_run', 'init_completed', 'query', 'session_summary',
+ 'build_completed', 'build_failed', 'first_run', 'init_completed', 'install', 'query',
+ 'session_summary',
]);
});
diff --git a/test/telemetry-install.test.ts b/test/telemetry-install.test.ts
new file mode 100644
index 00000000..271e5b5d
--- /dev/null
+++ b/test/telemetry-install.test.ts
@@ -0,0 +1,75 @@
+/**
+ * The `install` event — the top of the funnel, and the one event recorded from
+ * outside a command.
+ *
+ * The regression these tests exist for is subtle and expensive: the postinstall
+ * hook mints the install id before any command runs, which used to be exactly
+ * the condition `first_run` fired on. Get it wrong and every install still
+ * counts while `first_run` silently drops to zero, so the funnel looks like
+ * nobody who installs graft ever runs it.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { patchState, readState } from '../src/telemetry/identity.js';
+import { peek } from '../src/telemetry/queue.js';
+import { trackFirstRunIfNew, trackInstallIfNew } from '../src/telemetry/track.js';
+import { tmpRepo } from './helpers.js';
+
+const OPEN: NodeJS.ProcessEnv = {};
+
+function sandbox(tag: string): string {
+ const home = tmpRepo(tag);
+ mkdirSync(join(home, '.graft'), { recursive: true });
+ process.env.GRAFT_POSTHOG_KEY = 'phc_test_key';
+ return home;
+}
+
+function names(home: string): string[] {
+ return peek(home).map((e) => (e as { event: string }).event);
+}
+
+test('install fires once per version, not once per npm install', () => {
+ const home = sandbox('tel-install-once');
+ trackInstallIfNew({ home, env: OPEN });
+ trackInstallIfNew({ home, env: OPEN });
+ assert.deepEqual(names(home), ['install']);
+});
+
+test('an upgrade counts as a new install', () => {
+ const home = sandbox('tel-install-upgrade');
+ trackInstallIfNew({ home, env: OPEN });
+ // What an upgrade looks like from here: the recorded version is no longer the
+ // running one.
+ assert.ok(readState(home)?.installedVersion);
+ patchState({ installedVersion: '0.0.1-old' }, home);
+ trackInstallIfNew({ home, env: OPEN });
+ assert.deepEqual(names(home), ['install', 'install']);
+});
+
+test('first_run still fires after the postinstall hook minted the install id', () => {
+ const home = sandbox('tel-install-then-first-run');
+ trackInstallIfNew({ home, env: OPEN });
+ trackFirstRunIfNew({ home, env: OPEN });
+ assert.deepEqual(names(home), ['install', 'first_run']);
+ // And still exactly once.
+ trackFirstRunIfNew({ home, env: OPEN });
+ assert.deepEqual(names(home), ['install', 'first_run']);
+});
+
+test('the global flag is the only property, and it is a string', () => {
+ const home = sandbox('tel-install-global');
+ trackInstallIfNew({ home, env: OPEN, global: true });
+ const ev = peek(home)[0] as { properties: Record<string, string> };
+ assert.equal(ev.properties.global, 'true');
+});
+
+test('every gate closes the install event', () => {
+ const off = sandbox('tel-install-gated');
+ trackInstallIfNew({ home: off, env: { DO_NOT_TRACK: '1' } });
+ assert.deepEqual(names(off), []);
+ const ci = sandbox('tel-install-ci');
+ trackInstallIfNew({ home: ci, env: { CI: 'true' } });
+ assert.deepEqual(names(ci), []);
+});