--- title: Empty-inbox discovery tip --- # Empty-inbox discovery tip ## What it is A one-time, gentle card in the Omniscio **Inbox** that tells you your inbox can be cleared by **archiving** the items you're done with. It appears at most once, ever — the first time your inbox has genuinely piled up and you haven't yet started using archiving. It carries an **"Archive this tip"** button that archives the card itself, so you see the gesture happen on the spot. It never archives anything else: the sessions it counted are still waiting on you, so clearing those stays your call. The Inbox fills with sessions that need your attention (Needs You / Error / Stalled), plus alerts and approvals. Archiving an item files it into the **Archived** view (still searchable) and removes it from the Inbox, so archiving is how you take the Inbox back toward zero. Many people don't realize this, so their Inbox grows without bound — this tip surfaces the capability at the moment it is useful, then gets out of the way. ## Where to find it It arrives in the **Inbox**, as a card, at most once ever — there is nothing to switch on. It only appears once your Inbox has piled up and you have not yet started archiving. ## How it behaves ### When it appears All of these must be true (checked once, at app startup): - Your **visible Inbox has ~15 or more items** waiting for attention — the same count the app badge shows, so snoozed, hidden, and behind-the-scenes items don't count. - You have **never archived a session** (zero archived items) — the signal that you may not know archiving exists. - You **haven't already seen** this tip (it shows at most once, ever). - The master **agent-alerts** setting is on (turning it off suppresses this and every other agent-raised card). If you already archive things, or your inbox is small, or you've seen it before, it never appears. Because it is gated on "zero archived items," the moment you archive anything it can never fire again. ### How to clear your inbox (what the tip points you to) - Press **Archive this tip** on the card itself — that is the same gesture, performed once so you can see it. - Open a session you're finished with and **archive** it, or select several and archive them together. - Archived sessions stay searchable in the **Archived** view, so nothing is lost. - Your Inbox drops back toward zero. See [archive-a-session.md](archive-a-session.md) for the full archiving mechanic. ### Turning it off There is no dedicated toggle — it is a one-time card that self-limits to a single appearance, so there is nothing to keep switching off. To suppress it (and every other agent-raised inbox card), turn off **agent alerts** in Settings → Notifications. Developers can also set the `AMC_DISABLE_EMPTY_INBOX_TIP` environment kill switch. ## For agents ### How it works (for agents) `maybeSurfaceEmptyInboxTip` (`src/main/services/app/empty-inbox-tip-alert.ts`) runs once from the startup-task registry. It gates, in order, on the `AMC_DISABLE_EMPTY_INBOX_TIP` env kill switch → Tips & Guidance → the one-shot `emptyInboxTipSeen` setting → the visible attention count (`countSessionsByStatus([...ATTENTION_STATUSES], true, { excludeHiddenTags: true })`, the SAME count the OS badge uses, so it matches what the user sees) reaching `EMPTY_INBOX_TIP_MIN_ATTENTION` (15) → `countArchivedSessions() === 0` (the archive-usage signal; no new counter or migration). On fire it raises ONE deduped inbox card via the canonical one-call `raiseAgentAlert` helper (which absorbs the dedup push and its own non-fatal catch) and sets `emptyInboxTipSeen` (the dedupKey is the idempotency backstop). The card is COPY-ONLY: it carries no primary-action button, because its copy names no manual step to take. It explains the archive gesture and stops there — it does NOT close with "This tip appears only once.", in any of the 35 shipped languages (a tip teaches the thing; it does not narrate its own lifecycle). The copy is pinned by `tests/unit/services/empty-inbox-tip-alert.test.ts` and the all-languages rule by `tests/unit/lint/tip-copy-and-action.test.ts`. Any error is swallowed; it can never break startup. Full invariants: `.claude/memory/contracts/empty-inbox-tip-contract.md`. ## Related - [archive-a-session.md](archive-a-session.md) — the archiving mechanic this tip points you to. - [snooze-an-inbox-item.md](snooze-an-inbox-item.md) — the other way to take a row out of the Inbox (temporarily). - [inbox-overview.md](inbox-overview.md) — how the Inbox groups and counts items.