Plugin Widgets
A plugin widget is a small live indicator a plugin can show in Omniscio's titlebar — a count, a score, a status dot — with a popover holding the plugin's own page. Covers the five shapes, the colours a plugin may pick, what a plugin cannot draw, and how to turn one off.
On this page
What it is
A plugin widget is a small live indicator a plugin can show in Omniscio's top titlebar — a build count, a repo health score, a coloured dot when something needs attention. Clicking it opens a popover with the plugin's own page inside.
They sit alongside the built-in header widgets (Account, Hardcore, Usage) and behave the same way: drag them left and right to reorder, or hide one with right-click → Remove (the toast's Undo brings it back).
On by default. Switch Header Widgets off in Settings to hide every plugin and script widget at once. Your own scripts can show widgets here too — see script-widgets.md.
Where to find it
In the top titlebar, next to the built-in header widgets, once a plugin that declares one is running and the feature is on. Reorder it by dragging it left or right, exactly as you would any other titlebar widget, and hide it with right-click → Remove. Clicking the widget opens its popover — the plugin's own page rendered inside.
A plugin shows one widget in the titlebar: the first one it declares. A plugin that offers several widgets for the widget sidebar can have the others there, but only its first reaches the titlebar.
How it behaves
What a plugin can and cannot do
This is the part worth understanding, because it is deliberate.
Omniscio draws the widget itself. The plugin does not send pixels — it sends a short description: a shape, a number, a short label, a meaning like "error" or "running", and the name of an icon. Omniscio picks the actual colour, the font, the spacing, and the icon image.
So a plugin cannot:
- draw its own graphics, HTML, or images in the titlebar
- choose a colour (it picks a meaning; Omniscio picks the shade)
- write a sentence — the number is capped at 8 characters and the label at 16
- use an icon Omniscio reserves for itself, like the Account or Usage glyph
- hide the fact that it is the one showing you something
That last one matters most. The titlebar is where your account switcher and settings gear live, so people reasonably read anything up there as Omniscio talking. A plugin that could draw freely there could fake "Your session expired, sign in again" right next to the real account control — and by the time you'd think to disable the plugin, your password would already be gone.
Inside the popover, the plugin draws whatever it likes. That is safe, because you deliberately opened it and it carries a header naming the plugin that the plugin cannot restyle, hide, or draw over.
The five shapes
| Shape | Looks like | Good for |
|---|---|---|
stat |
a number with a small label under it | a count or a score |
pill |
a rounded chip with a word in it | a short status |
dot |
a small coloured circle | "everything's fine" / "something's wrong" |
gauge |
a thin bar filled to a percentage | a quota or progress |
sparkline |
a tiny trend line | a value moving over time |
Colours
A plugin picks a meaning, not a colour, and Omniscio maps it onto the same palette the rest of the app uses — so a plugin's "error" is the same red as a real error, and it can never invent a shade that mimics one.
neutral · running · needs-you · error · ember · accent
Example — RepoGuard
RepoGuard ships the reference implementation. It shows your fleet health score as a
stat, coloured green above 80, amber above 60, red below. Clicking it opens a
compact worst-first list of your scanned repos. When nothing has been scanned yet it
clears the widget entirely rather than showing a 0, which would read as a failing
score instead of "no data".
Turning one off
Right-click → Remove, same as any other header widget. Hiding it is instant and the plugin cannot re-add it; use the toast's Undo to bring it back. To hide every widget, switch Header Widgets off in Settings.
Disabling or uninstalling the plugin removes its widget immediately — including any update that was in flight at that moment.
Reading a header widget from Omni or a dashboard
A plugin widget is not only something you look at. With the local API the whole set is readable:
GET /widgets → { ok: true, data: { widgets: [...], max: 6, pluginWidgets: [...] } }
pluginWidgets carries every plugin widget currently in the titlebar — its plugin, the widget's id,
the plugin's name, and the same short description the app draws (shape, value, label, tone). An AI
session talking to an Omni session reads it with that session's own key; an ordinary agent session
gets a refusal, because this is part of what a person's Omni may see and a passing script may not.
A Mission Control dashboard can show one too: add a Header widget from the dashboard's Add widget menu, then pick which plugin's widget it shows in its settings. The tile draws the same face as the titlebar and names the plugin underneath, so it is always clear whose reading it is. A published snapshot has no live plugin data, so it shows a sentence saying so.
Related
Plugin widgets share the titlebar with the built-in ones described in header-widgets.md, which is where to look for the Account, Hardcore and Usage widgets and for the mechanics of reordering or hiding anything up there. The reference implementation is repoguard.md. A widget is one of the UI contributions a plugin makes, alongside the toolbar and menu items in plugin-ui-access.md, and a plugin that wants a full screen of its own rather than a popover should see plugin-settings-panel.md.
Every plugin widget is also listed in the Widget Library, where it can be added to or removed from the titlebar, and where a widget-only plugin an AI session built for you can be loaded.
Last verified 2026-11-15