Skip to main content
Extension.js collects a tiny amount of anonymous telemetry to understand which commands you run and which fail. It never collects source code, file paths, URLs, or project content. The privacy bar is strict by design:
  • Two events total: command_executed and command_failed
  • Three properties on every event: command, success, version
  • Opt-out with an environment variable, a CLI flag, or a persistent consent command
  • Extension.js samples and caps events to stay well inside the PostHog (open-source analytics) free tier

​
What Extension.js collects

Per CLI run, at most one of: A failure adds two more properties so a failure count reads as a cause rather than a number. code is one name from the CLI’s fixed error catalog, for example E_MANIFEST_NOT_FOUND, and exit_code is the process exit code as an integer from 0 to 255. code is checked against the catalog before it is sent, so a Node errno, an error message, or any value that is not a catalog name is dropped and the event reports E_INTERNAL instead. No error text ever travels. When a run offers to download a managed browser on a first run, the command’s own event carries the outcome, so an offer someone accepted can be told apart from one that ended the session. browser_install is one of offered, accepted, declined or failed, browser_install_browser names the managed browser, for example chrome, and browser_install_seconds is the whole number of seconds a download took. There is no separate install event, the counts stay on the two events above. The create command adds two more properties so a broken advertised starter shows up in its failure counts: template (the starter name as listed by extension create --help, or absent) and source (cli, or the surface that started the create, for example templates). template is checked against the published starter list before it is sent. A GitHub URL, a local folder path, or any other value that is not an advertised name is dropped rather than trimmed, so a private repository or a directory name never leaves the machine. The create command is also exempt from sampling, so template usage numbers stay accurate. Common context attached to every event: os (darwin/linux/win32), arch, node_major, is_ci, is_source_build. Nothing else. is_source_build is a single boolean answering “was this a registry install or a repository checkout”. It is computed from the shape of the install path (whether a node_modules-style segment sits above the CLI). The path itself is never read into the event, sent, or hashed.

​
Volume controls

Three independent controls limit how much data leaves the machine:
  • Sampling: Extension.js samples command_executed at 20 % by default. Override with EXTENSION_TELEMETRY_SAMPLE_RATE (0.0–1.0). Failures are never sampled.
  • Per-run cap: at most 3 events per CLI process. Override with EXTENSION_TELEMETRY_MAX_EVENTS.
  • Debounce (duplicate suppression): Extension.js drops duplicate (event, command, success) tuples within 60 s. Override with EXTENSION_TELEMETRY_DEBOUNCE_MS.

​
What Extension.js never collects

The Extension.js telemetry contract explicitly excludes:
  • Source code, manifest contents, HTML output, or package.json contents
  • Repo names, Git remotes, GitHub org/user names, branch names, commit SHAs, or preview URLs
  • Dependency lists, permission lists, or freeform project identifiers
  • Environment variable values, filesystem paths, or machine-local URLs
  • Stack traces, error messages, or free-text error names
  • IP addresses (Extension.js sets $ip to null on every payload)

​
Opt out

Three ways to disable telemetry, listed in precedence order:
The consent file lives at $XDG_CONFIG_HOME/extensionjs/telemetry/consent (or the platform equivalent). When that location is not writable, storage falls back in order: the platform cache directory, then a folder under the system temp directory, then ./.cache/extensionjs in the working directory.

​
Default behavior

In an interactive terminal, telemetry is opt-out. On the first run where none of the overrides above apply, Extension.js prints a one-line notice explaining how to disable it. It also records an enabled consent marker so the notice does not repeat.

​
CI is off by default

In CI with nothing attached to stdout (a CI marker set and no TTY), telemetry is off by default and reports source: ci. A stored enabled consent does not carry into a pipeline: consent recorded by a person at a keyboard cannot cover a pipeline that inherited that home directory, so the stored opt-in is demoted below the CI gate. A stored disabled is a refusal, and a refusal always wins, in CI and everywhere else. To send telemetry from a pipeline on purpose, set EXTENSION_TELEMETRY=1. That explicit machine-level opt-in sits above the CI gate.

​
Local audit log

Extension.js appends every event it considers sending (whether or not it actually ships) to events.jsonl next to the consent file. Inspect it any time. Delete it freely. The audit log stays bounded. At 1 MiB it rolls to a single events.jsonl.1 backup, replacing any previous backup. Override the cap with EXTENSION_TELEMETRY_AUDIT_MAX_BYTES. A file grossly over the cap (10 times or more) is dropped instead of kept. If the audit write itself fails, Extension.js disables all further sends for that run: an event that cannot be audited locally is not sent.

​
Best practices

  • Use EXTENSION_TELEMETRY_DISABLED=1 in CI when policy requires no telemetry.
  • Treat privacy regressions as product regressions.
  • Read the repository-level contract for the exact event list.

​
Next steps

  • Review Global flags for --no-telemetry and environment variable overrides.
  • Use build and dev for release and automation workflows.
  • Read the repository-level docs/TELEMETRY.md contract for the exact event list.