> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry and privacy controls in Extension.js

> Review the Extension.js telemetry contract: what anonymous data is collected, what is never collected, and how to opt out of telemetry entirely.

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 per 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](https://posthog.com/) (open-source analytics) free tier

## What Extension.js collects

Per CLI run, at most one of:

| Event              | Sampled                                    | Properties                             |
| ------------------ | ------------------------------------------ | -------------------------------------- |
| `command_executed` | 20 % (configurable, see below)             | `command`, `success: true`, `version`  |
| `command_failed`   | 100 % (Extension.js always sends failures) | `command`, `success: false`, `version` |

Common context attached to every event: `os` (`darwin`/`linux`/`win32`), `arch`, `node_major`, `is_ci`. Nothing else.

## 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:

```bash theme={null}
# 1. Environment variable (wins over everything else)
EXTENSION_TELEMETRY_DISABLED=1 extension dev   # preferred
EXTENSION_TELEMETRY=0 extension dev            # back-compat, also honored

# 2. Per-run flag
extension dev --no-telemetry

# 3. Persistent consent file via the telemetry command
extension telemetry disable
extension telemetry enable
extension telemetry status    # show current state (default when no argument)
```

The consent file lives at `$XDG_CONFIG_HOME/extensionjs/telemetry/consent` (or the platform equivalent).

## Default behavior

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.

Continuous integration (CI) environments follow the same rules. Set `EXTENSION_TELEMETRY=0` in your CI environment to disable telemetry across the board.

## 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.

## 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](/docs/workflows/global-flags) for `--no-telemetry` and environment variable overrides.
* Use [build](/docs/commands/build) and [dev](/docs/commands/dev) for release and automation workflows.
* Read the repository-level [`TELEMETRY.md`](https://github.com/extension-js/extension.js/blob/main/TELEMETRY.md) contract for the exact event list.