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

• stats.md — the Stats area that shows the collected settings-search data.
• settings-reference.md — the Settings controls whose searches are being counted.
• settings-home.md — the screen the settings search runs over.