# Sessions & agents settings These settings control how Omniscio starts, runs, recovers, and manages agent sessions — from automatic restarts and input focus to refill governors and deep forensics analysis. --- ## Auto-focus chat input {#sessionAutoFocusInput} When you switch to a session, Omniscio leaves your cursor OUT of the message box — you read first, then press **R** to start typing, Gmail-style. That keeps the single-key shortcuts (E archive, S star, C continue, H snooze) live while you read, instead of typing letters into a box you did not mean to be in. Turn this on if you would rather have the cursor placed in the message box automatically on every session switch. A brand-new session, and any session you launch yourself with Ctrl+T or the "+" button, still focus the box immediately either way — there is nothing to read yet. Accepted values: on / off. **Off by default** (it shipped on until 2026-08-25; if you had it on, your choice is kept). --- ## Session engine V2 {#sessionStoreV2Enabled} Runs the rebuilt session engine (V2) behind your session list, switching, and history. It behaves identically to the previous engine but is built on cleaner internals, which makes future improvements easier to ship. Leave this on unless you notice a problem after an update — if something looks off, turn it off and restart the app (the engine is chosen at startup). Accepted values: on / off. On by default. --- ## Sessions can self-archive without approval {#sessionSelfArchiveWithoutApproval} When a session finishes its work, it can archive itself straight away — even if your "Require approval for session archive" setting would normally put up an inbox card first. Only a session archiving *itself* gets this exemption; archiving a different session through the command-line API still goes through the normal approval path. Useful if you run many short-lived agent tasks and don't want archive confirmations cluttering your inbox. Off by default. Accepted values: on / off. --- ## Self-archiving master switch {#sessionSelfArchiveEnabled} The master switch for session self-archiving. When on (the default), a finished session may archive itself off your board once it decides there is nothing left for you to see, decide, or receive. When off, that self-archive signal is ignored and every session stays on your board until you archive it yourself. Turning this off also overrides **Sessions can self-archive without approval** above. Accepted values: on / off. On by default. --- ## Weekly forensics scan {#sessionForensicsAutoWeeklyEnabled} When enabled, the deep AI-powered analysis of your past sessions runs automatically once a week (Monday morning) — no manual trigger needed. The deep run spawns a paid agent session and will respect the daily spend cap you set below. The free deterministic friction scan (which looks for command timeouts, tool errors, and similar patterns) always runs on its own schedule regardless of this toggle. Accepted values: on / off. --- ## Forensics daily spend cap {#sessionForensicsDailyCostCapUsd} The maximum amount (in US dollars) that the opt-in deep forensics analysis session may spend in a single calendar day before it is refused. Because the deep run spawns a real paid agent session, this cap prevents unexpected charges if the analysis runs more often than expected. Accepted values: 0.05 – 20. Set alongside the weekly auto-run toggle above. --- ## Forensics scan interval {#sessionForensicsScanIntervalHours} How often the free deterministic friction scan runs — the lightweight pass that looks for patterns like command timeouts, hook blocks, tool errors, and redundant directory changes in your recent session history. Lower values give you fresher friction data; higher values reduce background activity. Accepted values: 1 – 168 hours (1 hour to one week). --- ## Session refill batch size {#sessionRefillBatch} When the Session Refill Governor revives interrupted sessions on its five-minute check, this limits how many it brings back in a single pass. Keeping this low prevents a burst of simultaneous restarts that could strain your machine or blow through budget quickly. Raise it if you want faster recovery after a crash or restart. Accepted values: 1 – 20. --- ## Refill cooldown between revives {#sessionRefillCooldownMinutes} After the governor revives a session, it will not poke that same session again for at least this many minutes. This prevents a session that keeps stopping immediately from being repeatedly relaunched in a tight loop. Accepted values: 1 – 1,440 minutes (up to 24 hours). --- ## Refill daily spend cap {#sessionRefillDailySpendCapUSD} The most the Session Refill Governor may spend reviving sessions in a single local day. Only pay-per-use sessions count toward it — an API key or a per-token vendor; a session on one of your Claude Pro/Max subscription accounts costs nothing extra per turn, so it does not count (one whose account you have since removed does, because its billing can no longer be told). Once today's revives reach this dollar amount, the governor pauses until tomorrow, and the Refill tab says the spending limit is what stopped it. Set to 0 to disable the dollar cap entirely — the daily revive-count limit still applies even when the dollar cap is off. Accepted values: 0 – 100,000. --- ## Refill target session count {#sessionRefillTargetCount} When fewer than this many sessions are actively running, the governor looks for recently interrupted work sessions and revives them until your running count reaches this target. Think of it as your "always keep N sessions working" setting. The governor only revives interrupted work sessions by default — not sessions you explicitly closed. Accepted values: 1 – 500. --- ## Allow refill to reopen closed sessions {#sessionRefillAllowReopenUserClosed} By default the Session Refill Governor only revives interrupted sessions — it never reopens a session you explicitly closed yourself. Turn this on to grant it that extra permission, so it may also bring back sessions you closed if your running count drops below the target. Off by default. Accepted values: on / off. --- ## Refill daily revive limit {#sessionRefillDailyMaxRevives} A hard backstop on the total number of sessions the governor may revive per local day, regardless of cost. This bounds the absolute worst-case spend even if the dollar cap is off. Default is 200 revives per day. Accepted values: 1 – 5,000. --- ## Refill candidate age window {#sessionRefillMaxCandidateAgeHours} The governor only considers sessions that were active within this many hours as candidates for revival — older or abandoned sessions are skipped. Lower this to revive only very recent work; raise it to cast a wider net on older interrupted sessions. Default is 24 hours. Accepted values: 1 – 720 hours. --- ## Refill nudge message {#sessionRefillNudgeText} The "continue" message the governor sends to a session it revives, for example: *"Please continue where you left off and finish the task."* You can customise this text if your sessions respond better to a different prompt — for instance, one that reminds them to check the branch status or summarise before continuing. Accepted values: any text up to 2,000 characters. --- ## Name patterns excluded from refill {#sessionRefillExcludeNamePatterns} A list of case-insensitive patterns (regular expressions) matched against session names. Any session whose name matches is never revived by the governor — useful for keeping generic shells, intake sessions, or outward-facing bots off the revival list. Default patterns exclude names like `^Session 1`, `[BUG]`, `[FEEDBACK]`, `Email:`, and `Tweet:`. Accepted values: up to 50 patterns, each up to 200 characters. --- ## Auto-continue when agent pauses {#autoContinueEnabled} When the agent pauses mid-task without asking a question — for example, it says "I'll continue now" but then stops — Omniscio automatically nudges it to keep going. This prevents unnecessary inbox interruptions during long jobs where the agent briefly idles between steps. Turn off if you prefer to see every natural pause land in your inbox. Accepted values: on / off. --- ## Resume sessions after crash {#autoResumeOnCrash} When the app is closed unexpectedly or crashes, sessions that were actively running receive a "continue" nudge when Omniscio restarts; sessions that were waiting for your input are restored to their waiting state. This means you rarely lose work to an unexpected shutdown. Turn off if you prefer to manually decide which sessions to restart. Accepted values: on / off. --- ## Auto-restart unresponsive sessions {#autoRestartUnresponsiveSessions} When a session shows "thinking" but its underlying process has wedged and stopped responding, Omniscio detects the stall and restarts that turn automatically — instead of leaving it spinning forever. The restart picks up from where the session stalled. Turn off to leave a stuck session in place so you can investigate it yourself. Accepted values: on / off. --- ## Retry transient launch failures {#relentlessSessionRelaunch} When a session fails to launch because the machine is momentarily overloaded — a brief OS hiccup, not a genuine error — Omniscio keeps retrying with an increasing gap between attempts instead of giving up after a few tries. Genuine errors (wrong credentials, bad config) still stop immediately and turn the session red. Accepted values: on / off. --- ## Break agent read loops {#readLoopBreakerEnabled} When an agent gets stuck re-reading the same unchanged file over and over, Omniscio detects the pattern and re-launches that turn so it can make forward progress — instead of letting it spin and stall. This covers a known failure mode where an agent loses its place and loops on tool reads indefinitely. Accepted values: on / off. --- ## Auto-recover stalled context {#contextStallAutoRecoverEnabled} When a session fills its context window and stops mid-task without finishing, Omniscio automatically frees space and continues it — so you see a finished reply instead of a blank or truncated one. This is most useful for long-running coding or research sessions. If you prefer to see the context-full warning and decide manually, turn this off. Accepted values: on / off. --- ## Fix late-thinking display bug {#trailingThinkingBoundaryV2Enabled} Addresses a rare display issue where a background tool returning late caused an "Extended thinking" line to appear *after* the agent's real answer — pushing that answer into the collapsed activity section and leaving only a short acknowledgement visible. Turn on to recover those hidden answers. Off by default because the problem is rare; the clean folded view is the normal case. Accepted values: on / off. --- ## Clear old sub-agent output {#trimOldSubagentOutput} When on, Omniscio removes the raw hidden sub-agent (Task helper) output from sessions you archived more than 14 days ago. Your conversation messages are untouched; only the collapsed "subagent result" text cards in those old archived sessions are cleared. A full backup is taken before anything is removed. Useful for reducing database size on installs with a large archive. Accepted values: on / off. --- ## Allow script-driven session spawning {#agentDrivenSessionsEnabled} Lets external scripts spawn Omniscio sessions and send them follow-up messages programmatically. Off by default — leave it off unless you have a trusted script or automation that needs this access. When on, use the limits below (`agentDrivenMaxConcurrent`, `agentDrivenMaxDollarsPerSession`, `agentDrivenMaxTurnsPerSession`) to bound what those scripts can do. Accepted values: on / off. --- ## Agent Board {#agentStatusBoardEnabled} Shows a live board of every agent Omniscio has launched — its workspace, current status, dev-pipeline phase, and to-do checklist — each with one click to jump straight to that session. Enabling this adds an Agent Board icon to the toolbar. Useful when you're running many concurrent agents and want a single-glance overview of what's happening. Accepted values: on / off. --- ## Auto-switch to inbox when idle {#autoSwitchToInbox} When another session needs your attention, Omniscio automatically navigates you to the inbox — but only if you've been idle for at least five seconds and are not currently scrolling, clicking, or typing. This keeps you from being interrupted mid-action while still surfacing urgent items quickly during natural pauses. Accepted values: on / off. --- ## Bring app forward when a session needs you {#autoFocusOnNeedsYou} Brings the Omniscio window to the foreground whenever a session transitions to "Needs you" — for example, when an agent asks a question or hits a required approval. Useful if you work in other apps while agents run in the background. Turn off if you prefer to check in on your own schedule. Accepted values: on / off. --- ## Require spawn source tracing {#requireSpawnSourceSession} When on, a session spawned via the command-line API is rejected unless the caller declares which session requested it (the `X-AMC-Source-Session-Id` header — Omniscio-spawned agents have it automatically as `$AMC_SESSION_ID`). This keeps every spawned session traceable back to its origin, which is important for auditing and debugging complex multi-agent workflows. Turn off to allow anonymous script or manual spawns. On by default. Accepted values: on / off. --- ## Auto-detect project icons {#autoDetectProjectIcons} Scans hub folders for favicons and logos and uses them as the project icon in the sidebar. When on, projects tied to a web app or known codebase often get a recognisable icon without you having to set one manually. Turn off if you prefer to assign icons yourself or if the auto-detected results are inaccurate. Accepted values: on / off.