Omniscio

Customize the header toolbar

The row of small icon buttons on the right of the title bar, and how to rearrange it — pin a tool into the bar, send it to the "More" overflow menu, or hide it entirely. Covers the right-click menu, the overflow's recent installs and search, drag-to-reorder, dividers, hover descriptions and the full Widgets manager in Settings.

On this page

What it is

The header toolbar is the row of small icon buttons on the right side of Omniscio's title bar (top of the window). By default it ships the marquee set — Notifications, Scratchpad, Help & Docs, Recipes, Mobile Access, Feedback, and the Settings gear — the features worth discovering on day one, with every other tool in the "More" menu, searchable from the "More" menu. It has two zones:

  • Pinned buttons — the icons shown directly in the bar.
  • The "More" menu — a three-dot (⋯) button at the end of the bar. Clicking it opens the "overflow" menu, which holds the buttons that can live on the bar but aren't pinned: apps that open as a popup and quick actions (Feedback, Reload, Check for updates and the like). With the search box empty it shows your Recently installed apps. Type in the search box at the top to see the six best matches as one list. A small note at the bottom reads "Full screen apps cannot be pinned to the toolbar": apps that take over the whole window are opened from the side bar, Quick Launch, the Tools page or the Marketplace instead.

Beyond the bar itself, the header's right side is a row of draggable blocks: the whole Shortcut bar is one block, and every widget that shows a reading (Balancer, Hardcore, Usage, Agent tool wait, Credits, Land Queue, Weather, Git running) sits outside the bar as its own bare block (no pill background), because the bar holds only pinned shortcuts. Drag a widget block directly (a tap still opens its panel — a drag reorders), or drag the Shortcut bar by the small grip that appears on hover; the block order is saved. Icons still reorder inside the Shortcut bar exactly as before.

You decide which buttons sit in the bar, which live in the "More" menu, and which are hidden entirely. Three gestures cover everything:

  • Pin / Unpin — move a button between the bar and the "More" menu.
  • Go to settings — jump straight to the settings page for that button's feature.
  • Remove from header — hide a button from BOTH the bar and the "More" menu. Removing a button does not turn off the feature — it only hides the icon. Every removed button can be added back from Settings → Widgets.

The one button you can't remove is the Settings gear — it's the guaranteed way back to re-add anything, so Omniscio always keeps it available.

Where to find it

The toolbar itself is the strip of icon buttons on the right-hand end of the window's title bar, at the very top of the app — it is always on screen, so nothing has to be opened first. The three-dot button at its end opens the "More" menu that holds everything not pinned. The full manager lives in Settings → Widgets, and each button's own feature settings are one click away through the right-click menu described below.

How it behaves

How to use it

Right-click any toolbar button — a pinned icon in the bar OR a row in the "More" menu — to get a small menu. The menu adapts to what you right-clicked:

  • Go to settings — appears when the button's feature has a settings page (e.g. right-click Mind Map → opens Settings at the Features section; New alarm → Notifications / Alarms; Resources → Diagnostics). Action-only buttons (Hard Reload, Help & Docs, Check for updates, Feedback) have no settings page, so this entry is hidden for them.
  • Pin to toolbar (on a "More"-menu row) / Unpin from toolbar (on a pinned icon).
  • Remove from header — hides the button everywhere. A toast confirms it and tells you where to get it back ("re-add under Settings - Widgets"), with an Undo button for one-click restore.

