Files

T

e699ee9686 feat(prompt-hook): graph-derived gate tier + confidence-tiered injection + gate telemetry (#1136 )

The keyword gate (#1126) can never know a repo's domain nouns. This adds
the graph-derived tier the design discussion converged on: symbol names
are split into prose segments at index time (name_segment_vocab, riding
the insertNode write path), and the hook verifies a prompt's plain words
against them — "the state machine des commandes" → OrderStateMachine, in
any language whose technical nouns are Latin script.

Confidence now decides HOW MUCH to inject, not just whether:
- HIGH (keyword, or index-verified code token): full explore injection,
  unchanged — the validated adoption lever.
- MEDIUM (segment matches only): a ~500-byte pointer naming the matching
  symbols; the AGENT writes the explore query. Never runs explore, so a
  fuzzy match can't inject 16KB of wrong-feature context.
- Silent otherwise, as before.

Precision is derived from the repo's own naming statistics plus measured
FP fixes: co-occurrence (≥2 words on one name) always qualifies; a single
word must be ≥5 chars, cluster across 2–25 names (singletons are prose
coincidence: "deploy to production" → matchesNonProductionDir), match a
multi-segment name, and not be an English function/filler word (the one
place a word list is honest: identifiers are English, so only English
prose collides). Every candidate is re-verified against nodes before
being surfaced — vocab rows are proposals, deletions leave orphans by
design, a full index rebuilds from scratch, and sync heals pre-upgrade
databases (batched + yielding; emptiness captured at sync ENTRY so the
sync's own writes can't mask the backfill).

Schema v7 migration is DDL-only (instant; none of the #1067 row-churn
hazards). Gate outcomes roll up as anonymous usage counters
(prompt-hook-gate-<outcome>, names only, never content) through the
existing telemetry pipeline — recall becomes measurable, and the counters
are the agreed kill-criterion data for ever revisiting a local classifier.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

2026-07-02 14:35:38 -05:00

4.5 KiB

Raw Blame History

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 in this repository.

Turning it off

Any of these works, permanently:

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

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.

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.

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 forwards the client IP, and IP discarding is enabled at the analytics backend on top of that. 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/ in this repository. It validates every event and property against the allowlist above (anything else is dropped), strips IPs, rate-limits, and forwards to a managed analytics store (PostHog, US region) as anonymous events. 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.

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.