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 — 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 plus the migration's tests in 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 — 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 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 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:<id>, 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 (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. 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 (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. Tip state (shown/dismissed/snoozed/completed) still persists in coaching_tip_state — see /src/main/db/queries-coaching.ts — and the Settings panel /src/renderer/src/features/settings/CoachingSettings.tsx + the Zustand store /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 page. The mirror image of this feature — teaching Claude new behaviours rather than teaching you Omniscio — is on the use skills page.

• 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 — skills teach Claude new behaviors; coaching teaches you about Omniscio