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), which measures mouse-vs-keyboard with a rough time-savings estimate for a curated set of 25 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: 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), both recorded under the keyboard_shortcut feature (action = triggered vs clicked). Clicks are captured by one delegated listener, useHotkeyClickTracker (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. Queried by getHotkeyUsageReport (splits presses vs clicks, and clicks by depth) / getHotkeyPressUsageSince (presses-only egress) (queries-feature-events.ts); presses shipped via the daily digest (fleet-telemetry-client.ts). Invariants + the full emit-tap map: hotkey-usage-tracking-contract.md.

Related

Shortcut Efficiency is the curated companion reading — a rough time-savings estimate over a fixed set of 25 shortcuts — while this page counts every press and click.