---
title: Plugin Widgets
---

# 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](header-widgets.md) (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.

```js
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:

```json
"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](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](repoguard.md). A widget is one of the UI contributions a plugin
makes, alongside the toolbar and menu items in [plugin-ui-access.md](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](plugin-settings-panel.md).