--- title: Coaching Tips (contextual hints and shortcut nudges) --- # Coaching Tips (contextual hints and shortcut nudges) ## What it is **Coaching Tips ship OFF.** Nothing is surfaced until you turn them on in Settings → AI Coach, and if you had them running before 26 August 2026 they were switched off for you once, automatically. The rest of this page describes what happens when you turn them on. **Coaching Tips** are small, context-aware nudges that Omniscio shows you when it notices you're doing something the hard way — like clicking the archive button five times in a row when **Ctrl+Shift+A** would be faster, or going seven days without trying voice input. Each tip appears as a dismissible **inbox card** with a title, a sentence or two of explanation, and (for tips that point at a setting) a button that jumps you there — it no longer interrupts you as a pop-up toast. They're deliberately low-frequency: a 45-minute cooldown between tips, max 3 tips per day, no tips in the first 5 minutes after launch, and each tip fires only once (unless you hit "Reset all"). Tips fall into five opt-in categories — **Shortcuts**, **Voice Commands**, **Productivity**, **Navigation**, and **Advanced Features** — and the whole system can be toggled off with one switch. **Shortcuts** tips never show on a phone or touch screen, where there's no physical keyboard to reach for — the other four categories still work everywhere. ## Where to find it Coaching lives in **Settings → AI Coach**, and nothing is surfaced until you switch it on there. That panel holds the master switch, the five category toggles, and the full catalog of tips with the state of each one; the tips themselves arrive in your **Inbox**, not over your work. ## How it behaves ### How to use it 1. **Turn them on first.** Settings → **AI Coach** → **Enable coaching tips**. Until you do, no tip ever fires and no coaching card is ever created. Turning them back on sticks — the one-time switch-off that ran on upgrade never runs again, so your choice survives every later update. 2. **Then let tips come to you.** Just use Omniscio normally. When you hit a trigger (e.g., clicking Archive ≥5 times, or having the app installed ≥7 days without ever using voice), a card lands in your **Inbox** rather than popping up over your work. Open it, use its button to jump to the relevant setting, **dismiss** it (archive), or **snooze** it like any inbox row. Because each tip fires only once, dismissing a card is effectively permanent — the rest of the coaching system stays on. To turn the whole system off, flip the master switch in Settings → AI Coach. 3. **See what's waiting.** Settings → **AI Coach** shows every tip in the catalog grouped by category, with a state per tip: **Ready** (will fire when triggered), **Learned** (you marked it done), **Dismissed** (hidden permanently), or **Snoozed** (hidden for 7 days). A summary at the top shows the counts. 4. **Mark tips as learned, snooze, or dismiss.** In the Coaching settings panel each tip has three buttons: the green **check** to mark it Learned (closed successfully), the amber **clock** to snooze for 7 days, and the gray **X** to dismiss permanently. A badge on the Settings menu shows how many "ready" tips are queued. 5. **Turn categories off.** The top of the Coaching panel has five category toggles — flip any off to silence that group. Example: you know every shortcut cold, so disable **Shortcuts** but leave **Advanced Features** on. Master switch is **Enable coaching tips** (off kills the whole system). 6. **Bring them all back.** Click **Reset all** at the bottom of the Coaching panel to clear every tip's state and the trigger event counters. On the next qualifying action, tips start firing again as if it were day one. ## For agents ### How it works `AppSettings.coachingEnabled` defaults to **false** in [/src/shared/types/settings/ai-features-settings.ts](/src/shared/types/settings/ai-features-settings.ts) — the single source the derived `DEFAULT_SETTINGS` is parsed from — so a fresh install never fires a tip. Because Omniscio persists the whole settings block and re-reads it without merging defaults, an existing install still had `coachingEnabled: true` on disk; the one-shot migrate-coaching-tips-forced-off.ts clears that persisted `true` once, guarded by an `=== true` check (so someone who had already opted out is untouched) and a `coachingTipsForcedOffMigrated` sentinel on the config root (so a later re-enable is never re-flipped). No persona re-enables it — `coachingEnabled` is deliberately absent from `PERSONA_DEFAULT_OVERRIDES`. Locked by [coaching-default-off.test.ts](/tests/unit/shared/coaching-default-off.test.ts) plus the migration's tests in [config-store-migrations.test.ts](/tests/integration/config-store-migrations.test.ts). Existing `coaching-tip:*` inbox cards are left in place — the change stops new ones, it does not sweep the inbox. The tip catalog is hardcoded in [/src/main/services/coaching-tip-catalog.ts](/src/main/services/coaching-tip-catalog.ts) — a TypeScript array of `TipDefinition` objects, each with an `id`, `title`, `message`, `category`, `priority`, a `trigger` (either `actionCount: { event, min }` or a time/neverUsed condition), and optional `actionLabel` + `settingsSection`. Triggers fire off counters in the `coaching_events` SQLite table and are evaluated two ways: synchronously after each recorded event, and by a 30-minute periodic checker in [/src/main/services/coaching-checker.ts](/src/main/services/coaching-checker.ts) for time-based tips. When a tip becomes eligible, Omniscio checks the cooldown (45 min, `COACHING_COOLDOWN_MS`), the daily cap (3 max, `COACHING_DAILY_CAP`), the 5-minute startup suppression, and the category/global toggles (`AppSettings.coachingEnabled` + `coachingCategories`) — all in `shouldShowTip`, unchanged. If it passes, `fireTip()` in [/src/main/services/coaching-service.ts](/src/main/services/coaching-service.ts) marks it shown (`markTipShown`, so it never fires again) and — for the normal `presentation: 'toast'` tips — creates a **persistent inbox card** via `raiseAgentAlert` with the stable dedupKey `coaching-tip:`, instead of the old `emitPush(IPC.COACHING_TIP_SHOW)` transient toast. The card's action button is a Settings deep-link resolved from the dedupKey through [/src/shared/alert-actions/coaching-tips.ts](/src/shared/alert-actions/coaching-tips.ts) (tips with no Settings target are classified `coaching-advisory` — a card with no button). Any future `presentation: 'spotlight'` tip still uses the `COACHING_TIP_SHOW` push, handled by [/src/renderer/src/hooks/useCoachingNudge.ts](/src/renderer/src/hooks/useCoachingNudge.ts). Because the card lives in the inbox, dismiss = archive and snooze rides the universal inbox-snooze table — no per-card "Don't show again" button is needed (the once-only `markTipShown` already makes a dismiss permanent). **Shortcuts**-category coaching cards are hidden from the mobile inbox by the projector [/src/renderer/src/stores/alert-inbox-items.ts](/src/renderer/src/stores/alert-inbox-items.ts) (a "use the keyboard shortcut" card is useless with no keyboard) — the same intent the old toast-time `getIsMobile()` guard carried; the coverage is locked by [tests/unit/lint/mobile-coaching-shortcut-suppression.test.ts](/tests/unit/lint/mobile-coaching-shortcut-suppression.test.ts). Tip state (shown/dismissed/snoozed/completed) still persists in `coaching_tip_state` — see [/src/main/db/queries-coaching.ts](/src/main/db/queries-coaching.ts) — and the Settings panel [/src/renderer/src/features/settings/CoachingSettings.tsx](/src/renderer/src/features/settings/CoachingSettings.tsx) + the Zustand store [/src/renderer/src/stores/coaching-store.ts](/src/renderer/src/stores/coaching-store.ts) manage it exactly as before. "Reset all" wipes both tables and the badge counter — still the only way to revive a permanently dismissed tip. ## Related Because a coaching tip arrives as an ordinary inbox card, the dismiss, snooze, and grouping rules it follows are on the [inbox alerts](inbox-alerts.md) page. The mirror image of this feature — teaching Claude new behaviours rather than teaching you Omniscio — is on the [use skills](use-skills.md) page. - [inbox-alerts.md](inbox-alerts.md) — coaching tips are now standard inbox cards (agent-sourced alerts) and follow the inbox's dismiss/snooze/grouping rules - [use-skills.md](use-skills.md) — skills teach Claude new behaviors; coaching teaches _you_ about Omniscio