Script Widgets

What it is

You write a small script — it watches your builds, a price, a to-do count, anything — and it tells Omniscio what to show. Omniscio draws a little widget in the top bar next to the built-in ones, and updates it every time your script sends a new value.

No plugin, no manifest, no install: one web request shows it, another updates it, another removes it. If you want a widget that opens its own page when clicked, build a plugin widget instead (plugin-widgets.md).

Where to find it

In the top titlebar, beside the other header widgets, as soon as a script sends one. Hover it to see its label — always "<name> · from a script" — followed by whatever tooltip text your script sent. Drag it left or right like any titlebar widget.

How it behaves

Sending one

Your script needs your Omniscio key, which lives in ~/.amc/cli-token on your computer.

TOKEN=$(cat ~/.amc/cli-token)
curl -s -X PUT http://127.0.0.1:19519/widgets/builds \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Builds","shape":"stat","value":"3","label":"failing","tone":"error","tooltip":"3 of 12 builds red"}'

The same call again with a new value updates it. Remove it with:

curl -s -X DELETE http://127.0.0.1:19519/widgets/builds -H "Authorization: Bearer $TOKEN"

A Node script that refreshes a widget every ten seconds:

const fs = require('node:fs')
const os = require('node:os')
const token = fs.readFileSync(`${os.homedir()}/.amc/cli-token`, 'utf8').trim()

async function show(value) {
  await fetch('http://127.0.0.1:19519/widgets/open-tasks', {
    method: 'PUT',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: 'Open tasks', shape: 'stat', value: String(value), tone: 'neutral', icon: 'ListChecks' })
  })
}

setInterval(() => show(Math.floor(Math.random() * 10)), 10_000)

What a widget can contain

The same short description plugin widgets use — Omniscio picks every colour, font and pixel:

Field	What it is
name	Your widget's name, up to 24 characters — shown as "<name> · from a script"
shape	stat, pill, dot, gauge or sparkline
value	Up to 8 characters
label	Up to 16 characters
tooltip	Up to 120 characters, shown after the app's own label
tone	A meaning — neutral, running, needs-you, error, ember or accent
icon	An icon name from Omniscio's list, such as Zap, Bell, ListChecks or ShieldCheck
progress	0 to 1, for a gauge
series	Up to 32 numbers, for a sparkline

Anything else is refused with a plain reason. The short text limits are deliberate: the titlebar sits next to your account switcher, so nothing up there may be long enough to fake "Your session expired, sign in again".

Limits and safety

• Only your own key works. An AI session's limited key is refused, so no agent can change your titlebar with its own credentials.
• Six at a time. A seventh is refused until you remove one; nothing is ever pushed out.
• Update as often as you like, within reason. Omniscio redraws at most four times a second and ignores an update that changes nothing; one widget may update 60 times a minute.
• Cleared on restart. Script widgets live only while the app runs — a script just keeps sending.
• Desktop only. They never appear on a paired phone.

Removing or turning them off

Right-click a script widget and choose Remove to hide it; it stays hidden even while the script keeps sending. Use Undo on the toast that appears to bring it straight back — a removed widget is not yet listed in Settings → Widgets, so that toast is the way to undo it. To turn off every titlebar widget — plugin and script alike — switch Header Widgets off in Settings; while it is off, scripts get a plain "switched off" answer.

For agents

Routes, gating and every field: the omniscio-control skill's script-widgets spoke. Write calls are full-trust only (cliTokenOnly), self-rate-limited per widget id, and answer 201 created / 200 updated / 400 invalid / 403 switched off / 409 at the cap of six / 429 over budget. The rules that must stay true live in the script widget contract (.claude/memory/contracts/script-widget-contract.md).

Related

Plugin widgets (plugin-widgets.md) are the richer sibling — same faces, plus a click-to-open page drawn by the plugin. The built-in titlebar widgets and how to reorder them are in header-widgets.md.