Supermail
A Superhuman-style email client - folders, compose, snooze, follow-ups, splits, flows, and filters on top of Gmail or IMAP - brought into Omniscio as a native sidebar feature and shipped from the same source as the standalone web client at mail.jls.dev. It is a React port of the vendored Supermail UI, not a webview or an embedded plugin.
On this page
What it is
A Superhuman-style email client - folders, compose, snooze, follow-ups, splits, flows, and filters
on top of Gmail or IMAP - brought into Omniscio as a native sidebar feature and shipped from the
same source as the standalone web client at mail.jls.dev. It is a React port of the
vendored Supermail UI, not a webview or an embedded plugin.
Status (2026-08-10): one-project Supermail. The native Omniscio surface is off by default behind
supermailEnabled; the standalone web client lives atmail.jls.devand uses the same backend.
Where to find it
How to turn it on
Settings → Connections → Email & Summaries → Supermail → Supermail (sidebar) (off by
default; setting supermailEnabled). While off, the sidebar row is hidden and nothing
Supermail-related loads.
A separate toggle, Show unread in Omniscio inbox (supermailInboxEnabled), controls whether
Supermail pushes unread items into Omniscio's unified inbox, gated by the master supermailEnabled
toggle.
How it behaves
What the user sees
- A "Supermail" row appears in the Omniscio sidebar (Omniscio built-ins group) with a mail icon; it shows only when enabled.
- Clicking it opens Supermail full-pane inside Omniscio, in one of two views: Mail (the mail
client) and Sessions (the Claude sessions started from Supermail — see "Start a session"
below). In the default unified header, Mail has a single Sessions button (a chat-bubble
icon with the live session count) at the right of the inbox toolbar; in Sessions view a
Mail | Sessionsswitch atop the sidebar session list comes back. The other header layouts (supermailHeaderLayout:current/unified/rail, defaultunified) keep the Omniscio-ownedMail | Sessionsstrip or left rail. - Pop it out into its own window — right-click the Supermail sidebar row → Open in new
window, or press the Supermail window global hotkey (default Ctrl+Alt+M) to open it in a
separate desktop window from anywhere, even in the background. The hotkey registers only while
Supermail is enabled and is rebindable or disableable in Settings → Keyboard Shortcuts
(System-wide). Under the hood this is the shared project-window pop-out
(
openProjectWindow('__supermail__')), so the mail-folder sidebar comes along when pinned. In the default overlay mode (sidebar hidden) the mail view fills the window, no empty column beside it. - One email in its own window — opened for you by an agent. Separate from the whole-client
pop-out, a single THREAD can pop into its own desktop window, so an agent can put an email in
front of you and you reply right there. Several can sit side by side, and Ctrl+W closes the one
you are looking at (Escape deliberately does not — it belongs to the mail UI, and closing on it
would discard a half-typed reply). Re-opening a thread that already has a window focuses it, and
at most 8 are open at once so an agent loop cannot carpet your screen. Agents open one with
POST /supermail/threads/<id>/open→ CLI control surface. Details: supermail-thread-window-contract.md. - Undo takes you back to the email. After you archive, trash or mark an email spam, Z or Ctrl+Z (Cmd+Z on Mac) puts it back in the list AND returns you to it: the full-page view navigates back, the reading pane re-opens, and from the list the cursor lands on its row. Undo is silent when the Undo toast is off (Settings → General → Confirmations), so the return to the email is the only sign it worked. Archive and trash always register their undo, even for mail opened from search or a link outside the loaded list.
- The first screen is Supermail's own sign-in, through the Supermail backend over the
agentmc://supermail/authdeep link (its primary scheme;omniscio://supermail/authis an alias). The app catches that deep link as it returns to the front (e.g. from your browser), so sign-in finishes in Omniscio instead of stranding you there. Omniscio has no user accounts of its own. The sign-in token stays on the computer and is never sent to a paired phone or web client.
Writing mail on the shared editor
Compose and reply run on the same editor the rest of Omniscio uses, so an outline behaves the same:
Enter continues a list at the same depth, Enter on an empty item steps out one level (and
leaves the list from the top), Tab nests an item with its children, Shift+Tab un-nests. A
list built in the body arrives in the delivered mail as a real nested <ul>/<li> — the body is
still the HTML the send path already carried, so nothing downstream changed.
The send chord is the one you already have (Ctrl/Cmd+Enter, remappable in Settings → Composing
→ send shortcuts); the editor never changes it. Bold, italic, underline, strikethrough, lists, quote,
indent/outdent and links (Ctrl/Cmd+K) all work, and a link opens the same Insert-link dialog.
Emoji shortcodes. Typing a :shortcode: (:smile:, :tada:, :+1:) becomes the emoji the
moment you type the closing colon, as on the previous editor. The lookup is the app's one emoji
table, so anything Omniscio renders as an emoji expands here too; an unknown pair (10:30:) and
anything inside a code block stay as typed. A pasted shortcode is left alone — expansion is for
what you type.
Going back. Settings → Composing → Use the shared compose editor restores the previous editor for compose and reply, live, no restart. The switch appears only inside Omniscio: the standalone web client at mail.jls.dev has no host editor, so it keeps the previous one.
Unsubscribe in one click (+ Unsubscribed folder)
Newsletters and marketing mail — any message carrying a List-Unsubscribe header — show a small
Unsubscribe button in the reading-view message header (ordinary mail shows nothing). One click:
- opens the sender's unsubscribe page (or
mailto:) in the browser; - saves a filter that moves FUTURE mail from that exact sender to a visible "Unsubscribed" folder — out of the inbox but browsable in the sidebar, never buried in All Mail and never deleted;
- moves any mail already in the inbox from that sender to that same folder.
A single humanized toast confirms all three, with Undo that truly restores it: the swept messages move back to your inbox and the just-created filter is removed. It is idempotent — unsubscribing again from the same sender never creates a duplicate filter. Signed out of the Supermail backend, the button still opens the unsubscribe page and says auto-filing needs your account (never a silent no-op). The filter is an ordinary Supermail filter — view or remove it in Settings → Inbox → Filters — and "Unsubscribed" is a normal sidebar label.
For a mailing list (a message carrying a List-Id), the sweep searches that list's own id and moves
only what it finds, so unsubscribing from one list never reads or moves the rest of your inbox. It
matches the sender's exact email address (a "From email" filter field), so news@cnn.com never
also catches breakingnews@cnn.com. It never deletes (move, not trash) and fails safe — if the
filter is ever confused, mail stays visible in your inbox, never silently hidden. A fully silent
one-click (no page opens) and a server-side domain block are out of scope (they need the separate
Supermail backend). One known limit: on a mailing list whose "From" is the person who posted, it
keys on that person — the visible Unsubscribed folder makes that catchable. Contract:
supermail-quick-unsubscribe-contract.md.
Start a session (Sessions tab + from a thread)
Supermail is a session host: you can start real Claude working sessions from it, like the Tasks and Agent Email panels.
- General — the Sessions tab (in the
Mail | Sessionssidebar strip) shows every session started from Supermail, with a "+ New session" button. Opening one swaps the main pane to its chat; the tab shows a live count badge and lists only your email sessions — not the general-project extras (Councils / Running Recipes). - With Ctrl+T — press Ctrl+T anywhere in Supermail (inbox, thread, compose box or Sessions tab) to start a new blank session in the Supermail host; it flips you to the Sessions tab so the new chat is visible. (Seeding a session from a specific email is "From a thread" below.)
- From a thread — with a conversation open, click "Start a session" in the reading-view header (top-right), or run "Start a session from this thread" from the command palette — both do the same. A small dialog opens with an optional first instruction (e.g. "Draft a reply" — or blank) and a Start button. Starting spawns a session seeded with the WHOLE thread (every message) as context. The thread rides along as untrusted text (email is attacker-controlled), treated as context to act on, never as instructions to obey. The first message is your instruction, then an About this item note the app adds (the thread's id and how to work with it), then the thread; with no instruction the session opens waiting, and the note and thread ride your first message. (A session-type picker appears only when more than one type is available; today there's just one, so the dialog stays this simple.)
- Back to a session, from the email — once you've started session(s) from a thread, its emails show a "N session" chip in the reading-view header; click it to jump to the newest session (the Sessions tab still lists them all). The chip shows only on threads that spawned a session.
Sessions run in a managed Supermail workspace (nothing touches your real repos unless you tell the session to). Output shows in the session view — nothing is posted back into your mailbox. Gated by the same Supermail toggle; there is no separate switch. For agents, the mechanics + invariants live in supermail-start-session-contract.md.
Create Task (send an email to Tasks)
With Tasks on, the triage bar's Create Task action sends the email you are reading to Tasks' Caught view and shows "Sent to Caught in Tasks" (or "Couldn't add this email to Tasks"). The subject becomes the task, the sender shows as "from sender", and nothing becomes a task until you keep it; on keep the email text is attached to the task as an Email note. On an older host without the bridge call, the button is simply hidden. See tasks-v2-part-3.md.
Reading mail through your Omniscio Google connection (shared grant)
By default, Supermail reads mail through your Omniscio Google connection — if you already
connected Google to Omniscio in Settings, you are never asked to sign into Google a SECOND time
inside Supermail. The toggle Use Omniscio's Google connection for mail
(supermailUseAmcGmail, default ON since 2026-08-14 — unified sign-in) controls this: ON and
Google connected in Omniscio Settings means Supermail reads your inbox through Omniscio's ONE
shared Google grant — the same one that backs Gmail / Calendar / Drive / Sheets / Docs. No second
consent screen and no new Google permission (the shared grant covers Gmail). Turn it OFF to use
Supermail's OWN separate backend sign-in. The default is self-targeting: it takes effect only
once Google is connected in Omniscio, so an unconnected user stays on Supermail's own sign-in — no
one is stranded, and one toggle flip reverts it.
- The Google token never leaves the main process. Supermail's mail calls are relayed through
Main (
gmail:api-request), which holds the token and is hard-bound to your own Gmail (gmail.googleapis.com/.../users/me); only mail DATA crosses to the renderer. - Reversible. Turning it OFF returns to Supermail's own sign-in, and it auto-falls-back (to Supermail's backend / demo path) whenever the shared grant is not connected or Supermail runs outside the Omniscio desktop app — so it never leaves a dead inbox; with no other session, Supermail shows its own sign-in screen.
- An expired Google sign-in says so, with a one-click fix. When the shared sign-in has EXPIRED
(not merely never connected), Supermail's sign-in screen says "Your Google sign-in has
expired" and, on the computer, offers Reconnect Google — the reconnect Omniscio's own Gmail
panel runs — bringing you straight back to your inbox. On a phone it says to reconnect on your
computer, because Google's sign-in opens a browser there. A failing background label refresh in
the meantime just keeps the labels you have (no longer reported as a crash). Invariant:
an-expired-grant-offers-reconnect-google. - A sync that stops, or never starts, is reported. A mailbox that has gone two hours without a successful sync raises a "SuperMail has stopped refreshing" card naming the account. A connection whose first sync can never complete — a missing Gmail permission, the Gmail API switched off on the Google project, or an outage during the first load — would otherwise leave an empty Supermail with nothing said, so two hours after a connected mailbox was first seen waiting for a successful sync, a "SuperMail hasn't loaded your mail yet" card appears instead. Both cards carry the same one-click Reconnect Gmail fix and clear the moment a sync succeeds; switching Supermail off forgets the waiting clock, so switching it back on starts a fresh two hours.
More than one Gmail account (normal mode)
With Use Omniscio's Google connection for mail on, you can add a second, third, … Gmail account
inside Supermail. Open the account switcher (the account row at the top of the nav, or Switch
Account in the command palette) and choose Add account → Google, then sign in to the other
account in your browser. It appears in the switcher, and Alt+1 … Alt+9 jump between accounts.
Each account is genuinely separate: its own Google consent and refresh token (held by Omniscio's main process, never the window), its own local mailbox copy, labels and drafts, and its own AI results and Plain Speak daily budget. An account can be reconnected on its own if its Google sign-in expires, and Remove account (in the account menu) asks Google to revoke it and deletes that account's local copy.
Your Omniscio Google connection is never re-pointed: Calendar, Drive, the Gmail automations and Omniscio's own Gmail panel keep the account they always did, whichever account Supermail shows. So the main account cannot be removed from Supermail; disconnecting it stays a Settings → Google action. Full invariants: supermail-multi-account-normal-mode-contract.md.
- A send that needs a Google reconnect fails LOUDLY, never silently. If a send (or other write)
can't authorize because the shared grant went stale or lacks the send scope, a persistent
"can't send email — reconnect Google" card appears in your inbox with a one-click Reconnect
Gmail button (the Google Account settings card gains one too), and the reply surfaces an
actionable "reconnect your Google account in Settings" toast that restores your draft — never
a silently-lost reply. The toast stays until a send can authorize; reconnecting in Settings
restores sending with no restart and nothing to retype. It does NOT tear the read session down
(the inbox works while you re-consent), clears itself the moment a send succeeds, and an ordinary
network / rate-limit / 5xx hiccup never raises it. See inbox-alerts.md.
Invariant:
.claude/memory/contracts/supermail-resilience-contract.md(the resilience bullet). - Scope. Covers the core inbox (list, read, search, archive, mark-read, label, send — including
choosing which Gmail "Send mail as" identity a message goes out from via the composer's
From picker, read from Gmail settings through the relay and falling back to your primary
address if the connection predates the needed permission (reconnect via the sidebar's
Reconnect) — and snooze), plus viewing and downloading received attachments (inline images
render in the body, image attachments show a thumbnail, downloads save the real file; bytes come
from Gmail via the relay) and, via the local mirror, background sync, exact per-lane split-counts,
offline reading and local search. Backend-only extras (multiple mailboxes, drafts, scheduled send,
attachments-on-send) stay on Supermail's backend and are degraded here. Engineering
invariants:
.claude/memory/contracts/supermail-shared-gmail-grant-contract.md. - Works on your phone (mobile web). With this toggle ON your inbox loads and is fully usable from the Omniscio mobile web UI (over Tailscale) — read, archive, reply and send. It reads the desktop's synced mirror and signs in off the shared grant, so no mailbox key is sent to the phone. A paired phone is bounded to those triage actions: it CANNOT permanently delete mail or change Gmail forwarding/filters (desktop-only, refused by a remote allowlist), and only your approved, signed-in device can reach it. See invariant 4 of the shared-grant contract and On your phone below.
- A reply stays in its conversation. In this mode a reply (and a filter auto-reply) lands
inside the thread it answers, for you and the recipient: on Send, Supermail looks up the newest
real message in the thread and sends with Gmail's thread link plus the standard reply headers,
and the composer stays open until that lookup finishes, so closing the app then never loses your
draft. If it can't look the thread up, the reply is not sent: your draft stays open with an
error, so a reply never goes out as a new conversation. Invariant:
a-reply-stays-in-its-conversation. - Full inbox, not just the first page. The shared-grant connector pages the inbox with Gmail's
own
nextPageTokencursor (getThreadsPageinshared/gmail-api/gmail-api.ts), so the list loads your WHOLE inbox as you scroll rather than a single ~25-thread page. Each listed thread still costs athreads.get, though those list reads now ask for metadata only and are cached per row; the local mirror (instant cold-load, offline reading, background sync, local search, exact counts) is the next bullet. Split-tab counts are exact over the local mirror — tallied from the whole local copy, not just the ~one loaded page (Gmail can't cheaply count arbitrary custom lanes, so the mirror does it), falling back to the loaded-page estimate only before the copy fills. - Local mailbox mirror (instant load + offline + always-on background sync). On this path the
inbox reads from a local per-account copy of your mailbox kept in the app's main process (a
standalone SQLite file), so it paints instantly and works offline — falling back to the live Gmail
connection when the copy is cold (never a dead inbox). Main owns the account (the renderer never
names it), the copy is wiped when you sign out of Google (it holds your mail), and the initial
fill runs low-priority and backs off under load. A background sync engine keeps the copy fresh
even when the Supermail panel is closed — a light ~5-minute check pulling only what changed via
Gmail's
history.listfrom a saved bookmark, applying new/removed mail and self-healing if the bookmark expires; it trims (never fully stops) under machine load and never triggers the big initial download. A background check that lands new mail wakes the on-screen inbox with a payload-free nudge that re-fires its normal refresh. Changes made in Gmail or Superhuman itself — archive, star, mark-read — surface in seconds, not minutes: besides the ~5-minute check, the copy syncs when you open or switch to Supermail, when the app regains focus, and on a ~60-second loop while you watch it side-by-side with your browser. The open inbox also re-reads the local copy about every 30 seconds, so an email archived, starred or marked read elsewhere disappears from the list and the tab counts follow, even if you never click into Supermail (it pauses while Supermail is hidden and reads only the local copy). Every path is coalesced (single-flight + a short throttle) and self-gates when the mirror isn't in use. When Supermail is enabled, the panel and this local copy are warmed a few seconds after launch, so the first open appears instantly with fresh mail (shared-Google path with an account connected only; off when Supermail is disabled or "keep panels loaded" is off). Off-switches:AMC_DISABLE_SUPERMAIL_MIRROR_BACKFILL(the initial fill) +AMC_DISABLE_SUPERMAIL_MIRROR_SYNC(the background sync) +AMC_DISABLE_SUPERMAIL_MIRROR_BODY_BACKFILL(offline-body caching) +AMC_DISABLE_SUPERMAIL_MIRROR_SEARCH_INDEX(the local search index). It layers on: instant thread open + offline message bodies — a thread paints its body instantly from the local copy (no more ~0.25–0.5s blank), then quietly upgrades to the full live thread with attachments / cc / bcc; cached bodies let a thread open with no connection at all, and the visible inbox rows are preloaded (an uncached body opens the old way); local search — subject / sender / body full-text search AND the common operators (from:/to:/subject:/is:unread/is:starred) answered instantly, falling back to a live Gmail search only for operators it cannot evaluate (e.g.has:attachment, date ranges, other folders), Gmail's own-address placeholder (from:me/to:me— the local copy would match any sender whose text merely contains the letters "me"), a negated operator, or a chosen "Search all mail"; and exact per-lane counts over the whole copy. Like the fill and sync, body-caching and search-indexing are paced, back off under machine load, and are individually off-switchable. Invariants:.claude/memory/contracts/supermail-local-mirror-contract.md.
On your phone
Supermail on the Omniscio phone app behaves like a phone mail app — one screen at a time, every action a tap away. It drives your computer's Supermail, so the computer must be on and Supermail connected there (shared-grant toggle above ON).
- Open it from the phone's hubs list — it lands on your inbox.
- Read: inbox rows show the sender, subject and a preview on their own lines; tap a row and the email opens full-screen. The side-by-side reading pane never squeezes onto a phone (your desktop reading-pane setting is untouched).
- Write and search: a floating Compose button and a Search icon in the inbox header — the
tap twins of the
cand/keys. - Act on an email: the bottom bar keeps one row of finger-sized actions; the rest sit under More. The subject at the top is never covered.
- Back: the phone's Back gesture (or the in-app back arrow) returns from an email to the list you opened it from; Back from the inbox leaves Supermail.
- Custom inboxes (Split Inbox): your own lanes appear in a drop-down at the top of the inbox, in the computer's order. You can create, rename, reorder and delete them from the phone; a change on either device shows on the other without a reload. Phone lane counts come from the mail already loaded, with no way to load more into the count — so a lane can read lower than the desktop's exact tally, even after the list pages in more.
- Fresh mail: opening Supermail on the phone asks the computer to pull the latest mail, and the phone refreshes itself when the computer syncs or a custom inbox changes.
- Not on the phone (hidden; use the computer): the Snoozed folder list, filter rules, video summaries, Archive Insights and the Mail | Sessions switch (Supermail-started sessions still appear in the phone's own session lists).
- Not connected yet? The phone never shows a sign-in form — signing in on the phone would
change the computer's Supermail account. The phone can only read mail through Omniscio's Google
connection, so it names the ONE thing the computer is missing, then you open Supermail on the
phone again:
- Turn on phone access on your computer — the computer's Supermail uses its own sign-in (the Use Omniscio's Google connection for mail toggle is OFF). This is why Supermail can work on the computer and not on the phone. Turn the toggle on.
- Reconnect Google on your computer — the Google sign-in Omniscio holds has expired.
- Connect Google on your computer — the toggle is on, but no Google account is connected in Omniscio Settings.
- Set up Supermail on your computer — shown only when Supermail runs outside Omniscio.
- A narrow window on your computer (such as an email opened in its own window) is still the desktop app — "phone" means the paired phone itself.
Invariants: .claude/memory/contracts/supermail-mobile-contract.md.
New-mail notifications (which producer runs, and why it varies)
When mail arrives, the desktop alert comes from one of two producers, chosen by your sign-in — never both:
- Reading through your Omniscio Google connection (the default,
supermailUseAmcGmailON) — the alert comes from your local copy of the mailbox, already kept fresh by the background sync above. No Supermail backend session is involved anywhere in the path. - Supermail's own sign-in (the toggle OFF) — the alert comes from Supermail's backend notification stream, exactly as before: same backend stream, same session under it. Nothing about this path changed. Your mail is not kept locally in that mode, so there is nothing local to notify from.
Why the split exists. The backend stream is keyed to a session token with a 30-day life that nothing renews — it cannot be renewed without a Google consent screen, so no automation can do it. When it lapsed, mail kept syncing perfectly while notifications alone silently stopped, behind a repeating "notifications are disconnected" alert. Reading from the local copy removes that session from the notification path entirely, so nothing is left to expire. In this mode the backend stream stands down and any standing "disconnected" alert is cleared, because it is no longer true.
Behaviour you can expect:
- Freshness. Alerts arrive on the next sync. The sync runs every 5 minutes, speeding up to about every 60 seconds while you are actively at the computer (backing off when the machine is idle or busy). Settings → Email & Summaries → Notifications — desktop on/off, the Important-only filter, and quiet hours — apply to these alerts.
- Unread mail from other people only. A thread you have already read, and a note you mail yourself, never alert — the backend stream's rule.
- One alert per conversation. Several new replies in one thread produce a single alert.
- A big backlog can never flood you. A burst alerts on at most a handful of the newest threads; the rest collapse into one silent "N more new emails" summary.
- It is impossible to double-alert. A mail pass overlapping a previous one (the sync resumes from its boundary point after a backlog) cannot re-alert it.
- The "Emails in inbox" option keeps working here — each new email the option selects still creates its dismissible Omniscio inbox card with an inline reply box. That option is chosen separately from the alert rules above: turning the alerts off, or quiet hours, never stops the cards. On this unified path "Important only" is honoured, because the local mirror carries the mail provider's IMPORTANT label.
One honest limitation: the "VIP only" filter currently yields no alerts, here and on the backend stream alike — the backend reports VIP as always-false, so the setting is inert today. Engineering invariants: supermail-notification-delivery-contract.md.
Superhuman snooze-reminders are filtered out
If you also use Superhuman, its snooze brings a thread back by mailing a "Reminder" note from
reminder@superhuman.com ("This is a reminder from Superhuman Mail. Do not reply to this email.").
Supermail treats that reminder as noise — exactly like its own snooze-return marker: it never
becomes the inbox row's sender/preview and never shows inside the opened thread, so the row keeps
the real person and message. The conversation stays in the inbox (real date, no artificial
bump); only the reminder is hidden. Detection is by sender, scoped to the snooze reminder (a
one-off sharing@superhuman.com note is a different Superhuman feature and is left alone). Existing
reminder-topped threads clean up on the mirror's next self-healing rebuild. Engineering invariants:
the local-mirror contract (thread-we-snoozed-never-evicted) in
supermail-local-mirror-contract.md.
AI Filtering (the AI-powered sibling)
Alongside the rule-based filters on part 3, an in-development AI Filtering feature lets AI triage each new email against a plain-language instruction (keep / archive / label / mark-read / star — never trash): preview-first, off by default, cost-capped, mirroring the Inbox Pilot's evaluator for email. Full details: supermail-ai-filtering.md.
Split Inbox (focused lanes, with an on/off switch)
Supermail can divide the inbox into split lanes (Primary, Other, VIP, Team, Calendar…) shown as tabs above the list. A master on/off switch turns the feature off for a single unified inbox, and back on to restore it. It lives in TWO places: Settings → Inbox → Split Inbox → "Split inbox", AND in the "Manage split inboxes" dialog (the ⚙️ gear next to the tabs) as a "Turn off split inbox" button — the gear is where users actually look to get rid of the tabs (the tab strip alone only switches lanes). Turning it off there also closes the dialog, so the now-tabless inbox shows immediately.
- Off = zero split inboxes. The list shows ALL inbox mail as one stream, the tab strip (and its gear) is hidden, and split scoping is skipped. Your configured splits are not deleted — they stay on the backend and reappear when you switch it back on. Re-enable from Settings → Inbox → Split Inbox (the in-inbox gear is gone while off).
- Default OFF — one unified inbox out of the box; splits are opt-in. Device-local (browser
localStorage
supermail:split-inbox-enabled), like the other display prefs, so it does not sync to themail.jls.devweb client. Store:features/split-inbox/split-enabled-store.ts. - GOTCHA (agents): when off, BOTH the render view-key (
inbox-page.tsx) ANDcurrentInboxViewKey()(features/split-inbox/inbox-view-key.ts) must force the plainlabel-inboxview — otherwise a focus/sync refetch pulls a stale split partition and shows a subset as "all mail". The two gates are a pair; the refetch half is locked byinbox-view-key.test.ts("targets the plain inbox when OFF"). - Too many lanes for the header? With the reading pane off (lanes shown as tabs), the tab strip scrolls sideways: a ‹ / › arrow appears on whichever side still hides lanes, a click slides the strip most of a screen-width, the mouse wheel scrolls it sideways, and switching lanes from elsewhere (Tab, the lane manager, a deep link) slides the selected lane into view. The strip re-settles on the selected lane whenever its own widths change — the unread badges arriving, the fonts finishing, the header resizing — so it never sits at an offset that belongs to an older layout. Once the reader scrolls it (wheel, touch, an arrow, a click on a lane), the strip is theirs and nothing moves it again until a lane is chosen from outside it. Clicking a lane never scrolls the strip. The ⚙️ gear and right-hand toolbar buttons always stay visible.
- Switch lanes from the keyboard. Tab opens the next lane and Shift+Tab the previous
one, wrapping at both ends; empty hidden lanes are skipped and the lane you land on is remembered
exactly as if you had clicked it. The keys take over Tab only while split inbox is on with at
least two lanes showing — with the feature off, or a single lane, Tab stays a normal focus key.
Work with the lane picker open and they move you a lane and close it; inside a dialog or an open
menu, Tab belongs to that surface. Both keys are listed in Supermail's
?shortcut reference. Rules: supermail-split-tabs-contract.md. - Rearrange or edit a lane right from the tabs. Drag a tab onto another to move it — it slides into place and the order saves when you let go on the strip (let go elsewhere, or press Esc, and nothing changes); the catch-all tab stays put. Right-click a tab to edit it: your own lanes open straight into their edit screen; Gmail's own categories and the catch-all can't be edited, so they open the lane list. Heads-up: tab order is also sort order — an email matching two lanes lands in the left-most — so moving a tab can change where such mail shows up. Rules: supermail-split-tabs-contract.md.
- Invites reach the Calendar lane on the fast local path too. The default Calendar lane
recognises a meeting invite by its
.ics/text/calendarpart, and that works from the local mirror: the mirror records each message's part names and types while it caches the body, so an invitation is classified exactly as on a direct Gmail connection, without re-fetching. - Manage the lanes at Settings → Inbox → Split Inbox → "Manage split inboxes" (add/edit/reorder/ remove custom splits; the four Gmail-category builtins + the catch-all are system-managed).
- Manage them from an AI agent / CLI. An agent on the Omniscio control server can list, create,
edit, delete and reorder your split inboxes headlessly (
/supermail/splits*, a thin main→backend proxy — apply-immediately, global-token-only, the JWT stays in Main), so you can ask it to "set up a split inbox for me" — see the omniscio-controlsupermail-splitsskill spoke. Invariants: supermail-splits-cli-contract.md.
Search results order (newest first, with a sort menu)
Search lists results newest first, so a sender's latest email tops the list; mail a filter archived is still found, in Done and All Mail.
A sort menu in the results header offers Newest first (the default), Oldest first, Sender A–Z / Z–A, Subject A–Z / Z–A, Unread first and Best match (the old relevance order). Picking one reorders at once and re-runs the search, so the next page continues it. The choice lasts for the session and resets on sign-out; in "Search all mail" it sorts what Gmail has loaded so far.
Inbox list: the View options menu (sort · group · unread)
A single "View options" menu (a sliders button in the inbox toolbar) holds three device-local list toggles — sort direction, group by sender, unread only. Each is a stay-open checkbox row, so several can be flipped without the menu closing; all persist across restarts, so an untouched inbox is unchanged:
Sort direction — flip the list between Newest first (default) and Oldest first. It reorders the mail already loaded; more history keeps loading as you scroll (never force-pulling the whole mailbox). Auto-load-on-scroll stays tied to newest-first, so oldest-first can't trigger a runaway "keep loading" loop.
Group by sender — cluster the inbox under a header per sender instead of date separators. Within each sender the emails stay date-ordered (the sort direction controls that too), and every row still shows its own date — sender AND date. Off by default (the flat date-grouped list). Grouping keys on the sender's email, so two people sharing a display name stay separate.
Unread only — the same one-click "show only unread" filter that used to be a standalone toolbar button, now the third menu row (
inbox-store.listFilter). While it is on, the list pages never open a row in the reading pane on their own — you pick the thread with a click or Enter. That covers both unattended paths: the auto-open of the top row, and the keyboard-cursor preview (arrow keys / j-k still move the highlight, but the pane no longer follows it, nor does the cursor advance when a row leaves the list or it refills). Opening a thread marks it read, so an unattended open drops that row back out of the filtered list and moves on: the list reads itself away — rows vanish, "Still syncing your mail…" shows, it refills and starts over, marking real mail read every pass (with a warm cache the panel crashed on React's nested-update limit, "Something went wrong"). The guard isreadingPaneConsumesFilterinfeatures/inbox/inbox-filters.ts, honoured by bothinbox-page.tsxandlabels/label-page.tsxin their auto-select effect AND their focus-to-pane mirror; every other quick-filter (starred / important / no-reply) is inert to reading a thread and keeps both.
Sort + group are also command-palette actions (Ctrl/Cmd+K → "Inbox: Toggle sort direction" /
"Inbox: Toggle group by sender"); no dedicated single-key shortcut in v1. Device-local
(supermail-inbox-view-prefs), like the other display prefs, so they don't sync to the
mail.jls.dev web client. Sort/group are a display-only transform — the inbox store's
canonical order and pagination are untouched — in features/inbox/inbox-view-order.ts +
features/inbox/inbox-view-prefs-store.ts, with the menu built on the shared Dropdown in
features/inbox/inbox-view-menu.tsx and the sender-aware list headers in
features/inbox/thread-list.tsx.
Related
- Supermail (part 2) — the continuation of this page.
- Supermail (part 3) — the continuation of this page.
Each Supermail feature has its own page: AI Filtering, Catch me up, Assistants, Archive Insights, the AI Digest, Contact Groups, send shortcuts and the reading view.
Last verified 2026-11-19