Customize the header toolbar

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 one click away in 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 drops down every other available button that isn't pinned. This is the "overflow" menu, and its rows are organized into labeled sections (Notes & capture · Sessions & workflow · Notifications & focus · System & diagnostics · Help & support · Integrations · Plugins · Experimental) so a long list stays scannable instead of one flat scroll. Only sections that have a button show a header; the "Add divider" row always sits at the very bottom. A search box pinned at the top filters the rows by name as you type — handy when the list is long.

Beyond the bar itself, the header's right side is a row of draggable blocks: the whole Shortcut bar is one block, and the Balancer (account) and Hardcore widgets sit outside the bar as their own bare blocks (no pill background). 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; Support Chat → Channels; 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 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:

• Search the "More" menu — a box at the top filters the rows by name as you type (accent- and case-insensitive). It's focused the moment the menu opens, so you can type immediately; press ArrowDown to move into the results, and clearing the box restores the full grouped list.
• 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 row in the "More" menu 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 — the "More" menu has a Divider entry; pinning it inserts a vertical separator into the bar so you can group icons. Right-click a divider → 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.

Every sidebar tool is also a header button

Every tool in the left sidebar — Skills, Cron Jobs, Stats, Tags, and any plug-in you switch on (AI Coaching, KMS, ContextDock, …) — automatically gets its own header button too. These derived buttons start in the "More" menu; pin the ones you reach for often, exactly like any other button, and clicking one opens that tool's panel just like clicking its sidebar row. 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. unchecking Support Chat) → 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.

How it works

Every toolbar button is one entry in TOOLBAR_ITEMS in src/renderer/src/features/toolbar/toolbar-items.ts ({ id, label, icon, group, settingsSection?, … }). 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 account/hardcore 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 grouped. Each item carries a group, and an ordered TOOLBAR_GROUPS registry names the sections + their render order. A pure groupOverflowItems() helper arranges the flat overflow list into labeled sections (keeping registry order within each, dropping empties, and pinning the "Add divider" row to the bottom) — it never adds or drops an item, so grouping is display-only. The Experimental section fills itself from any item flagged as an in-development (Lab) feature; derived integration:<id> buttons fall into Integrations. Section headers are non-interactive (role="group"), so keyboard navigation still steps only through the real buttons. A search box at the top filters the flat list by label (via the shared foldForSearch) before grouping — so grouping stays pure and empty sections simply drop out; the menu keeps focus in the box on open (autoFocusFirstItem: false) and ArrowDown moves into the results. 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. All of this is locked by toolbar-overflow-grouping-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.

Related

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)
• keyboard-shortcuts.md — some toolbar buttons also have a keyboard shortcut shown on their "More"-menu row