Inbox overview
The Inbox is the one list of everything waiting on you, gathered from every project and every channel. It sits at the top of the sidebar, and clearing an item there is the same as clearing it where it lives.
On this page
What it is
The Inbox is Omniscio's cross-project triage view — one place that surfaces every item across every project that needs your attention right now, regardless of which channel it came from. It sits at the very top of the projects sidebar with an amber inbox icon and an amber count badge showing how many items are waiting. Click it (or trigger your inbox keyboard shortcut) and the middle column switches from "this project's sessions" to "everything that needs you, grouped by source."
The Inbox is not a separate folder, mailbox, or queue — it's a live aggregation. Every item in it also exists in its home location (a session in its project, an SMS thread in the SMS virtual project, a cron approval in the queue), so triaging from the Inbox is the same as triaging from each home. The Inbox just collapses them into one list so you don't have to walk every project to find the four sessions that need replies, the two SMS threads with new messages, and the cron job pending approval.
Inbox attention scoped to a real project also appears in that project's "Needs You" section. Most inbox items are either session attention (already shown in their project) or virtual-source items (SMS, Briefings, cron) with no real-project home. But some non-session items are tied to a real project — a repo's PR-merge-queue nudge, a project's context-size (doc-token) alert, a project-scoped cron-job approval, a Nighty-Tidy summary, an agent alert (for example the Auto-lander's "branches landed" notice), or a held Bug-Intake "Review" card. Those surface in both places: the global Inbox and the owning project's Needs You sidebar section (with the project's amber attention badge counting them), on desktop and mobile — so opening the project shows what needs you there, not only in the Inbox. These notice rows behave exactly like the session rows beside them: Tab / J / K (and mobile tap) reach them in the order they're shown, and clicking or keyboard-activating one opens its detail in place in the project's main panel — you stay in the project, and closing it returns you there, not to the global Inbox. One shared membership source drives the row, the amber badge, and the project-view nav so they cannot drift; see project-needs-you-attention-contract.md.
The Inbox surfaces one kind of item per entry in the INBOX_SOURCE_INTEGRATIONS registry (inbox-sources.ts; INBOX_SOURCE_COUNT derives from it, so this page does not quote a number that would drift). The main ones are: sessions that delivered something for you (a finished answer, a question, a plan to approve, a permission request, a mission, a merge-conflict handback), today's Briefings summary if it hasn't been read, unread SMS conversations, unread Telegram conversations, pending cron-job approvals, pending automation-rule approvals, CLI Pending Actions queued by external AIs (settings PATCHes, session lifecycle, project deletes, project bug-intake toggles, away-mode rule changes — see cli-pending-actions.md), recipe approvals, recipe authoring approvals, and recipe runs that failed, stalled or stopped incomplete. Sessions that hit an error (API or auth), that you stopped, that gave up recovering ("Recovery failed"), or that are waiting out a rate limit are not in the Inbox — they wait in their project's Interrupted section and do not chime (errors and stops since 2026-08-21, rate-limit waits since 2026-08-14). PRD Stack plugin attention items render as a separate group below the unified list.
While items remain, the Inbox keeps one selected for you so you're never staring at a stale empty pane: finishing the current item drops you into the next, and an item that arrives while you're sitting on "All clear" opens on its own — a session, a text, an alert. Approvals are the deliberate exception: an approval that arrives while you're idle in the inbox waits as a row instead of opening on its own, so a background agent's approval can never take over your screen — you open it when you're ready. That protection covers the Inbox and every other screen; on the Approvals screen itself the opposite is what you want, so an approval that arrives while that screen is open with nothing selected opens in its reading pane (useApprovalsQueueAutoSelect, mounted by its sidebar), and answering one moves you to the next waiting approval — a row you closed with the pane's X is never re-opened, and an open approval is never replaced. (Opening the Inbox yourself reopens the item you were last viewing if it still exists, otherwise the newest item — approval or not (groups list oldest-first, so "newest" is the bottom row of a group) — and finishing the item before an approval still advances onto it — only a from-behind arrival is held back. See inbox-navigation-contract.md approvals-no-passive-auto-open.) If items remain but none is open (auto-select hasn't landed one yet), the reading pane prompts "Select an item" rather than falsely claiming all-clear. The "All clear" panel — the Omniscio orb resting on a soft round glow, the heading "ALL CLEAR" in the brand gradient with a thin line under it, and the subtext "No sessions need your attention right now" — appears only when the Inbox is genuinely empty (the count badge is 0). That's the goal state — empty inbox means triage is done.
Where to find it
At the very top of the projects sidebar, marked with an amber inbox icon and an amber badge counting what is waiting. Clicking it — or pressing your inbox keyboard shortcut — switches the middle column to the grouped list of everything needing you.
How it behaves
How to use it
- Open the Inbox. Click the amber Inbox entry at the top of the projects sidebar (above the divider that separates Inbox from your pinned and grouped projects). The icon is a mailbox glyph; the badge to its right shows the total count of pending items across every source. The middle column switches from per-project sessions to the unified inbox list, with
aria-label="Inbox, N needing attention"set for screen-reader callout. - Read the grouped list. Items are grouped by their source project — a real project's group header shows the project's color bar and icon plus the project name; virtual sources show a Lucide icon (alarm clock for CRON JOBS, smartphone for SMS, newspaper for BRIEFINGS) plus a tinted label. Every group header — real project or virtual source alike — also carries a parenthesised count of how many items sit in that group (for example Omniscio (12)), on desktop and mobile. Inside each group, items are sorted oldest-first so the longest-waiting items are easy to spot. Sources that share a name share one group: if two sources would both show a HELP DESK header (for example, replies to reports you filed, and the incoming questions an admin sees), they appear as one HELP DESK group with one combined count. Your own projects are never merged, even when two have the same name. Groups that are waiting on you come first: a group holding a session that needs you, a card asking for your answer, or an approval (including a Mission Control workflow approval) sits above groups that only hold information. The first-run welcome cards still lead, and the System section of Omniscio's own notices always sits last and starts folded. Once you open System it stays open until you fold it again. Group order itself is frozen so the list doesn't shuffle under your finger as new items arrive. A new group joins the end of its tier (waiting or not) rather than splicing into the middle. The order stays stable across visits: it changes only as you clear items, as new ones arrive, or when a group gains its first waiting item or loses its last one. It resets when you restart the app. Collapse groups to scan by product. A Collapse all / Expand all toggle folds the whole Inbox down to a list of product names, and every group header carries a small arrow (chevron) that folds that one group down to just its name and count — so you can shrink the Inbox, then open one product to see only its items. On both desktop and mobile the toggle sits in the Inbox header row itself (the same row as the "Inbox" title): on desktop it's an icon-only button beside the source-filter icon, with its "Collapse all"/"Expand all" label shown in the hover tooltip; on mobile it's the labeled toggle. On desktop it's hidden while Focus Mode is armed (the list is behind the focus overlay, so there's nothing to fold). Collapsing only hides the rows; it never changes what's in the Inbox or the order you navigate. The keyboard walk steps only through rows you can actually see — a folded group is skipped whole, so Tab / J / K can never land on a row that has nothing on screen to show for it. Folding is never undone for you: on desktop and mobile alike an explicit fold folds fully, including a group holding the item you have open (that item still shows in the reading pane on the right, so the open card is never stranded either way). Your collapsed/expanded choices are remembered across restarts and on your phone. Tapping a group name still jumps into that project as before — the arrow is the dedicated fold control.
- Click a row to act on it. A session row opens that session in the right pane so you can read the question, choose a plan option, grant or deny a permission, or reply. An SMS row opens the conversation viewer. A Briefings row opens today's briefing. An approval row (cron, automation, CLI Pending, recipe) opens an approval modal showing the action kind, the target, the JSON payload, and Approve / Reject buttons. All five approval kinds sit together in one "Approvals" section, and approving or rejecting one carries you to the next pending approval — never off into a project's sessions — until the queue is clear. Closing an approval (the X) without deciding doesn't lose it — the approval stays waiting in the Inbox and Omniscio drops you onto the next pending item so you can keep moving through the queue (close the last one and you land back on the list). The amber row colour signals "decision required" so you can scan and prioritize.
- Triage with keyboard. J / K walk forward and backward through the unified list across groups (the same shortcuts you use inside a project's session list). Shift+J / Shift+K extend a multi-selection so you can bulk-archive or bulk-snooze. Plain arrows clear any stale multi-selection so a follow-up bulk action operates on what you can see, not on a selection from twenty rows ago. However you move the selection — walking with J / K, or clearing items so the cursor jumps to the next one — the Inbox keeps the selected row in view: if it would land off-screen (for example above the fold after you clear an item near the top), the list scrolls just enough to reveal it, so you never lose your place. See
inbox-navigation-contract.mdactive-row-scrolled-into-view. - Items leave the Inbox automatically as you handle them. Reply to a session and its row disappears (the session is no longer in attention status). Read the briefing and its row clears. Approve a CLI pending action and the row vanishes. An SMS thread leaves the Inbox when you dispose of it — open it, tap Mark as read on the thread, archive it, or reply (in Omniscio, or straight from your phone, which Omniscio catches on its next background sync within ~30 seconds). Just opening a thread also takes it out of the Inbox — there is no "peek" — though the app moving its own cursor onto a thread does not count as opening it (see
sms-inbox-attention-contract.md). Snoozing or archiving from inside a session — or right-clicking the Briefings row and choosing Archive or Snooze, or pressing H on it — also drops it out of the Inbox immediately. Right-clicking a session row and choosing Clear from inbox removes just that row from the Inbox and its badge count without archiving the session: it keeps running, its scheduled wake-ups still fire, and it stays in its project's Needs You list (never in Live, where nobody looks) until you archive it or reply. If it needs you again later, it comes back to the Inbox by itself. Dismiss on a session row archives it. Seeneeds-you-visibility-contract.mda-cleared-row-returns-only-for-a-new-need. The badge count on the sidebar updates live via push events — no refresh. And a restart never leaves you a row you can't act on: an Allow/Deny tool-permission request lives inside the running agent's own process, so it cannot survive Omniscio closing. On the next launch that session moves out of the Inbox into Interrupted and — with auto-resume on — restarts and asks again with a live Allow/Deny card, instead of sitting in the Inbox forever with nothing to click. Every other kind of "needs you" (a question, a plan to approve, a finished turn) is written into the transcript, so it survives a restart and correctly stays in the Inbox. Seepermission-prompt-lifecycle-contract.mdP17. A message you have open never vanishes while you read it. If the agent starts working again while its message is on screen — most often an overseer that another agent just messaged — the conversation stays open until you move to another item; only then does it leave the Inbox. Archiving or pausing it still moves you on to the next item. Seeinbox-navigation-invariants-1-contract.mdactive-session-auto-eject. Opening a finished session counts as reading its report. Omniscio will not let an agent or an automatic clean-up file away a report you have not seen. Replying, choosing Mark as read, or simply opening the session and using the window while it is on screen all count — on your computer or your phone. A session the Inbox opened on its own while you were away does not count until you touch the window. Opening it does not take it out of the Inbox; only acting on it does. - Mobile uses the same view. On a mobile-width viewport (the phone web UI or a narrow window) the Inbox is just another row in the projects panel; tap it and the sessions panel slides in showing the same unified, grouped list. Swipe-left on a row archives the underlying session with an Undo toast. Clearing the item you're viewing slides you straight into the next one — or back to the list when the inbox empties — exactly as it does on desktop (one shared reconcile drives every way you clear, so a phone never gets dropped to the list instead of advancing; see
inbox-navigation-contract.mdmobile-panel-follows-advance). The Inbox is also the default landing tab on mobile because triage is the primary phone use case — see mobile-remote-access.md. - Keep a busy hub out of the Inbox. Right-click any hub in the projects sidebar — a project, or a built-in hub like Alarms, Briefings or Agent Alerts — and pick Show in Inbox (the default), Show in quiet lane (its items sit in one section below the Inbox with their own count and never add to the Inbox badge) or Hide from Inbox. The same choice lives in Settings → Inbox → Hubs in your Inbox, which also lists sections with no hub row of their own, such as System. The hub's own sidebar badge and its Needs You list are untouched, nothing is deleted, read or snoozed, and the choice follows you to your phone. If the Inbox is empty only because of hidden hubs or sources, it says so ("Sources hidden" with a Show all button) instead of celebrating inbox zero. See inbox-hubs.md.
Add an assigned item to Tasks
When an Inbox row is assigned work from Jira, Linear, Asana, ClickUp, Trello, Airtable, Monday.com or Notion, its detail pane has an Add to Tasks button next to Open in (it is hidden when Tasks is not available). One press creates a task from the item: the title (with the key, like "PROJ-12", for Jira and Linear), the due date when the source has one (Asana), and the item's web link attached as a link on the task. It shows "Added to Tasks" and the button changes to Added. Nothing is written back to the source: the item in Jira, Asana or the other tool stays exactly as it was, and finishing the task in Tasks does not close it there.
Scope and limits
- Driven from the app — and from the local command-line surface too. The unified channels layer that feeds this inbox — connecting a channel, applying its config, sending a message, marking an item read, or deleting an item, across the Slack, RSS, webhook, calendar, Drive and Sheets adapters — is driven from the desktop and mobile UI, and the same actions are also exposed headlessly on the local control surface (
127.0.0.1:19519) through a/channels/*route family: reads for the channel list, a conversation's messages, search, an adapter's config fields and the unread count, plus the mutating actions (send, mark read, apply config, connect, disconnect, delete one item). Those mutations apply immediately — unlike the Slack-specificPOST /slack/send, they do not wait in an approval queue. They are ordinary CLI-parity routes: the oldermessaging-clientdesktop-only exemption no longer covers the channel-layer actions (theCHANNELS_CONNECT/CHANNELS_CONFIG_APPLY/CHANNELS_SEND/CHANNELS_MARK_READ/CHANNELS_DELETE_ITEMfamily).
Related
- snooze-an-inbox-item.md — every row in the Inbox (every inbox kind) is snoozable via right-click → Snooze; one unified Snooze Palette, one expiry sweep, one gate helper, counts update live via
INBOX_SNOOZE_CHANGED - cli-pending-actions.md — how external-AI requests land in the inbox as approve/reject rows
- bulk-select-sidebar.md — Shift+J/K multi-select and bulk archive/snooze across inbox groups
- snooze-a-session.md — snoozing a session removes it from the inbox until the snooze expires
- archive-a-session.md — archiving from the inbox kills the CLI process and drops the row
- mobile-remote-access.md — the mobile/phone view defaults to the Inbox as the landing tab
- daily-digest.md — the Briefings (formerly Daily Digest) row that surfaces in the Inbox once a day
Last verified 2026-10-06