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:
- Over MCP — Wizget runs a local MCP server. Point any MCP-capable AI at it and the AI can create, edit, move, resize and remove widgets itself, live.
- Paste the JSON — for AIs without MCP. Copy the widget skill from the app (Custom → Copy widget skill) or download SKILL.md, send it to any AI, and paste its reply into Custom → New from AI output. The editor pulls the JSON out of the reply on its own.
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
| Tool | What it does |
|---|---|
list_widgets | Every widget on the desktop: label, spec id, x/y, size, pinned. |
create_widget | Validate and save a spec, then place it. Args: spec (the widget/1 object), optional x, y, width, height. |
update_widget | Replace a custom spec; every widget using it reloads in place. |
remove_widget | Close a widget window. Arg: label. |
delete_spec | Delete a saved custom spec. Arg: spec (custom:<id>). |
move_widget | Move a widget. Args: label, x, y (logical px from the screen's top-left). |
resize_widget | Resize a widget. Args: label, width, height. |
pin_widget | Pin or unpin so it can't be dragged. Args: label, pinned. |
arrange_widgets | Tidy every widget into neat, non-overlapping rows. |
refresh_widget | Reload a widget in place. Arg: label. |
get_spec | Read a spec — a gallery id (to fork) or custom:<id>. |
list_gallery | Ids of the built-in widgets, for forking. |
list_custom | Ids and names of your custom widgets. |
validate_spec | Check 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:
| Field | What it is |
|---|---|
id | Kebab-case unique id. Saved customs become custom:<id>. |
name, description, category | Shown in the gallery and on the widget. Category is one of the gallery's. |
size | Base size: 1x1, 2x1, 2x2, 3x1, 3x2. Users can still resize the window; pick the size the content fits. |
tone | The accent colour: canary, green, red, blue, orange, violet, teal, pink, gray. One tone per widget — it drives the icon tile, bars and main button. |
sources | Named data feeds — native (built into the app) or http (a web API you describe). See below. |
data | Derived entries: read from a source (or another entry) and run ops — window, filter, sum, groupBy… See Data steps. |
view | The card's layout tree — Stack, Row, Label, Metric… See Views. |
sample | Data the preview shows before the first real fetch. Keep it in step with the view. |
credentials | Keys 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). |
refresh | How often to re-fetch, e.g. "15m". At least a minute. |
active | Optional: 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
| Node | What it is | Key fields |
|---|---|---|
Stack, Row | Vertical / horizontal layout | children, gap, wrap, align |
Label | Small muted caption | text |
Text | A line of text | text, size (sm, md, lg) |
Metric | One big number, optional change arrow and caption | value, delta, caption, size (md, lg, xl) |
Progress | A bar pinned to the card's bottom | value, max |
Ring | A ring with a label in the middle | value, max, text |
Dots | Steps as dots (Pomodoro rounds) | value, max |
Grid | A dense filling grid (year in days) | value, max |
Gauge | A semicircle with a needle | value, max, text |
Sparkline, BarChart | A line / bars from a series | series, y |
HeatGrid | A contribution-style activity grid | series (rows with t, v) |
List | Rows of {title, subtitle?, value?} | items, limit, placeholder |
Logo | A brand mark or icon in a tile | icon (logo:github, ph:timer, or a bound data: image) |
Button | A control that runs a source action | action, icon, text, variant (round, soft, ghost), size |
Input | Text/number field, or a slider | action, kind (text, number, slider), value, placeholder |
Notes | A text area that saves as you type | value, action, placeholder |
Checklist | Tick-box rows {id, title, done} | items, action (toggle), remove, limit, placeholder |
Timeline | A day on one line | from, to (hours), activity, blocks, sun |
AnalogClock | An analog face with sweeping hands | value (bind to hands), tone |
FlipClock, SegmentClock | Split-flap / seven-segment digits | value, tone |
WeekStrip | This week as a strip, today lit | items ({title, value, today}), tone |
Guide | An inline step-by-step help card | steps |
Html | Raw markup in a shadow root — the escape hatch for any design | html, 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.
| Source | Gives | Setup / actions |
|---|---|---|
clock | Current time as ISO — format with |time, |date:long… | — |
clock.zone | Time in another place: value, offset, hands for AnalogClock | zone |
time.today | Today's date fields + 7 days for WeekStrip | — |
time.progress | Fraction of day/month/year gone | param of |
countdown | Days until a date | params to, label |
focus.timer | Countdown timer: remaining, progress, status | toggle, reset, add |
focus.stopwatch | Elapsed time, laps | toggle, lap, reset |
focus.pomodoro | Focus/break rounds: phase, remaining, round | toggle, skip, reset |
focus.log | Today's finished rounds as Timeline blocks | — |
focus.todos | A to-do list kept on the PC | add, toggle, remove, clearDone |
focus.notes | One saved note | set |
setting | A value the user types once (a monthly goal…) | needs value |
calendar.ical | Upcoming events from a private iCal link | setup url |
money.currency | ECB rates conversion: rate, result | from/to; amount, swap |
system.screenTime | Time at the computer today + per-app list | — |
sky.sun | Sunrise/sunset + sun position 0–1 | city |
sky.weather | Temp now, week highs, forecast (Open-Meteo, no key) | city |
system.cpu, system.ram | Load 0–1 + top apps | — |
system.battery | Level 0–1, state, charging | — |
system.devices | This computer and connected Bluetooth devices (each earbud and case): list of level, charging, icon | — |
system.network | Down/up speed + 30-sample series | — |
system.disk | Free space on the system drive | — |
system.temp | CPU °C where a sensor reports one | — |
system.brightness | Brightness 0–1 | set (slider) |
system.theme | Dark/light mode | toggle |
system.os | Desktop shortcuts state | open (quickSettings, notifications, showDesktop, tray, language, keyboard, taskManager, dnd) |
media.nowPlaying | Whatever's playing: title, artist, art, position | toggle, next, prev |
audio.volume | Speaker volume 0–1, muted | set, toggle |
audio.mic | Mic mute state | toggle |
apps.notifs | Windows notification count for one app | app |
apps.running | Apps with open windows | start (Start/Launchpad) |
files.recent | Recently opened files | open (path) |
files.bin | Recycle bin count and size | empty |
files.open | Open a path / URL / search | go (text) |
files.launch | Launch an app by name | go (name) |
files.shot | Screenshot via the OS tool | go (region, window, screen) |
files.wallpaper | A photo picker that sets the wallpaper | set |
ai.claudeCode (alias ai.claude), ai.codex, ai.gemini, ai.grok, ai.cursor, ai.opencode, ai.deepseek, ai.glm | How much of an AI plan is left — read from the sign-ins already on the PC. Same shape each: plan, first/second windows, list, stale | deepseek/glm take a key |
ai.limits | Every provider at once, flattened to the two with data | params 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" }
}
} - Keys. Declare them in
credentials(name themcred_*) — never inline. The user pastes once; it's stored in the OS keychain and only sent to the hosts this widget calls.auth.asisbearer,basic,header:<Name>orquery:<name>."optional": trueonauthmeans "use the key if there is one, else go anonymous". - Request.
method(GET/POST),url(https only),query,headers,body. Templates:{{now}},{{now-30d}},{{now-month}}with|iso(default),|unix,|ms,|date; plus{{param.name}}for setup answers. - Setup questions.
needs:{"param": "mode", "label": "Live or test mode", "options": ["live", "test"]}or aplaceholderfor free text.paramsgives defaults. - Paging. At most
maxrequests (default 5, up to 20), whilewhileholds:cursor(passfrom's value asparam),page(numbers fromstartuntil a short page), ornext(follow the link at a path until missing). - Map.
itemslocates the rows; every other key reads a field — a path, arithmetic (total - refunded,close / prev - 1), a conversion after|(cents,number,unix,date,lower,re:<pattern>), or=USDfor a fixed value. Name the timetand the amountv. - Shapes.
seriesandlistgive rows;metricandprogressread one reply where each map key is a path into it.
Data steps
Each data entry reads from a source or earlier entries (several merge as rows), then runs ops in order:
| Step | Does |
|---|---|
window | Keep rows in last ("30d") or since the start of today/week/month/year |
filter | Keep rows whose field is eq/ne a value or in a list |
sort, topN | By field (desc), or the n largest |
groupBy | One row per day/week/month, summed; with last empty days are 0 |
sum, avg, min, max, count, first, last | One number from the rows (field, default v) |
streak | Days in a row with v > 0, ending today |
periodChange | This period vs the one before, as a fraction (0.18 = up 18%) |
pace | Month-so-far total projected to the whole month |
ratio | This 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
- Start from the closest gallery widget —
list_gallery+get_specover MCP — and change it. Built-ins are forked, never edited. - Put the one number that matters first and biggest; labels and captions stay small and muted.
- A
2x1holds a label, one big value and a row of buttons — don't cram. - Keep
samplein step with the view so previews look right.
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.