---
title: Settings Search telemetry
---

# Settings Search telemetry

## What it is

**What it is.** A small record of how people use the search box in the Settings panel — what they
search for, which result they pick (and how far down the list it was), and whether they then change
a setting. It exists so the Settings search can be made to rank results better over time. A
read-only **"Settings Search"** tab in the Stats area shows the data collected on this device; when
telemetry is on, the same events are also sent to the app's anonymous fleet telemetry (the same
pipeline as crash/error reports), so ranking can be improved across all installs.

## Where to find it

### What you see (the UI)

- **Where the data comes from:** the search box at the top of **Settings** (gear icon → type a
  query like "dark mode" → a list of matching settings appears → you click one, or press Enter).
- **Where you read it back:** open the **Stats** virtual project (Omniscio sidebar group) → the
  **Settings Search** tab in the Stats tab strip. It shows three lists, all-time:
  - **Top searches** — the most-searched terms, by how often a result was picked.
  - **Buried picks** — for each query, the _average position_ of the result people picked plus how
    many times. A high average position means people kept scrolling past the top results to find
    what they wanted — the clearest "this should rank higher" signal, and the actionable fix-list.
  - **Fell back to AI** — searches where the normal keyword results came up empty and the user hit
    **"Ask AI"**. A direct signal that those queries have a ranking/keyword gap.
- On a fresh install the tab shows an empty state ("No settings searches yet.") until you search.
- A one-line note under the heading reads: **stored on this device; shared anonymously when
  telemetry is on**.

## How it behaves

### What gets recorded (and what doesn't)

Three kinds of event land in one local table:

1. **pick** — you picked a result. Records the query, which setting, its **0-based rank** in the
   shown list, how many results were shown, and whether the list was the normal keyword results
   (`local`) or the AI fallback (`ai`).
2. **ai_fallback** — you pressed "Ask AI" because keyword search found nothing. Records the query.
3. **action** — after a pick, you changed a setting **in that same section within ~60 seconds**
   (proof the search actually led somewhere). Records the changed setting and whether it was the
   exact one you picked. This also covers changing the **theme** ("dark mode"), which takes a
   different code path from normal settings.

Keystrokes are **not** logged — recording happens only when you pick a result or hit "Ask AI", not
on every character typed. The query text is the only free-text stored, capped at 200 characters.

### Privacy & safety

- **Local first, telemetry-gated upload.** The data is written to Omniscio's local SQLite database (the
  source of truth for the readout). When **telemetry is enabled** — the same setting that governs
  crash/error reporting — a background tail also ships the rows to the app's anonymous fleet
  telemetry (keyed on a random install id, the search text scrubbed before egress). Turn telemetry
  off and nothing uploads. No email/share path; the fleet tail is the only sink.
- **Bounded.** The log auto-trims on a 6-hour schedule — it keeps about a year of data, hard-capped
  at 100,000 rows, so it can't grow without limit.
- **Can't break search.** Recording is fire-and-forget: if writing an event ever fails, the search
  itself is completely unaffected (the error is swallowed, never surfaced).

### Important scope note

This feature **collects and displays** the data only. It does **not** change how the live Settings
search ranks results — that "auto re-rank from what people pick" step is intentionally deferred.
The idea is to look at the **Buried picks** list first and improve ranking deliberately, rather than
guess before there's real data.

## For agents

### Under the hood (for agents with repo access)

- **Table & queries:** `settings_search_events` (a ledger migration under `src/main/db/migrations/`)
  - `src/main/db/queries-settings-search-events.ts` (`recordSettingsSearchEvent`,
    `pruneSettingsSearchEvents`, `getSettingsSearchStats`).
- **IPC:** the `settings-search-analytics` domain — `:record` (fire-and-forget insert) and `:stats`
  (the readout) — handlers in `src/main/ipc/handlers-settings-search-analytics.ts`.
- **Recording (renderer):** `src/renderer/src/features/settings/settings-search-analytics.ts`
  (`recordSettingsSearchEvent` + the pure `buildSearchActionEvent`). The single pick recorder is
  `recordPick` in `useSettingsSearch.ts`; the "Ask AI" fallback is recorded in `handleAiSearch`; the
  follow-up action is recorded by `noteSettingInteraction` in `Settings.tsx` (fired from both the
  normal settings-change path and the theme-change path).
- **Readout UI:** `src/renderer/src/features/statistics/SettingsSearchTab.tsx` + the
  `fetchSettingsSearch` slice in `stores/stats-store.ts`.
- **Pruning:** wired into `runLocalLogPrune` in `src/main/services/local-log-pruner.ts`.
- **Fleet upload:** `runFleetSettingsSearchTail` in `src/main/services/fleet-telemetry-client.ts`
  (sibling of the error tail) ships new rows past the `fleetSettingsSearchCursor` config cursor via
  `writeFleetEvent('settings-search', …)`, gated on `getTelemetryEnabled()`, query scrubbed at
  egress; reads via `getSettingsSearchEventsAfter`.
- **Contract (invariants):** `.claude/memory/contracts/settings-search-analytics-contract.md`.

## Related

This page has no direct sibling in the library, so begin at [INDEX.md](INDEX.md), the library index, and look for the pages about Settings and about the Stats area that shows the collected data.