App shell and health banners (what the app tells you about itself)

What it is

Every other feature in Omniscio assumes the app is healthy and connected. This one is about the moments it is not, and about the frame that holds everything else.

The shell is the window itself. Omniscio draws its own title strip rather than using the operating system's, so the top of the window is draggable chrome in the app's own style with its own caption buttons, a wayfinding trail and an inbox counter. The same idea applies to popped-out windows, which each get a slim draggable strip of their own. The app icon in the taskbar or dock carries a badge too, so you can see that something needs you without the window being visible.

The health banners are one-line strips pinned to the top of the window. They exist so a broken or degraded state never masquerades as a quiet one: a dropped connection, a frozen main process or a restricted start-up should be something you can see at a glance, not something you infer from a screen that stopped changing. They are stated in plain language, they use the app's amber "needs patience" tone rather than alarming red where no action is possible, and none of them covers the app's content.

Where to find it

At the very top of the Omniscio window, above all content and — deliberately — above any dialog, pop-up or menu that happens to be open at that moment. There is nothing to switch on: a banner appears only while its condition is true and disappears on its own when it is not.

How it behaves

The connection strips

When your phone or browser cannot currently reach the computer running Omniscio, one of four strips appears:

• You are offline. Some features are unavailable. — shown on desktop and on a phone, only after the app has been genuinely offline for five seconds. A momentary network blip never flashes it.
• Reconnecting… — the app is re-establishing the live link after an outage.
• Waiting for your computer… — the link is still open but has gone quiet, or a request you made has gone unanswered for five seconds. This is the calm twin of the strip above: same look, a different icon, so the two read as related but distinct.
• Connection lost — tap to reload — the app has stopped retrying. This one is actionable, and tapping it reloads the app, which is the guaranteed way back.

At most one of the socket strips shows at a time, by precedence: connection lost first, then reconnecting, then waiting. The offline notice is separate from those three and can appear alongside one. On the desktop app there is no socket to lose, so the socket strips never appear there — only the offline notice does.

The connection strips are drawn on their own layer above dialogs, so a dropped link is never hidden behind a pop-up, but they are see-through to your taps: only the reload button catches a click, so a tap aimed at whatever is underneath still lands there.

The app-frozen banner

The app may be frozen — waiting for it to respond. appears on the desktop app when the main process has gone silent. The app's engine sends a small heartbeat about every five seconds; if none arrives for roughly fifteen seconds — three missed beats — while the window is visible, this strip appears.

It is informational on purpose. Reloading the window cannot unfreeze the engine, so waiting is the designed recovery. The moment a heartbeat arrives the strip clears, and the whole check is skipped on a phone or in the browser, where a dead engine shows up as the connection-lost strip instead.

The Safe Mode banner

Safe Mode — automation and integrations are off. You can still view and run sessions manually. appears when Omniscio booted in Safe Mode, and its Restart Normally button is the way out. Safe Mode is sticky by design, so this banner has no dismiss button — hiding the only exit would strand you in it. Pressing the button asks for confirmation first, because restarting normally stops any sessions you started while in Safe Mode. Safe Mode has its own page under Related for what it disables and how it is entered.

The graphics-acceleration banner

Desktop only, and self-gating: it appears only when the app itself turned graphics acceleration off, which it does after repeated start-up crashes. The only symptom is usually a stuttering mouse over the window. It stands down while Safe Mode is on, since Safe Mode owns the banner above and deliberately runs on basic graphics.

The one-time nudges

A few other strips share this space, appear under narrow conditions and are dismissed for good once handled:

