Plugin Widgets

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 them from Settings → Widgets.

In development. Off by default. A developer turns it on with the plugin-widgets feature toggle; until then no plugin widget appears anywhere.

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 from Settings → Widgets. Clicking the widget opens its popover — the plugin's own page rendered inside.

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

Settings → Widgets, same as any other header widget. Hiding it is instant and the plugin cannot re-add it.

Disabling or uninstalling the plugin removes its widget immediately — including any update that was in flight at that moment.

For agents

Your plugin needs both the chrome and chrome.widget permissions. They are separate on purpose: being approved to add a header button does not silently grant permission to draw a live widget in the titlebar.

amc.widget.set({
  shape: 'stat',
  value: '87',            // ≤ 8 characters
  label: 'repo health',   // ≤ 16 characters
  tone: 'running',        // a meaning, not a colour
  icon: 'ShieldCheck',    // a name from Omniscio's list
  tooltip: '87/100 across 12 scanned'
})

amc.widget.clear()        // remove it

Call set as often as your own state changes — updates are batched for you, and an unchanged re-push costs nothing.

To give your widget a popover, declare a widget entry point in your manifest:

"ui": { "widget": { "entryPoint": "ui/widget.html" } }

Without one, clicking the widget opens your normal plugin panel instead. Set panel: 'none' in the spec if you want a pure indicator that isn't clickable.

Keep the popover page small and fast — it renders in a 320×256 frame, so it should show one focused thing, not your whole dashboard.

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.