Wizget

Widget reference

How to build a Wizget widget with your AI — every field, view, source and option.

A Wizget widget is one JSON object: where its data comes from, and which built-in components show it. No code, no CSS, no HTML — your AI writes the JSON, Wizget renders it natively and keeps it fresh. Two ways to get it onto your desktop:

Connecting over MCP

The server listens on 127.0.0.1 only, speaks streamable HTTP, and every request must carry the per-install token in the URL. The full address is in the app under Custom → Connect your AI, and in mcp.json in Wizget's app data folder.

For Claude Code the app can register itself — the Connect Claude button runs claude mcp add-json --scope user wizget … for you. For other clients, add an http-type MCP server with the URL shown in the app.

Tools

ToolWhat it does
list_widgetsEvery widget on the desktop: label, spec id, x/y, size, pinned.
create_widgetValidate and save a spec, then place it. Args: spec (the widget/1 object), optional x, y, width, height.
update_widgetReplace a custom spec; every widget using it reloads in place.
remove_widgetClose a widget window. Arg: label.
delete_specDelete a saved custom spec. Arg: spec (custom:<id>).
move_widgetMove a widget. Args: label, x, y (logical px from the screen's top-left).
resize_widgetResize a widget. Args: label, width, height.
pin_widgetPin or unpin so it can't be dragged. Args: label, pinned.
arrange_widgetsTidy every widget into neat, non-overlapping rows.
refresh_widgetReload a widget in place. Arg: label.
get_specRead a spec — a gallery id (to fork) or custom:<id>.
list_galleryIds of the built-in widgets, for forking.
list_customIds and names of your custom widgets.
validate_specCheck a spec without placing it — returns the errors to fix.

Two resources are always readable: wizget://guide (this authoring guide, as markdown) and wizget://schema (the JSON schema). Built-in gallery widgets are fork-only — get_spec hands over a copy to change under a new id; the originals can't be modified through MCP. Widgets and their positions are real desktop state, so every mutation you make is saved and restored on restart.

The widget/1 spec

Every spec is an object with "schema": "widget/1" and these top-level fields:

FieldWhat it is
idKebab-case unique id. Saved customs become custom:<id>.
name, description, categoryShown in the gallery and on the widget. Category is one of the gallery's.
sizeBase size: 1x1, 2x1, 2x2, 3x1, 3x2. Users can still resize the window; pick the size the content fits.
toneThe accent colour: canary, green, red, blue, orange, violet, teal, pink, gray. One tone per widget — it drives the icon tile, bars and main button.
sourcesNamed data feeds — native (built into the app) or http (a web API you describe). See below.
dataDerived entries: read from a source (or another entry) and run ops — window, filter, sum, groupBy… See Data steps.
viewThe card's layout tree — Stack, Row, Label, Metric… See Views.
sampleData the preview shows before the first real fetch. Keep it in step with the view.
credentialsKeys the widget needs — never the keys themselves. Each entry: label, help (where in the provider's dashboard to make a read-only key), placeholder, link (the page that hands out keys).
refreshHow often to re-fetch, e.g. "15m". At least a minute.
activeOptional: keep updating while the widget is in the background.

Inside view, any text, value or caption can interpolate data: {{source.field}}, {{dataEntry}}, {{param.name}} for setup answers, and filters like {{value|money}}. Nodes can also bind a source field directly.

Views — the components a widget can show

NodeWhat it isKey fields
Stack, RowVertical / horizontal layoutchildren, gap, wrap, align
LabelSmall muted captiontext
TextA line of texttext, size (sm, md, lg)
MetricOne big number, optional change arrow and captionvalue, delta, caption, size (md, lg, xl)
ProgressA bar pinned to the card's bottomvalue, max
RingA ring with a label in the middlevalue, max, text
DotsSteps as dots (Pomodoro rounds)value, max
GridA dense filling grid (year in days)value, max
GaugeA semicircle with a needlevalue, max, text
Sparkline, BarChartA line / bars from a seriesseries, y
HeatGridA contribution-style activity gridseries (rows with t, v)
ListRows of {title, subtitle?, value?}items, limit, placeholder
LogoA brand mark or icon in a tileicon (logo:github, ph:timer, or a bound data: image)
ButtonA control that runs a source actionaction, icon, text, variant (round, soft, ghost), size
InputText/number field, or a slideraction, kind (text, number, slider), value, placeholder
NotesA text area that saves as you typevalue, action, placeholder
ChecklistTick-box rows {id, title, done}items, action (toggle), remove, limit, placeholder
TimelineA day on one linefrom, to (hours), activity, blocks, sun
AnalogClockAn analog face with sweeping handsvalue (bind to hands), tone
FlipClock, SegmentClockSplit-flap / seven-segment digitsvalue, tone
WeekStripThis week as a strip, today lititems ({title, value, today}), tone
GuideAn inline step-by-step help cardsteps
HtmlRaw markup in a shadow root — the escape hatch for any designhtml, css (with {{field}} templates and {{#each list}}…{{/each}} loops)

The default theme covers most widgets; a spec's optional theme restyles the card itself — bg, fg, accent, font (webfonts via @import in css), radius, pad, and raw css scoped under .wg. Html nodes take it further: arbitrary markup with live data binding, remote images and its own isolated CSS — that's how an AI recreates a design you show it.

Icons are Phosphor names (ph:timer) or logo: brand marks. A Button's or Input's action runs a source action — {"action": {"source": "timer", "do": "toggle"}} — nothing else can run.

Native sources

{"kind": "native", "id": "<id>", "params": {…}}. A source with setup asks the user once, on the widget; mark a source "optional": true to make setup skippable. Extra needs on any native source become questions whose answers arrive as params.

SourceGivesSetup / actions
clockCurrent time as ISO — format with |time, |date:long…—
clock.zoneTime in another place: value, offset, hands for AnalogClockzone
time.todayToday's date fields + 7 days for WeekStrip—
time.progressFraction of day/month/year goneparam of
countdownDays until a dateparams to, label
focus.timerCountdown timer: remaining, progress, statustoggle, reset, add
focus.stopwatchElapsed time, lapstoggle, lap, reset
focus.pomodoroFocus/break rounds: phase, remaining, roundtoggle, skip, reset
focus.logToday's finished rounds as Timeline blocks—
focus.todosA to-do list kept on the PCadd, toggle, remove, clearDone
focus.notesOne saved noteset
settingA value the user types once (a monthly goal…)needs value
calendar.icalUpcoming events from a private iCal linksetup url
money.currencyECB rates conversion: rate, resultfrom/to; amount, swap
system.screenTimeTime at the computer today + per-app list—
sky.sunSunrise/sunset + sun position 0–1city
sky.weatherTemp now, week highs, forecast (Open-Meteo, no key)city
system.cpu, system.ramLoad 0–1 + top apps—
system.batteryLevel 0–1, state, charging—
system.devicesThis computer and connected Bluetooth devices (each earbud and case): list of level, charging, icon—
system.networkDown/up speed + 30-sample series—
system.diskFree space on the system drive—
system.tempCPU °C where a sensor reports one—
system.brightnessBrightness 0–1set (slider)
system.themeDark/light modetoggle
system.osDesktop shortcuts stateopen (quickSettings, notifications, showDesktop, tray, language, keyboard, taskManager, dnd)
media.nowPlayingWhatever's playing: title, artist, art, positiontoggle, next, prev
audio.volumeSpeaker volume 0–1, mutedset, toggle
audio.micMic mute statetoggle
apps.notifsWindows notification count for one appapp
apps.runningApps with open windowsstart (Start/Launchpad)
files.recentRecently opened filesopen (path)
files.binRecycle bin count and sizeempty
files.openOpen a path / URL / searchgo (text)
files.launchLaunch an app by namego (name)
files.shotScreenshot via the OS toolgo (region, window, screen)
files.wallpaperA photo picker that sets the wallpaperset
ai.claudeCode (alias ai.claude), ai.codex, ai.gemini, ai.grok, ai.cursor, ai.opencode, ai.deepseek, ai.glmHow much of an AI plan is left — read from the sign-ins already on the PC. Same shape each: plan, first/second windows, list, staledeepseek/glm take a key
ai.limitsEvery provider at once, flattened to the two with dataparams a/b

The http source — any web API

Describe one request; Wizget makes it, pages through the reply, and maps rows:

"credentials": {
  "cred_stripe": { "label": "Stripe", "help": "Developers → API keys → Create restricted key, Read on Balance.", "placeholder": "rk_live_…", "link": "https://dashboard.stripe.com/apikeys" }
},
"sources": {
  "pay": {
    "kind": "http",
    "request": {
      "url": "https://api.stripe.com/v1/balance_transactions",
      "query": { "limit": 100, "created[gte]": "{{now-60d|unix}}" {"}"},
      "auth": { "credential": "cred_stripe", "as": "bearer" }
    },
    "paginate": { "cursor": { "param": "starting_after", "from": "$.data[-1].id" }, "while": "$.has_more", "max": 10 },
    "shape": "series",
    "map": { "items": "$.data", "t": "created", "v": "net|cents", "currency": "currency" }
  }
}

Data steps

Each data entry reads from a source or earlier entries (several merge as rows), then runs ops in order:

StepDoes
windowKeep rows in last ("30d") or since the start of today/week/month/year
filterKeep rows whose field is eq/ne a value or in a list
sort, topNBy field (desc), or the n largest
groupByOne row per day/week/month, summed; with last empty days are 0
sum, avg, min, max, count, first, lastOne number from the rows (field, default v)
streakDays in a row with v > 0, ending today
periodChangeThis period vs the one before, as a fraction (0.18 = up 18%)
paceMonth-so-far total projected to the whole month
ratioThis value divided by another entry's ("of": "goal.value")

A complete example

{
  "schema": "widget/1",
  "id": "my-mrr",
  "name": "MRR",
  "description": "Monthly recurring revenue",
  "category": "money",
  "size": "2x1",
  "tone": "green",
  "credentials": {
    "cred_stripe": { "label": "Stripe", "help": "Developers → API keys → restricted key, Read on Subscriptions.", "placeholder": "rk_live_…" }
  },
  "sources": { "subs": { "kind": "http", "request": { "url": "https://api.stripe.com/v1/subscriptions", "query": { "limit": 100, "status": "active" }, "auth": { "credential": "cred_stripe", "as": "bearer" } }, "shape": "list", "map": { "items": "$.data" } } },
  "data": { "count": { "from": "subs", "ops": [{ "op": "count" }] } },
  "sample": { "count": 42 },
  "view": {
    "type": "Stack", "gap": 8,
    "children": [
      { "type": "Label", "text": "Active subscriptions" },
      { "type": "Metric", "value": "{{count}}", "size": "xl" {"}"}
    ]
  }
}

Tips

The canonical reference for AIs is spec/GUIDE.md in the repository, bundled inside the app and served as the wizget://guide MCP resource. The paste-anywhere version is SKILL.md.