# Telemetry

CodeGraph collects a small set of **anonymous usage statistics** — which commands and
tools get used, which languages get indexed, which agents drive usage — so we can tell
which of the 20+ languages and 8 agent integrations deserve the most work. This page is
the complete list of what is collected. If a field isn't on this page, it isn't collected;
the ingest endpoint enforces this list as an allowlist and is itself
[public, auditable code](telemetry-worker/) in this repository.

## Turning it off

Any of these works, permanently:

```bash
codegraph telemetry off        # stores your choice (and deletes any unsent data)
```

```bash
export CODEGRAPH_TELEMETRY=0   # per-shell / per-CI override
export DO_NOT_TRACK=1          # the cross-tool standard — always honored
```

`codegraph telemetry status` shows the current state, what decided it, and your machine ID.
The interactive installer (`codegraph install`) asks up front with a visible default-on
toggle and never re-asks. If you never saw the installer (e.g. `npx` straight into `init`),
a one-line notice is printed to stderr before the first time anything is sent.

Off means off: when disabled, CodeGraph records nothing, opens no connection to the
telemetry endpoint, and sends no "opted out" ping.

Separately from telemetry, the MCP server checks GitHub for a newer release in the
background (at most once a day) so it can tell you an update exists — it fetches a
version number and sends nothing about you or your machine. `DO_NOT_TRACK=1` disables
this check too; to turn off only the update check, use `CODEGRAPH_NO_UPDATE_CHECK=1`.

## What is collected

Every payload carries this envelope:

| field | example | notes |
|---|---|---|
| `machine_id` | `b3a8c1…` | random UUID minted on first send — derived from nothing |
| `codegraph_version` | `0.9.9` | |
| `os` / `arch` | `darwin` / `arm64` | platform identifiers only |
| `node_major` | `22` | major version only |
| `ci` | `false` | whether the `CI` env var was set |
| `schema_version` | `2` | bumped when this page changes (v2 dropped the `index` event's `sqlite_backend` field) |

And one of four events:

- **`install`** — when `codegraph install` configures agents: which agents
  (`["claude","cursor",…]`), global vs project-local, and whether it was a fresh install,
  an upgrade, or a re-run.
- **`index`** — when a full index completes: the **language names** present (e.g.
  `["typescript","go"]`), the file count as a **coarse bucket** (`<100`, `100-1k`,
  `1k-10k`, `10k+`), and the duration as a bucket (`<10s`, `10-60s`, `1-5m`, `5m+`).
- **`usage_rollup`** — one line per day per tool: the tool or CLI command **name** (e.g.
  `codegraph_explore`, `init`), how many times it ran, how many errored, and — for MCP
  tools — the connecting agent's name and version from the MCP handshake (e.g.
  `Claude Code 2.1`). The Claude Code prompt hook also counts its **gate decision**
  (fired fully, fired as a hint, or did nothing — fixed counter names like
  `prompt-hook-gate-medium-segment`); the prompt itself is never read, stored, or sent.
- **`uninstall`** — when `codegraph uninstall`/`uninit` runs: which agents were removed.

Usage is **aggregated locally into daily totals** before anything is sent — there is no
per-call event stream, and nothing is sent in real time.

### The browser viewer sends nothing

`codegraph ui` (the local viewer) has no telemetry of its own. The server it starts
makes no outbound connections at all, and the page in your browser talks only to that
server on `127.0.0.1`: nothing about the symbols you open, the searches you type, or the
path you walk leaves your machine, and none of it is recorded anywhere. The only thing
telemetry ever learns about the viewer is what it learns about every command: that a
command named `ui` was run, once, on a day, in the daily `usage_rollup` above. The
command never triggers a send of its own, and `codegraph telemetry off`,
`CODEGRAPH_TELEMETRY=0`, or `DO_NOT_TRACK=1` switches off even that count, as it does
everything else on this page.

## What is never collected

- **No source code.** No file paths, file names, directory names, repository names or
  URLs, symbol names, search queries, or anything else derived from the contents of an
  indexed project.
- **No IP addresses.** The ingest endpoint never reads, logs, or stores the client IP —
  and there is no analytics vendor downstream that could. No geolocation.
- **No fingerprinting.** The machine ID is a random UUID stored in
  `~/.codegraph/telemetry.json` — delete that file (or run `codegraph telemetry off`,
  then `on`) and the old ID is gone forever, with no way to reconnect it.
- **No personal data.** No usernames, hostnames, emails, or environment variables.

## How it travels

Events POST to `telemetry.getcodegraph.com` — a first-party endpoint whose complete
source lives in [`telemetry-worker/`](telemetry-worker/) in this repository. It validates
every event and property against the allowlist above (anything else is dropped), never
reads the client IP, and rate-limits per machine ID. Sends are fire-and-forget with a
short timeout: offline or air-gapped machines buffer a bounded local file (256 KB cap)
and never retry-loop, log errors, or slow a command down. Telemetry never adds latency to
MCP tool calls — recording is an in-memory counter.

## Where it is stored

Accepted events are written to **our own database on Cloudflare** (D1) and go nowhere
else. **No third-party analytics vendor receives any of this data**, because the ingest
endpoint makes no outbound requests at all — its source is the entire path your events
take, and there is nothing after it. This is a stronger guarantee than a promise not to
share: there is no second party to share with.

What is kept is checkable rather than asserted. The storage schema —
[`telemetry-worker/migrations/0001_init.sql`](telemetry-worker/migrations/0001_init.sql),
checked in beside the endpoint that writes it — is the complete list of what a row can
hold, with a comment on every column.

Individual events are **deleted after 90 days**. What outlives them is anonymous daily
totals: counts per day of things like operating system, version, and language, plus which
days each machine ID was active so returning-user numbers survive. No event details, and
still nothing that identifies a person or a codebase.

The engineering contract behind all of this — including the rule that schema changes must
update this page, the client, and the public endpoint in one PR — is in
[`docs/design/telemetry.md`](docs/design/telemetry.md).