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

# 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 **12 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 12.

## 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 **12 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 12.** 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](../../.claude/memory/contracts/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 12 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 12 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](../../src/renderer/src/features/dashboard/keep-alive-pool.ts)
  — `MAX_WARM_NEEDS_YOU` (the 12 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](../../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](../../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](../../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](../../src/renderer/src/features/settings/sections/performance/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](../../.claude/memory/contracts/keep-alive-pool-contract.md).

## Related

- [frozen-panel-retention.md](frozen-panel-retention.md) — instant switch _back_ to recently-viewed non-streaming sessions.
- [instant-new-session.md](instant-new-session.md) — instant _new_ session via Ctrl+T.
- [lazy-content-load.md](lazy-content-load.md) — instant _first_ cold-mount of a long session.