---
title: Customize the header toolbar
---

# 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 · 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](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](open-settings.md) 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](ui-auto-tidy.md), 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](keyboard-shortcuts.md).

- [open-settings.md](open-settings.md) — the Settings gear and the Settings UI the "Go to settings" action opens
- [ui-auto-tidy.md](ui-auto-tidy.md) — automatic decluttering of never-used toolbar icons (demote, not remove)
- [keyboard-shortcuts.md](keyboard-shortcuts.md) — some toolbar buttons also have a keyboard shortcut shown on their "More"-menu row