--- title: Hotkey usage --- # Hotkey usage ## What it is **What it is.** A usage signal that records every time a keyboard shortcut is *pressed* AND every time you *click* a control that has a shortcut instead of pressing the key. So you can see which shortcuts are heavily used, which are nearly dead, and which you keep clicking past — the data behind deciding whether to drop a shortcut, ship it **unassigned by default**, or surface one you never reach for. Distinct from **Shortcut Efficiency** (see [shortcut-efficiency.md](shortcut-efficiency.md)), which measures mouse-vs-keyboard with a rough time-savings estimate for a **curated** set of ~21 button-backed actions. Hotkey Usage is the **universal** version: it records a raw press of **every** bound shortcut (so an unused one shows a low/zero count) and — the "could've used the hotkey but didn't" count — a **click** of every shortcut-backed control, so "you clicked this button 40 times and never pressed its key" shows up for *every* shortcut, not just the curated set. The two are separate features by design. ### What gets recorded One event per discrete keypress of a bound shortcut, tagged with: - **the action id** — the shortcut's internal name (e.g. `goToInbox`, `prevSession`, `add-child`), and - **the surface** — which keymap fired it: `app` (the main Settings → Keyboard Shortcuts list, including the reserved Ctrl+number nav), `gmail`, `diff`, `digest`, `mindmap`, `kms` (the notes-editor commands), `approval` (the inbox approval pane's Enter/X + pane keys), `inbox` (the inbox detail pane), `team-chat` (the Team Chat quick switcher), `terminal` (the terminal palette / find / new-session combos), or `browser` (the AI Browser panel's palette / MRU ring). The hardcoded (non-rebindable) surfaces record a stable internal name for the action rather than a rebindable shortcut id — still never the key text. Key-repeat holds don't inflate the count — holding a key records **one** press. Only the action id + surface are stored — never the key text, message content, or file paths. **Clicks (the "could've used the hotkey but didn't" count).** Separately, whenever you *click* a control that also has a keyboard shortcut, that's recorded too (tagged with the same action id). This is **universal** — it rides the invisible marker every hotkey button already carries (and the build fails if a hotkey button is ever missing one), so it covers every shortcut-backed control with no per-button setup. It only counts a genuine mouse click: a keyboard-triggered button press, a right/middle click, a touch tap, and a click blocked by Hotkey Training Mode are all ignored. It's also cheap — one shared click listener whose only work on a normal click is a single instant check. **Click depth + estimated time lost.** Each click also records HOW DEEP it was reached — a top-level **button** (1 step), inside an open **menu** (2 steps), or a nested **submenu** (3 steps) — derived from how many menu layers the clicked control sits in (`role="menu"` ancestors). A coarse shared cost table ([hotkey-click-depth.ts](../../src/shared/hotkey-click-depth.ts): button ≈1.5s · menu ≈3s · submenu ≈4.5s vs a hotkey ≈0.5s) turns that into an estimated "time lost vs the shortcut," shown per shortcut and as a headline total in the tab. Always labeled a **rough estimate** — solid for RANKING which shortcuts cost you the most, directional on the exact seconds. Rough edges (accepted): a menu without the standard tag, or an *inline* submenu (e.g. Move-to-project), undercounts by one tier. **Not recorded (deferred):** the notes-editor's plain rich-text formatting keys (Ctrl+B/I/U, lists, headings) — they're standard conventions you'd never unassign. And an *exactly-zero*-press list (the ranking surfaces least-used instead, which is the same actionable signal). ## Where to find it ### Where the data shows up 1. **In-app — Stats → Hotkey Usage tab.** Your own machine, immediate: a ranked list of your shortcuts (most-pressed first; the bottom rows are your drop/unassign candidates). Each row shows its **presses** and, when you've clicked its button instead, a **"clicked instead"** count plus an estimated **"≈ time lost vs the shortcut"** (from the click-depth cost model); a headline total sums the clicks AND the rough total time lost across all shortcuts. A shortcut you *only* ever click (0 presses) still appears — the clearest "you have a shortcut you never use" signal. Per-shortcut history is kept for ~90 days (the retention horizon), so the shared **"All Time"** range shows roughly that window — not your whole history; the tab labels this honestly. 2. **Cloud admin console — Hotkey Usage ranking.** Across all users (anonymized) and per signed-in user, in the Product Analytics view — **press counts only**. The click ("could've used the hotkey") count stays on your machine and is not sent to the fleet ranking (an easy follow-up if that changes). This populates only after the app ships, users press keys, and the daily reports accumulate over days–weeks — the in-app tab is the only immediate view. ## How it behaves ### Privacy The per-user data is invisible and rides the single existing telemetry consent (signed-in only, no separate opt-in) — the same pattern as per-user AI spend / activity. Only the closed-enum action id + surface name egress; they cannot carry personal content. ## For agents ### Where the code lives Trackers `trackHotkeyPress` (presses) + `trackHotkeyClick` (clicks) ([hotkey-press-tracker.ts](../../src/renderer/src/lib/hotkey-press-tracker.ts)), both recorded under the `keyboard_shortcut` feature (`action` = `triggered` vs `clicked`). Clicks are captured by one delegated listener, `useHotkeyClickTracker` ([useHotkeyClickTracker.ts](../../src/renderer/src/hooks/useHotkeyClickTracker.ts)), that reads the `data-hotkey-action` markers and tags each click's reach `depth` (its `clickDepthTier` helper). The depth enum + cost model + `estimateClickSecondsLost` are the shared, pure [hotkey-click-depth.ts](../../src/shared/hotkey-click-depth.ts). Queried by `getHotkeyUsageReport` (splits presses vs clicks, and clicks by depth) / `getHotkeyPressUsageSince` (presses-only egress) ([queries-feature-events.ts](../../src/main/db/queries-feature-events.ts)); presses shipped via the daily digest ([fleet-telemetry-client.ts](../../src/main/services/fleet-telemetry-client.ts)). Invariants + the full emit-tap map: [hotkey-usage-tracking-contract.md](../../.claude/memory/contracts/hotkey-usage-tracking-contract.md). ## Related [Shortcut Efficiency](shortcut-efficiency.md) is the curated companion reading — a rough time-savings estimate over a fixed set of about twenty shortcuts — while this page counts every press and click.