Pre-render inbox sessions (instant switch into needs-you sessions)

What it is

What it does

When a session needs your attention it moves to your inbox (its status turns to "needs you", amber). To make clicking into one of those feel instant, Omniscio pre-builds the session's full chat view — parsing the markdown, highlighting the code, building the DOM — in the background, before you click. Clicking then just reveals an already-built panel instead of showing a brief "loading" shell.

The catch is cost: each fully-built chat is real memory and CPU. If your inbox is large (dozens of sessions) and Omniscio pre-built every one, the app bogs down — lots of heavy chat views constructed and held at once. So the pre-rendering is bounded: Omniscio only pre-builds the 200 most-recently-active inbox sessions — the ones you're most likely to open next. The rest stay as lightweight shells and build in about half a second when you click them, exactly like a running session does.

This is why a big inbox could feel slow while the same sessions, once running, feel fast: running sessions are never pre-rendered heavy (only the active one is), but inbox sessions used to all be pre-rendered. Bounding the pre-render fixes that — the app stays fast no matter how large the inbox grows.

Important: bounding the pre-render does not drop any session from memory. Every inbox session is still kept "alive" as a cheap shell so its data is ready instantly; only the expensive visual pre-build is limited to the recent 200.

Where to find it

Settings → Performance, as the pre-render toggle. Its effect is felt in the inbox: clicking a waiting session opens straight into a built panel rather than a shell.

How it behaves

How to turn it on or off

Settings → Performance → "Pre-render inbox sessions". It is on by default.

The toggle's own description reads: "Pre-builds your most recent inbox (needs-you) sessions in the background so switching into them is instant. A built-in limit keeps the app fast even when the inbox is large — older inbox sessions load in about half a second when you open them. On by default; turn off to do no inbox pre-rendering at all."

No restart is required. Turning it off immediately drops any pre-built inbox panels back to shells (reclaiming their memory) and switches every inbox session to load-on-click. Turning it back on resumes background pre-building of the recent set. Most people should leave it on — the bound already keeps it cheap; the off switch exists for very low-memory machines or troubleshooting.

When it applies

• The session is in your inbox — status "needs you" (amber). Running, idle, ended, and errored sessions are not pre-rendered by this feature.
• It is among the 200 most-recently-active inbox sessions. Ping-pong between a handful of inbox sessions and they all stay instant.
• Its conversation has already loaded into memory. Omniscio fetches the recent inbox histories in the background (a couple at a time, off the critical path) and only marks a panel "pre-built" once its real content is ready — so a pre-built panel never flashes an empty chat.

When it does NOT apply

• Inbox sessions beyond the most-recent 200. They stay shells and build on click (~0.5s) — graceful, never blank.
• Non-inbox sessions (running, idle, ended, errored). Switching into those uses the normal keep-alive / load-on-click paths.
• On the phone / mobile web view, which shows one session at a time and has no background panel pool to pre-build into. Note this is only the visual pre-build that's desktop-only — the conversation history cache IS pre-warmed on mobile (a separate data-layer warm) so tapping an inbox item still paints instantly over the slow tunnel. See keep-alive-pool-contract.md § "Mobile surface — the attention-history prefetch ALSO runs on every surface".
• When the feature is off (the toggle, or the kill switch below).

Limits and memory

Each pre-built inbox panel is a full heavy chat view (markdown + syntax highlighting + DOM), so the count is deliberately capped:

• At most 200 inbox panels are pre-rendered at once (MAX_WARM_NEEDS_YOU), most-recently-active first.
• Background history fetching is rate-limited (a couple per idle slice) so pre-building never blocks the app or a keypress.
• The 200 cap stacks on top of the keep-alive pool's own budget rather than replacing it, so they never fight over the same panels.

How it relates to the other "instant session" features

Several layers make sessions feel fast; this one is specifically about switching into an inbox session:

• Pre-render inbox sessions (this page) pre-builds recent inbox panels so opening one is instant.
• Instant new session (Ctrl+T) pre-builds one blank session per project so creating a session is instant.
• Frozen-panel retention (off by default) keeps recently-viewed non-streaming panels built so switching back is instant.
• Lazy content load makes the first open of any long session paint quickly.

All four sit on top of the keep-alive pool, which keeps the active session and live/attention sessions mounted. Inbox sessions are always in that pool as shells; this feature decides which of them are additionally pre-rendered heavy.

For agents

The kill switch

There are two independent off-switches, and the environment switch always wins:

1. The Settings toggle above (prerenderInboxSessionsEnabled, default on).
2. An environment kill switch: launch Omniscio with AMC_DISABLE_NEEDS_YOU_WARM=1 and inbox pre-rendering is forced off even if the setting is on. A missing or malformed switch is treated as "not killed," so the setting governs in the normal case (fail-safe to on).

Where it lives in code

• src/renderer/src/features/dashboard/keep-alive-pool.ts — MAX_WARM_NEEDS_YOU (the 200 cap), selectWarmableNeedsYouSessions(...) (the most-recent-N selection, shared by the pre-render selector and the background fetch pump), and selectWarmHeavyIds(...) (which inbox panels render heavy).
• src/renderer/src/lib/needs-you-warm-flag.ts — isNeedsYouWarmEnabled(setting): the setting first, then the AMC_DISABLE_NEEDS_YOU_WARM kill switch wins (fail-safe on).
• src/renderer/src/features/dashboard/useRenderWarmPump.ts — the render-warm hook (extracted from Dashboard, 2026-06-07). It computes the pre-built set synchronously on every run, so pre-rendering works even when the machine is too busy to ever hand it an idle moment (the fix for the bug where nothing got pre-rendered); it also fetches the bounded inbox histories on idle, flips panels to pre-built as data lands, and clears them when the feature is turned off.
• src/renderer/src/features/dashboard/Dashboard.tsx — calls useRenderWarmPump and feeds the pre-built set (renderWarmIds) to the panels.
• src/renderer/src/features/settings/PerformanceSettings.tsx — the "Pre-render inbox sessions" toggle row.

The full engineering contract (test-locked invariants + safe-change checklist) is the "needs_you render-warm" section of .claude/memory/contracts/keep-alive-pool-contract.md.

Related

• frozen-panel-retention.md — instant switch back to recently-viewed non-streaming sessions.
• instant-new-session.md — instant new session via Ctrl+T.
• lazy-content-load.md — instant first cold-mount of a long session.