Right-click the header bar itself — on the app name, the account cluster, or a widget (anywhere on the header's content, rather than the empty draggable middle) — to open a widget menu: a quick on/off list of your widgets so you can add or remove them from the bar right there, plus an "Add divider" row that adds a divider to the end of your pinned icons and a "Manage widgets…" row that opens the full Settings → Widgets pane. Toggling a widget keeps the menu open so you can flip several at once. The empty middle of the bar stays a window-drag handle, so right-clicking blank space there shows the OS window menu instead.

Other ways to manage the bar:

  • Recently installed — with the search box empty, the "More" menu shows up to five apps you installed or switched on most recently, newest first, each with a pin button. If you have installed nothing yet it says "No recent installs — type to search" and offers a Browse the Marketplace row. Type in the search box to find any other button the menu holds.
  • Which apps can be pinned — only apps that open as a popup (floating over your current screen) and quick actions can be newly pinned to the bar. Apps that take over the whole window — and the buttons the side bar's tools add — are not in the "More" menu at all; Settings → Widgets shows them with "Full screen apps cannot be pinned to the toolbar". This holds for the pin button, the right-click Pin, the switches in Settings → Widgets, and the automatic pin when you switch an app on. A full-screen app that was pinned before keeps its place until you remove it, and if Auto-Tidy moves it off the bar it stays listed in the "More" menu.
  • When you switch an app on — a popup app is pinned, a message tells you, and its button flashes. A full-screen app is not pinned: the message says "{name} is on" with an Open button that opens it, and nothing flashes. If that app is already pinned, its own button flashes instead.
  • Search the "More" menu — a box at the top shows the six best matches as you type (accent- and case-insensitive), as one list with no headings: a name that matches exactly comes first, then names that start with what you typed, then a word in the name, then the text anywhere in the name, then a match in the button's description. Every row looks the same, whether it opens a popup app or runs a quick action. The box is focused the moment the menu opens, so you can type immediately. Press ArrowDown to move into the results. Clearing the box brings back the Recently installed list.
  • Use the "More" menu from the keyboard — ArrowDown / ArrowUp move between the search box and the rows. Enter picks a row. Escape or Tab closes the menu.
  • Hover for a description — hovering any pinned icon in the bar OR a row in the "More" menu shows a short tooltip describing what that tool does, not just its name. A pinned icon shows its label plus the description; a "More"-menu row shows the description on hover. A button with no description yet (a third-party plug-in) falls back to a short generic tooltip (its name is already shown in the row).
  • Hover-pin shortcut — hovering a button's row in the "More" menu (in Recently installed or in search results) also reveals a small pin icon on the right; click it to pin without opening the right-click menu.
  • Drag to reorder — drag pinned icons left/right to rearrange them.
  • Dividers — a divider is a thin vertical line between pinned icons. To add one, right-click the header bar (for example the app name) and choose Add divider, just above Manage widgets…; it lands at the end of your pinned icons, and you can drag it into place. The "More" menu no longer has a Divider entry. Dividers can be dragged like icons, and are removed by right-clicking one → Remove divider.
  • Settings → Widgets — the full manager: lists Pinned widgets (with up/down reorder + unpin), In overflow menu (pin), and a Removed from header card where each removed button has an Add back button. Reset to defaults restores the default pinned set AND clears all removals.

Header rows, shrinking and scrolling

The header never cuts anything off. When the window gets narrow, it gives way in a fixed order:

  1. The Omniscio name hides and the logo stays, so you never see a half-name like "OMNI…".
  2. The breadcrumb folds to just its back and forward arrows.
  3. Shortcut bars you have set to shrink fold into their "…" menu. By default shortcut bars do not shrink on their own, so you never lose icons into a menu you did not ask for. A folded bar still keeps in view the icons that can only open themselves (CPU burst, Focus Mode, Narration mode, Land queue, Feedback and Bookmarks) beside its "…".

Everything comes back, in the reverse order, as soon as there is room again.

If a row still does not fit, it scrolls sideways. Use the mouse wheel or a trackpad swipe, click the small left and right arrows that appear at the row's ends, or press Tab to walk to a piece that is out of sight and the row slides it into view. The window buttons and the drag area stay put while the row scrolls.

Several rows. Turn on Settings → Lab → Custom header layout and the header can have up to four rows. A row with nothing on it is not shown. With the switch off, the header is a single row as before, but it still shrinks and scrolls.

  • Move a piece: right-click a piece in the header (the logo, breadcrumb, a widget or the shortcut bar), then choose Move to row and pick a row (or New row). Every menu item has a tooltip saying what it does.
  • Move one shortcut icon: right-click the icon and choose Move to row. The icon joins the shortcut bar on that row (a new bar is made if the row has none).
  • Choose what shrinks: right-click a piece that can shrink and open When space is tight: Shrink automatically, Always full, or Always compact.
  • Add a row, or start over: Add a header row and Reset header are in the same right-click menu.
  • Everything in one place: Customize header… (or Settings → Widgets → Header layout) lists every row, with its left and right sides, move buttons, the shrink choice for each piece, Add a row, Remove row and Reset header.

Reset header puts the header back to its original single-row layout.

Every sidebar tool is also a header button

Every tool in the left sidebar — Skills, Cron Jobs, Stats, Tags, and the built-in plug-ins (AI Coaching, KMS, ContextDock, …) — automatically gets its own header button too, and so does every plug-in you install. A side-bar tool's button opens that tool's full panel, so it counts as a full-screen app: it is not in the "More" menu and cannot be newly pinned (one you pinned earlier keeps working). A plug-in that opens as a popup gets a button in the "More" menu that you can pin like any other. New plug-ins are covered automatically — switch one on and its button appears, switch it off and it's gone. (The three sidebar group headers — Agent Tools, Automation, Insights — and tools that already have a dedicated header button, like Recipes, never get a duplicate.)

Removed vs. unpinned vs. feature-off — three different things

  • Unpinned → still one click away in the "More" menu.
  • Removed → gone from the bar and the "More" menu; re-add from Settings → Widgets. The feature still works and is reachable by its other entry points.
  • Feature turned off (in its own settings, e.g. turning Mind Map off) → the button disappears because the whole feature is disabled, not because you removed the icon. Turn the feature back on to see the button again.

Changing the header from AI

An AI working for you over the local control server can rearrange the header exactly as you can by hand:

  • It reads the header first. GET /header/catalog returns every header button the app can draw (built-in buttons, sidebar tools, plug-in buttons and panels, plug-in and script widgets), each with its exact name, label, description, kind, and where it is now — pinned (with its row and side), in the "More" menu, removed, or unavailable because its feature is off. It also lists the header pieces (logo, needs-you count, breadcrumb, view switch, page actions, the shortcut bars) with their row and side, the current row layout, and the setting names that change them.
  • It writes the usual settings. Pinned buttons are pinnedToolbarItems, removed buttons hiddenToolbarItems, the widget order headerBlockOrder, and the row layout headerLayout. A headerLayout change is saved but only drawn while Settings → Lab → Custom header layout is on; the catalog's customLayout.enabled says which, and layoutSource names the setting that decides what you see.
  • A misspelled name is refused. If one of those four writes introduces a name the header does not have, the change is refused before any approval card reaches you, with the unknown name and the closest real one. Names already saved are never re-checked, so a list that still holds a button from a plug-in you turned off goes through. If the app window cannot answer within 3 seconds, the catalog answers "unavailable" and the change is not blocked.
  • A real name in the wrong place is told where it goes. A name the catalog lists but that cannot sit where it was written (a toolbar button put in a headerLayout row, for example) is refused with where it belongs instead: a toolbar button is pinned with pinnedToolbarItems and given a shortcut bar with headerLayout.iconBars; a header piece goes in headerLayout.rows. The refusal carries the name and its belongsIn place in unknownIds. Rows hold pieces only, because a button written into a row would be dropped silently when the header draws.

The list is built by the same code that draws the header, so it cannot drift from what you see. Your own clicks in the app are never name-checked.

How it works

Every toolbar button is one entry in TOOLBAR_ITEMS in src/renderer/src/features/toolbar/toolbar-items.ts ({ id, label, icon, settingsSection?, appPresentation?, … }). Two AppSettings arrays drive placement, both saved in config.json:

  • pinnedToolbarItems — ordered ids shown in the bar (a | marker is a divider). A brand-new install seeds the marquee default (notifications, scratchpads, help, recipes, mobile-access, feedback, settings); existing users keep their own saved bar.
  • hiddenToolbarItems — ids the user removed; filtered out in getVisibleItems() so they leave BOTH the bar and the "More" menu. The settings id is never honored here (the gear can't be removed).
  • headerBlockOrder — the order of the header blocks (the Shortcut bar plus the bare widget blocks). getHeaderBlocks() resolves it defensively (always includes the shortcuts block, skips hidden/unknown ids, appends pinned-but-unlisted widgets); getPinnedEntries(…, excludeWidgetBlocks=true) keeps the widget ids OUT of the pill so they render as standalone bare blocks in AppToolbar via the outer useDragReorder row. Locked by header-widget-contract.md.

Every item carries a hover description. Both surfaces show a "what is this?" tooltip. Static items resolve their copy from TOOLBAR_ITEM_DESCRIPTIONS in src/renderer/src/features/toolbar/toolbar-catalog.ts via toolbarItemDescription(); derived integration buttons get theirs from TOOLBAR_INTEGRATION_DESCRIPTIONS (set on the button in deriveSidebarPluginToolbarItems). The "More"-menu row uses the description as its native title= (the global tooltip interceptor styles it), and the pinned icon shows label + a muted description line via the shared pinnedTooltipContent helper (with <Tooltip multiline>). A guard test requires every static TOOLBAR_ITEMS id to have a non-empty description, so a new toolbar button can't ship the old one-size-fits-all tooltip — add the item's copy to TOOLBAR_ITEM_DESCRIPTIONS when you add the item. The self-contained stateful widgets (Balancer/account, Hardcore, notifications bell, the voice mic, focus/presentation/narration toggles, manage-sessions) keep their own bespoke tooltips.

The "More" menu is a search box, a Recently installed list and a note. getOverflowItems() lists only items canPinToTopNav allows (popup apps and quick actions — anything without appPresentation: 'full'), plus a full app the user pinned that Auto-Tidy demoted; it never includes the divider pseudo-item. Derived side-bar integration buttons carry appPresentation: 'full', and resolveToolbarItem answers the same for an integration: id, so Settings → Widgets and the right-click Pin refuse them too. With an empty query, ToolbarOverflowMenu shows "Recently installed" (up to five popup apps from the appInstallHistory setting that can still be pinned, newest first) or, with none, "No recent installs — type to search" and a "Browse the Marketplace" row. A non-empty query renders searchTopNavItems() (toolbar-search.ts): the command palette's rankPaletteEntries over label and description, capped at TOP_NAV_SEARCH_LIMIT (6), as one flat list. A foot line (app-toolbar-overflow-note) always reads "Full screen apps cannot be pinned to the toolbar". The group headers, the TOOLBAR_GROUPS registry and every item's group were retired on 2026-11-06 (app-presentation-contract.md). Pinning follows src/shared/app-presentation.ts: only items that are not full can be newly pinned. The menu keeps focus in the box on open (autoFocusFirstItem: false), and ArrowDown moves into the rows. Earlier design record: docs/superpowers/specs/2026-11-04-grouped-overflow-menu-design.md. The fresh-install default also ships burstFocusPinMigrationCompleted: true so an old one-time migration can't re-add CPU Burst / Focus Mode to the curated bar. The divider rule and the default bar are locked by toolbar-overflow-grouping-contract.md; everything the menu lists by app-presentation-contract.md.

Sidebar tools become header buttons automatically. Beyond the static TOOLBAR_ITEMS, every amc-builtin sidebar virtual project is derived into a header button (id integration:<id>) from the same live project list the sidebar renders — so the header can never drift from the sidebar, and a new plug-in needs zero per-plug-in wiring. The derivation lives in src/renderer/src/features/toolbar/integration-toolbar-items.ts and is injected into the toolbar helpers' extraItems parameter, so derived buttons pin / unpin / remove through the exact same machinery as the static ones. Its invariants (derived-not-hardcoded; namespaced ids handled by startsWith guards, never switch cases; toolbar-items.ts stays node-safe) are locked by sidebar-plugin-header-parity-contract.md.

The right-click menu is a single component, src/renderer/src/features/toolbar/ToolbarContextMenu.tsx, rendered once at app level (not inside the dropdown). Right-clicking a "More"-menu row keeps that dropdown open behind the context menu — the menu stacks on top instead of the "More" menu vanishing — and because the menu is app-level it survives the dropdown closing later (e.g. when you pick an action); pressing Escape dismisses the context menu first, then the dropdown. It builds its action list from the item definition + where the right-click came from (pinned bar vs. "More" menu). "Go to settings" calls navigateToSettingsProject({ section }) with the item's settingsSection; the handlers live in src/renderer/src/app/useToolbarActions.ts. The Settings → Widgets manager is src/renderer/src/features/toolbar/ToolbarSettings.tsx. The same component also renders a header-background menu (type:'header'): right-clicking the header's no-drag content fires handleHeaderContextMenu — guarded by shouldOpenHeaderContextMenu, which steps aside for existing items (e.defaultPrevented) and text fields — and opens an inline widget add/remove toggle list (built by getHeaderWidgetToggles, same source as Settings → Widgets) plus a "Manage widgets…" escape. The empty drag-middle is deliberately left as a window-drag handle (a -webkit-app-region: drag region does not deliver right-click to the renderer on Windows). Locked by toolbar-context-menu-contract.md (I9–I11).

This is separate from Auto-Tidy (see ui-auto-tidy.md): Auto-Tidy automatically demotes never-used icons from the bar into the "More" menu (still reachable, restored from Settings → Diagnostics → Hidden items). A manual Remove is a full hide and is restored from Settings → Widgets — the two mechanisms are independent and compose cleanly.

The gear held in the bar is the way into every settings page, which open settings covers. If icons you never touch have been quietly moved out of the bar for you, that is a different, automatic mechanism — see Auto-Tidy, and note it only demotes rather than removes. Buttons that also answer to a keystroke list that shortcut on their overflow row, and the whole rebinding surface is on keyboard shortcuts.

  • open-settings.md — the Settings gear and the Settings UI the "Go to settings" action opens
  • ui-auto-tidy.md — automatic decluttering of never-used toolbar icons (demote, not remove)
  • header-widgets.md — the named widgets that sit in the header, and how they are arranged into rows
  • keyboard-shortcuts.md — some toolbar buttons also have a keyboard shortcut shown on their "More"-menu row

Last verified 2026-11-06