--- title: Context Usage Warnings --- # Context Usage Warnings ## What it is **Context warnings** are automatic in-chat alerts that tell you when a session's context window is filling up. Two thresholds exist: **75%** (a heads-up that context is getting full) and **90%** (compaction is imminent — the session will compact its conversation history soon to free space). Each warning appears as a persistent amber-colored divider line in the chat with a triangle-warning icon and a message like "Context is 85% full (170k / 200k tokens)." The warnings stay in the chat permanently — they don't disappear when you scroll, and they survive app restarts. After compaction resets the context window, the warnings can fire again on the next ramp-up. To keep the warnings from becoming noise, two suppression rules apply. First, each threshold fires **at most once per fill-up** — the warning does **not** repeat just because the session restarts or switches accounts after a rate limit; it only re-arms after a real compaction frees space. Second, while the agent is deliberately **parked waiting** on a background task (you'll see an "agent appears to be waiting" note in the chat), the context warning is suppressed entirely — a waiting agent isn't running the turn that would overflow, so the alert would just be a false alarm. **Both thresholds are OFF by default** — an automatic nag on every long chat is something you opt into, not something Omniscio imposes. Turn either on in **Settings → Sessions → Advanced → "Warn when a chat is 75% full"** / **"Warn when a chat is 90% full"**. Once a warning is showing, you can also flip both switches **right from the message**: a small **⋯ options button** sits at the end of the warning line (you can also **right-click the warning**), opening a popover that explains in plain English what the warning means. Changes save instantly. Turning a warning off only stops _future_ notes — the message already in the chat stays. The default is off for **new** installs. If you have been using Omniscio for a while and your saved settings already have these warnings on, they stay on until you turn them off — the change deliberately doesn't reach in and flip a setting you already have. The same is true of the separate [session handoff](session-handoff.md) note. ## Where to find it The warnings appear **inline in a session's chat**, as an amber divider line partway down the conversation — that is where you read them, and the small options button at the end of that line (or a right-click on it) is where you switch them on or off again. The switches themselves live in **Settings → Sessions**, under the **Advanced** heading, and on mobile the options button is the only route since there is no right-click. ## How it behaves ### How to use it 1. **Turn a warning on (they ship off).** Open Settings → Sessions, expand **Advanced**, and use the toggles "Warn when a chat is 75% full" and "Warn when a chat is 90% full". Once a warning is showing in a chat you have a second, quicker route: click the **⋯ options button** at the end of the warning line — or **right-click the message** — and flip the switches in the popover that appears (it also explains what the warning means). On mobile, use the ⋯ button (there is no right-click). Settings is the route that always works, since with the warnings off there is no warning row to click. 2. **Watch for amber warnings in the chat.** While a session is actively running, Omniscio checks the session's context usage at the end of each turn (in the default mode). When the threshold is crossed, an amber divider line appears inline in the conversation. 3. **Take action if you see a 90% warning.** The session will compact automatically soon. If you want to preserve the current conversation state, consider using the session's compaction summary (click "Show summary" on the compaction divider after it appears) or copying important context before compaction happens. 4. **After compaction**, the warnings re-arm. If the session fills up again, they fire once more at the same thresholds. A rate-limit account-switch or app restart does **not** re-fire a warning on its own — only a real compaction re-arms it — so a busy session that resumes repeatedly won't keep repeating the same "100% full" line. ### How it works In the default mode, Omniscio checks context fullness **at the end of each turn**, not on a background timer. Two things happen at turn-complete. (1) A **cheap** check runs every time: `checkContextWarning()` in [context-budget-manager.ts](/src/main/process/context-budget-manager.ts) reads a free in-memory estimate of fullness (no process launched) and can fire a warning from it. (2) The **expensive authoritative** check — launching the `/context` CLI command (via [context-query.ts](/src/main/services/context-query.ts)) — runs only when a consumer will actually show the result: a 75%/90% warning is enabled, or the context indicator is on. `maybeQueryContextAtTurnEnd()` in [context-budget-manager.ts](/src/main/process/context-budget-manager.ts) makes that decision; with no consumer enabled the spawn is skipped entirely. There is **no background polling** in the default mode. Both checks hand the percentage to a pure decision helper, `decideContextWarning()` in [ndjson-utils.ts](/src/main/process/ndjson-utils.ts), which applies the two suppression rules on top of the raw thresholds before any message is emitted: - **Suppress while waiting.** If the session is parked in a "staying running" hold (the waiting detector has set `deferredWork`), the helper returns "no warning" — the alert would be a false alarm next to the "agent appears to be waiting" banner. - **Once per fill-up.** Whether each threshold has already fired is tracked at the **session** level — manager-side Sets keyed by session id (`contextWarn75Ids` / `contextWarn90Ids`), **not** flags on the per-process session object. That's why a rate-limit account-switch or app restart, which re-spawns the underlying CLI, does not re-fire the warning. The tracking is cleared only by a `compact_boundary` event (a real compaction lowered the context) and when the session is removed. Because both warnings now ship **off**, a default install has no consumer for that expensive check at all — so unless you turn on a warning or the context indicator, the `/context` helper launch simply never happens. That is a small free speed-up, and nothing is lost: the automatic recovery for a session that runs out of room keys off a compaction signal, not off this percentage. One consequence worth knowing internally: the `??` fallbacks beside every read of `contextWarning75Enabled` / `contextWarning90Enabled` are the *real* default, because `getSettings()` does not merge in `DEFAULT_SETTINGS`. They must move in lock-step with the declared default — a stray `?? true` would quietly bring the warnings back for exactly the installs that never asked for them. When a warning does fire, it's emitted as a system message with `metadata.kind = 'context-warning'`. After a compaction event the per-session warn-once tracking is cleared, so the next context ramp-up is monitored again and can re-fire the warnings. **The authoritative check is fullness-gated, and skipped when nothing will show it (default on).** When the **"Keep my computer smooth under load"** master toggle is on (`smoothLoadEnabled`, the default), the end-of-turn `/context` helper launch is governed two ways: it is **skipped entirely** when no consumer is enabled (no 75%/90% warning and no context indicator), and on the warning-only path it is **skipped** for any session whose free in-memory fullness estimate is comfortably below the warning band (under 60%) — so running many sessions at once doesn't pile up one helper-process launch per session. (If the context indicator is on, the fullness gate is bypassed so the indicator gets the real number even below 60%.) **No warning is missed:** the authoritative number refreshes at each turn-complete for any in-range session, and the cheap free-estimate warning check runs every turn regardless of the gate; a slightly-stale authoritative number is only possible _below_ 60%, where there is no threshold to cross. The gate fails open (launches) when fullness is unknown. Turning the toggle off restores Omniscio's older behavior: a 90-second background poll plus an unconditional end-of-turn launch for every running session. See [Keep my computer smooth under load](smooth-load.md). On the renderer side, [MessageBubble.tsx](/src/renderer/src/components/ui/MessageBubble/MessageBubble.tsx) detects `metadata.kind === 'context-warning'` and renders the message with amber styling (amber border, amber text, `AlertTriangle` icon) instead of the default gray system-message treatment. That same row also carries the **in-message control**. `MessageBubble` adds a small `⋯` options button after the timestamp and wires an `onContextMenu` (right-click) handler on the warning row; either opens [ContextWarningControls.tsx](/src/renderer/src/components/ui/ContextWarningControls.tsx), a small popover. The popover is **portal-mounted to `document.body`** — the warning lives inside a virtualized chat row whose CSS `transform` would otherwise become the containing block for a `position: fixed` panel and mis-place it (the same reason the chat's image/document right-click menus portal). It renders a plain-English explanation plus two `ToggleSwitch`es bound to the same `contextWarning75Enabled` / `contextWarning90Enabled` settings, flipped through `settings-store`'s `updateSetting` (optimistic save + "Settings saved" toast, auto-rollback on failure). Because the warning renders as a **standalone** message — it is deliberately **not** one of the kinds the real-conversation layout folds inline (`INLINE_MARKER_SYSTEM_KINDS` in [TurnGroup.tsx](/src/renderer/src/features/sessions/TurnGroup.tsx)) — the control always has a row to attach to; a guard test locks that. ## Related The master toggle that decides whether this check runs at all — and that keeps many sessions from each launching a helper process — is on the [Keep my computer smooth under load](smooth-load.md) page. What you see *after* the window fills and the conversation is compacted is described on [Compaction Summary](compaction-summary.md), and the separate, token-measured note that offers to carry work into a fresh session is [Session handoff](session-handoff.md). How the chat handles new rows like these appearing while you are scrolled elsewhere is on [Session scroll position](scroll-position-memory.md). - [Keep my computer smooth under load](smooth-load.md) — the `smoothLoadEnabled` master toggle that gates this check (turn-complete-only, fullness-gated, skipped when no warning/indicator will show it) so many concurrent sessions don't each launch a `/context` helper - [Compaction Summary](compaction-summary.md) — the expandable summary card that appears after compaction completes, showing what was in the context before it was compacted - [Session handoff](session-handoff.md) — a **separate**, absolute-token note (sized per model — 0.75 × the model's context window by default, e.g. 750,000 tokens on a 1M model, 150,000 on a 200k one) offering to carry the work into a fresh session. It is not a third threshold on this feature: these two warnings stay percentage-based and unchanged, while the handoff note is measured in tokens because quality degradation tracks context **length**, not window fullness - [Session scroll position](scroll-position-memory.md) — how Omniscio handles scroll position when new messages (including warnings) appear