Tray and window
The system tray icon and the main window: the two close behaviours controlled by closeToTray, the tray's right-click menu with its show, wake-word, hard-reload, restart, DevTools and quit entries, the two global hotkeys, the single-instance lock, and how popped-out windows and a saved window size come back on the next launch.
On this page
What it is
Omniscio runs as a desktop app with a single main window plus a system tray icon. The tray icon (Windows: bottom-right corner near the clock; macOS: top menu bar; Linux: indicator area) is the persistent presence — it stays alive even when the window is hidden, and it's the only way to fully quit Omniscio once closeToTray is enabled, because in that mode the X button on the window just hides it instead of quitting.
The tray icon shows the Omniscio logo. Clicking it shows / focuses the main window. Right-clicking opens a small context menu with a few options. The tray's tooltip reads "Omniscio."
Two close behaviors exist, controlled by the closeToTray setting (defaults to false):
closeToTray: false(default): Clicking the window's X button quits Omniscio entirely — always; nothing keeps it running behind your back (when agents are mid-task it asks first, see the close warning below). Any other windows you have open (a detached session, a project or integration pop-out, KMS, Writer, Scratchpad, a SuperMail thread or Job Monitor) close with the app, and automatically reopen at their last size and position the next time you launch. Closing quits: child Claude CLI processes are sent a graceful kill, anything still running after 5 seconds is force-killed, then the app exits. Work in flight comes back. A session that was running, starting or stalled when you quit is saved, and on the next launch Omniscio relaunches it with a continue nudge — the Auto-Resume Sessions on Restart toggle (Settings → Workflow, also in the Manage-sessions Refill view) is on by default; switch it off and a quit is final. What does not come back: a session whose AI had genuinely finished its last turn (it returns waiting for you, markedSession preserved — app closed while waiting for your input), a session you closed yourself, and help chats such as Ask Omniscio. A session that could not be saved is surfaced in Needs You instead. TheSession suspended — app was closedmarker is the one that means nothing will resume — it is written for a session you closed yourself, a help chat, or a session whose state could not be confirmed when you quit.- The close warning (agents still working): with
closeToTray: false, pressing X while one or more agents are mid-turn first shows Omniscio's own dialog — drawn in the app, silent, never a Windows system box — saying how many agents are working and that quitting stops them mid-task. Its buttons: Keep Omniscio Running in the Background (focused; Enter) hides the window to the tray, Quit and Pause Them quits, and Cancel (Esc, or clicking outside) leaves the window open. Ticking Don't warn me again remembers the button: Keep running turns oncloseToTray(X hides from then on), Quit turns off Settings → General → Warn me before closing while agents are working (warnOnCloseWithWorkingAgents, on by default), so X just quits. Either can be switched back in Settings → General. The warning never blocks a close: with no agent working, the switch off, Windows signing out or shutting down, or a window that cannot show it (crashed, frozen, still loading, or reloaded mid-warning), X quits as usual. closeToTray: true: Clicking X just hides the window. The tray icon stays visible, every Claude CLI session keeps running in the background, notifications still fire, and you can bring the window back via the tray icon or the global hotkey. To actually exit, right-click the tray icon and pick Quit — the same graceful shutdown, with the same restart-resume behaviour described above.
The default closeToTray: false matches what most desktop users expect ("close means quit"). Enable closeToTray: true if you treat Omniscio as an always-on assistant — sessions keep working overnight, you get notifications, and the window comes back instantly when you need it.
A global hotkey (default Ctrl+Shift+M, macOS: Cmd+Shift+M) brings the window to the front from anywhere on your system, even when Omniscio is hidden to tray, minimized, or behind other windows. Rebind it under Settings → Keyboard Shortcuts → OS-level hotkeys (or the legacy mirror at Settings → System → Global Hotkey — both write the same field). A second global hotkey, the Quick Launch hotkey (Ctrl+Space by default; Cmd+Option+L on macOS), does not bring the main window forward — it opens the floating Quick Launch composer over whatever you're doing. Type a prompt and submit to start a session; press the hotkey again to close it.
Where to find it
The tray icon lives in your operating system's notification area — the bottom-right corner near the clock on Windows, the top menu bar on macOS, the indicator area on Linux. Clicking it shows or focuses the main window; right-clicking it opens the tray menu with Show Omniscio, the wake-word entry, Hard Reload, Restart Omniscio…, and Quit — plus Open Developer Tools, which is a development build's row and is not there in an installed build. The two global hotkeys are rebound under Settings → Keyboard Shortcuts → OS-level hotkeys, and the sounds and OS notifications behind the badge count are configured under Settings → Notifications. The closeToTray setting lives at Settings → General → Keep running when I close the window (GeneralSettings.tsx; behavior in window.ts).
How it behaves
How to use it
- Click the tray icon (Windows: bottom-right system tray; macOS: top menu bar) to show and focus the Omniscio window. If the window was minimized, it un-minimizes. If hidden to tray, it reappears in its last position.
- Right-click the tray icon for the menu:
- Show Omniscio — same as clicking the icon (show + focus)
- Pause Wake Word / Resume Wake Word — only appears when you have wake-word voice activation enabled in Settings → Voice Control. Toggles the always-listening microphone without quitting voice entirely.
- Hard Reload — Clears the renderer's HTTP cache, then reloads the window bypassing cache. Use it when the UI looks stuck or didn't pick up a change. Same effect as
POST /app/reloadon the CLI control server and theIPC.APP_HARD_RELOADhandler. Non-destructive: Claude CLI sessions keep running in the background, only the renderer reloads. No confirmation prompt — the reload is fast and reversible. - Restart Omniscio… — Pops a native confirmation dialog (default button: Restart, cancel button: Cancel), then relaunches Omniscio. Picks the same graceful-shutdown path as Quit below: every running Claude CLI session is SIGTERM'd with a 5-second grace and gets a shutdown marker in its history; a session still mid-work is saved and comes back on the next launch as long as Auto-Resume Sessions on Restart is on (the default). Use it when you've updated a setting that needs a restart, or when something in the main process looks wedged. The trailing … follows the platform convention for "this action needs further input."
- Open Developer Tools — Opens Chrome DevTools attached to the main window in a separate detached window. Detached mode is deliberate — a pinned panel inside the Omniscio window is awkward when the Omniscio window is itself the thing you're debugging. This row is a development build tool and is omitted from an installed build's tray (
isInstalledBuild()intray-menu.ts), so it never appears on a customer's machine. - Quit — gracefully shuts down Omniscio: terminates every Claude CLI process, force-kills anything still running after 5 seconds, then exits.
- Press the global hotkey to focus the window from anywhere. Default is Ctrl+Shift+M (Cmd+Shift+M on macOS). Works even when Omniscio is hidden to tray, behind another window, or minimized — no need to find the icon. Rebind it under Settings → Keyboard Shortcuts → OS-level hotkeys (the legacy Settings → System → Global Hotkey field still works and is mirrored to the same setting).
- Press the Quick Launch global hotkey for instant capture. Default is Ctrl+Space (Cmd+Option+L on macOS). It opens the floating Quick Launch composer over whatever you're doing — it does not bring the main window forward or launch anything by itself. Type a prompt and submit to start a session; press the hotkey again to close the composer. Rebind under Settings → Keyboard Shortcuts → OS-level hotkeys (legacy mirror lives at Settings → Quick Launch → Quick Launch Hotkey). If you set this to the same combination as the focus hotkey, the new-session hotkey is skipped to avoid the collision.
- Close the window with X. Default behavior (
closeToTray: false): Omniscio quits — always, even if you have other windows open (with agents mid-task, Omniscio's own close warning asks first; tick Don't warn me again to stop it). Graceful shutdown sends SIGTERM to every Claude CLI, waits up to 5 seconds, then force-kills survivors and exits; other windows (pop-outs, detached sessions, KMS / Writer / Scratchpad) close with it and reopen on the next launch. Sessions that were mid-work are saved and relaunched on the next launch by Auto-Resume Sessions on Restart (on by default); a session that had finished its last turn comes back waiting for you instead, and one you closed by hand is never brought back. WithcloseToTray: true: the window hides, the tray stays, sessions keep running, and X never quits — that setting is the only way to make X leave Omniscio running. - Notifications keep firing while hidden to tray. When a session needs your attention, Omniscio plays the configured "Needs You" sound and shows an OS notification (system notification center). The app icon also shows a badge count that mirrors your Inbox — the same number shown on the in-app Inbox (every inbox item: sessions that need you, plus approvals, agent alerts, integration rows, and so on — not just sessions), on the Windows taskbar, macOS Dock, and Linux notification area (depending on DE support). Clicking the OS notification focuses Omniscio and jumps to that session. Configure or silence under Settings → Notifications. See notifications-and-silence.md.
- Quit via Ctrl+Q is not bound by default. The reliable ways to fully quit are: tray icon → Quit, or (with
closeToTray: false) close the window via X. There's also the platform-standard Alt+F4 (Windows) / Cmd+Q (macOS), which both go through the same close-handler and respectcloseToTray. - Single-instance lock. If you launch Omniscio while it's already running (or hidden to tray), the second instance exits immediately and the existing window comes to the front. This is enforced via Electron's
requestSingleInstanceLock()so you never end up with two Omniscio windows fighting over the same database. (That lock guards two processes. Until bug 7206d9d9 a fast double-click could still leave ONE process showing two Dashboard windows, because the relaunch handler is live before the first window exists and rebuilt one the startup path was already about to build — fixed by making window creation refuse to build a second.) One exception: if Omniscio is in the middle of closing (the window vanishes instantly but cleanup keeps running for a few seconds), a relaunch in that brief window is ignored rather than yanking a half-closed window back — just launch again once it has finished closing, and that launch starts fresh. This keeps the shutdown and a new startup from interfering. - Popped-out windows come back on relaunch. If you have windows popped out — a detached chat session, the KMS window, a Scratchpad, or a project or integration window — and you quit Omniscio, they automatically reopen at their last size, position, and maximized or fullscreen state the next time you launch, so you don't have to re-pop them. (The same memory applies every time you reopen a pop-out, not just on relaunch — if you had it maximized or in fullscreen, it comes back the same way.) There's no setting — it just works. To keep one from coming back, simply close it before you quit (only the pop-outs still open at quit time are remembered). This works even after a crash or a force-exit, not just a clean quit: the open-pop-out list is saved continuously during the session (and force-flushed at shutdown), so a hard crash still reopens them on the next launch — the same crash-durability as Omniscio's "resume my running sessions."
- Single-instance lock. If you launch Omniscio while it's already running (or hidden to tray), the second instance exits immediately, the existing window comes to the front, and a native "Omniscio is already running" notification appears so the relaunch doesn't read as "nothing happened / it won't launch" (especially when the existing window was already visible). This is enforced via Electron's
requestSingleInstanceLock()so you never end up with two Omniscio windows fighting over the same database. (That lock guards two processes. Until bug 7206d9d9 a fast double-click could still leave ONE process showing two Dashboard windows, because the relaunch handler is live before the first window exists and rebuilt one the startup path was already about to build — fixed by making window creation refuse to build a second.) One exception: if Omniscio is in the middle of closing (the window vanishes instantly but cleanup keeps running for a few seconds), a relaunch in that brief window is ignored rather than yanking a half-closed window back — just launch again once it has finished closing, and that launch starts fresh. This keeps the shutdown and a new startup from interfering. - Popped-out windows come back on relaunch. If you have windows popped out — a detached chat session, the KMS window, a Scratchpad, or a project or integration window — and you quit Omniscio, they automatically reopen at their last size and position the next time you launch, so you don't have to re-pop them. There's no setting — it just works. To keep one from coming back, simply close it before you quit (only the pop-outs still open at quit time are remembered). This works even after a crash or a force-exit, not just a clean quit: the open-pop-out list is saved continuously during the session (and force-flushed at shutdown), so a hard crash still reopens them on the next launch — the same crash-durability as Omniscio's "resume my running sessions."
- The window always opens fully on the screen it lands on. Omniscio reopens the main window at the size and position you left it — but if that saved size is bigger than the display it opens on, it is shrunk to fit and nudged fully on-screen first. This matters most on a monitor rotated to portrait: a 1080×1920 panel leaves only ~830 points of usable width, so a window sized on a landscape monitor would otherwise open wider than the screen and hang off both edges — a small "boxed" window with the theme's background glow cut off past the edge. The minimum window size shrinks with the display too, so a narrow screen can always contain the whole window and you can never be left dragging a window that is physically wider than your monitor. A window you have deliberately stretched across two monitors is left exactly as it is. There's no setting — it just works.
- On a portrait monitor, the first-ever window is portrait-shaped too. Omniscio's built-in default window size is a landscape-shaped 1200×800. On a display that is taller than it is wide, the default becomes the usable screen area instead — so a brand-new install on a rotated monitor un-maximizes to a tall window rather than a stubby one using barely half the height. This only affects a profile with no saved window size yet (a fresh install, or one whose saved size was corrupt); once you have moved or resized the window even once, your own size is what comes back. On any landscape or square display the default is unchanged, exactly 1200×800. One consequence worth knowing: on a fresh portrait profile the windowed size equals the screen, so un-maximizing looks like it does nothing until you resize the window yourself — that is deliberate.
###Notices from the tray
Omniscio's own notices — a cloud outage, a scheduled job that failed, a budget cap or a provider balance warning — arrive as a desktop pop-up exactly like a session alert does. They are both "Omniscio", so at a glance they are indistinguishable: telling them apart means reading each one. The opt-in Send Omniscio's own notices from the tray setting (Settings → Notifications, directly under the System notifications block) separates them.
It is off by default, and flipping it takes effect on the very next notice — no restart. It is read when a notice fires, not at start-up. With it off, nothing changes at all: the delivery, the wording, the sound and the rendering of an app notice are exactly what they were before this setting existed.
What counts as one of Omniscio's own notices. The notices the app raises about itself: everything fired for a cloud, cron, SMS-health, provider-status, new-model, balance or spend-runaway event, plus the app-state account notices (budget warning, budget exceeded, all accounts exhausted, sign-in expired). The wedged-self-heal escalation ("a background auto-fix is stuck") counts too: it is cron reporting on itself. Deliberately not included are anything that asks you to act or carries your own content — session alerts (a session needs you, stalled, errored), a recipe awaiting your approval, a device-approval or workspace-join prompt, PM board activity (assignments, deadlines, overdue items), and person-to-person messages (Team Chat, incoming SMS). Labelling one of those as the app's housekeeping would push something that wants you into the list you have learned to skim, which is the opposite of the point.
What the setting changes, with it on:
- The notice comes from the tray (Windows). Instead of a plain app pop-up, the notice is raised as a tray notification from the Omniscio tray icon, with the operating system's info glyph. A Windows toast's icon is fixed by the app's identity, so the tray route is what makes these look unlike an ordinary pop-up sitting next to them.
- It is labelled. Any app notice delivered as a pop-up carries a group header the operating system prints above it, so the notification centre holds Omniscio's own notices and your session alerts as two separate groups. A session alert never carries that header — it renders exactly as it always has.
- Clicking it still works. A tray notice click focuses the Omniscio window, and for a notice about one specific session (a budget cap) it opens that session — the same click a session alert carries.
- Nothing is lost to a route that cannot run. Where the tray cannot carry the notice — macOS and Linux have no tray-notification API, the tray is gone mid-quit, or the call is refused — the notice falls back to the labelled pop-up, exactly once. Both the success and the failure are logged, so "it came from the tray" and "it fell back" are each readable rather than guessed at.
One limit worth knowing. Windows gives no failure signal for a balloon it quietly swallows (a policy or a focus setting can drop it without a word), so a notice suppressed that way is not re-delivered. The tray route is the fast path, not the record: the inbox card the same event raises is what still reaches you.
What it does not change. Session alerts are byte-for-byte identical whether the setting is on or off — the separation is bought entirely on the app-notice side. The tray icon itself, its right-click menu, sounds, Focus Mode and the notification-behaviour setting above it all behave as before (see notifications-and-silence.md). The tray route is Windows-only; macOS and Linux get the labelling half and keep their existing delivery.
Under the hood the app-notice entry point is notificationService.showSystemNotification(...) (notification-service.ts), which consults tray-system-notifications.ts for the route and the group label; the channel-level app notices (budget, accounts, auth) reach it through the same NotificationCore method. The invariants it must keep are in tray-system-notifications-contract.md.
Related
The pages below cover the neighbouring surfaces:
- keyboard-shortcuts.md — every hotkey (including the two OS-level ones above) is now rebindable under Settings → Keyboard Shortcuts; the old Settings → System fields remain as a mirror for backward compatibility
- open-settings.md — Settings → System is where launch-on-startup lives (and the legacy hotkey mirrors)
- notifications-and-silence.md — sounds, OS notifications, badge counts, and how to silence them
- keyboard-shortcuts.md — full list of in-app shortcuts (Ctrl+Shift+M and Ctrl+Space are global, the rest are app-only)
- quick-launch-modal.md — Quick Launch is the global Ctrl+Space surface; this page covers its UI, defaults, and settings
- app-shell-health-banners.md — the frame around the window and the thin strips at the top of it that say the app is offline, reconnecting, possibly frozen or in Safe Mode
Last verified 2026-10-03