• Credentials — a nudge when you skipped both an account and an API key during setup; dismissing it is remembered, and it can send you straight to the account settings.
• Required extensions — shown after onboarding when an extension Omniscio depends on is missing. It can install for you, or snooze itself, and it waits a day before asking again.
• Plain Speak was reset — a one-time notice to the people the change actually affected, explaining that the setting is now opt-in.
• Reply to start — appears only while starter agents are genuinely parked and waiting, because a reply is the only thing that wakes them. It removes itself once they have all been started.
• Push notifications — on a phone's browser only, offering to turn on notifications; dismissing is remembered on that device.
• Device approval and pairing — on a phone or browser only, when the device is paired but not yet approved, or when the server has rejected its credential. The pairing card is deliberately distinct from the connection-lost strip, because that one's reload cannot fix a rejected device.

The window frame

• The main window's title strip is about 50 pixels tall, draggable, and carries Omniscio's own caption buttons in place of the operating system's. It also holds a wayfinding trail and the inbox attention counter — the same number the sidebar's Inbox badge shows, computed once so the two can never disagree.
• Popped-out windows are frameless and get their own slim draggable title strip with its own caption buttons. On macOS the native traffic lights stay where they are. (A drag strip has no keyboard equivalent inside the app; the operating system's own window menu, such as <kbd>Alt</kbd>+<kbd>Space</kbd> then Move on Windows, moves a window without a mouse.)
• The app icon badge in the taskbar or dock shows attention. It is clamped to nothing — while the real counts stay untouched underneath — in three cases: Focus Mode is on, Presentation Mode is on (a count baked onto your icon while screen-sharing is a leak), or the desktop icon badge has been switched off in settings.

For agents

Under the hood (for agents with repo access)

• The stack. src/renderer/src/app/AppBanners.tsx mounts every shell banner in one place; ConnectionBanner.tsx owns the four connection strips, with browser-only precedence lost > reconnecting > waiting from pickSocketStrip, and the offline strip independent of it. The strips render through a portal onto <body> on the z-connection-banner layer (above dialogs, below the toast deck) inside a pointer-events-none wrapper; only the reload Button opts back in.
• The 5-second offline gate is src/renderer/src/hooks/useOfflineBannerGate.ts (default delayMs = 5000, cancelled if connectivity returns first).
• The frozen detector is src/renderer/src/hooks/useMainLivenessWatch.ts: MAIN_LIVENESS_TICK beats arrive every ~5 s, staleness is judged every 3 s against MAIN_LIVENESS_STALE_THRESHOLD_MS (~15 s), only while the window is visible, and it sets appFrozen on the connectivity store. It is enabled on Electron only.
• Safe Mode is src/renderer/src/app/SafeModeBanner.tsx — gated on isSafeModeActive(), exit via IPC.SAFE_MODE_SET { enabled: false } after a confirm; contract .claude/memory/contracts/safe-mode-contract.md.
• The frame is src/renderer/src/components/ui/CustomTitlebar.tsx (TITLEBAR_HEIGHT = 50, WindowControls, the injected breadcrumb, attentionCount) and StandaloneWindowTitleBar.tsx for popouts (titleBarStyle: 'hidden', STANDALONE_WINDOW_TITLE_BAR_HEIGHT).
• The app-icon badge is resolved in src/main/services/notification-service.ts (badgeSurfaceSilenced() vetoes on focusModeService.isEnabled(), presentationModeEnabled === true, or desktopIconBadgeEnabled === false — read === false on purpose so the default stays ON) and painted through setOverlayIcon in src/main/ipc/notification-handlers.ts.
• Related contracts: .claude/memory/contracts/mobile-ws-stall-guard-contract.md (the reconnect/give-up state machine the connection strips display), inbox-count-list-parity-contract.md (one attention number across surfaces), presentation-mode-dnd.

Related

• tray-and-window.md — the tray icon, the two close behaviours, the global hotkeys and how popped-out windows come back on the next launch.
• offline-banner.md — the offline strip on its own: what it means and what still works while it is up.
• safe-mode.md — what Safe Mode turns off, how it is entered, and how to leave it.
• mandatory-claude-extensions.md — the extensions the nudge is about, why Omniscio requires them, and how they are installed.