agent-widgets 0.4.0

A gallery with a reason to install

Seven ready-made widgets ship with the engine. aw gallery lists them, aw gallery add <id> copies one into your workspace — feed, samples and tests included.

• ai-limits — what is left of your Claude and Codex windows, the pace against an even spend, a forecast of when you run out and a week of history
• agents — which Claude Code and Codex sessions wait for you, went silent or are working, with live timers
• github — contribution year, streaks, the review queue, the last 14 days
• ai-spend — your Claude Code tokens at API prices: today, week, month, by model
• tiles — 2048 played with widget buttons
• system-pulse and focus, redrawn

aw gallery add ai-limits && aw feed run ai-limits && aw ship ai-limits

Big widgets that earn their size

The preview now measures the largest empty area of every size and warns with UNDERFILLED; the sheet outlines the hole. Templates fill the sizes they declare, and the skill is rewritten around a ladder — each size answers a bigger question. On the same brief a fresh agent went from an extra large widget that was 71 % empty to 15 %.

Three more ways to install

• npm — npm install -g agent-widgets, or straight into an MCP config: npx -y agent-widgets mcp --workspace ~/Widgets
• Claude Desktop — download agent-widgets-0.4.0.mcpb below and open it
• MCP registry — io.github.Surdeddd/agent-widgets

aw_init creates the workspace from an MCP client, so clients without a shell can start from an empty folder.

Also

• Feeds that print the same output while nothing changed cost no reloads; the gallery feeds are built that way, and a change reaches the desktop about a second after it is published.
• System date text follows the widget language; context.locale for your own formats.
• AWSparkline(values, range: 0...100) pins the scale of a percentage.
• Sample dates can be offsets from now: "+90m", "-4m".
• SAMPLE_NOT_LOCALIZED only for feeds that read AW_LANG.

Full list: CHANGELOG.

Upgrade: brew upgrade agent-widgets, or git pull && make install.

agent-widgets 0.3.1

Two fixes for problems that shipped in 0.3.0. If you installed with Homebrew, upgrade: aw new did not work there.

brew update && brew upgrade surdeddd/tap/agent-widgets

Fixed

• aw new behind a symlink. A Homebrew install keeps the engine behind a symlink (opt/agent-widgets/libexec → Cellar/…), and aw new failed there with UNEXPECTED … couldn’t be copied: the created paths were cut at the wrong place once the symlink was resolved. It now works from any install location.
• Widgets with a running timer settle on the desktop. aw ship and aw dev compared captured frames byte by byte, so a Text(date, style: .timer) or an AWCountdown, which changes every second, never looked still: every window waited its full 30 s and the run ended unverified with SHOT_UNCHANGED although the slot had redrawn within a second. Frames are now compared as pictures: a ticking clock is neither a redraw nor a widget that keeps redrawing, and the same ticking widget is still reported as unchanged. On a real desktop the capture of four sizes went from 120 s to under 7 s.

How it was checked

• Both bugs are reproduced by tests that fail on 0.3.0: an engine reached through a symlink, and real captures of a dev slot with six live timers.
• aw new was run against the released 0.3.0 and the fixed build behind the same symlink: exit 1 before, six files created after.
• 219 engine tests and 69 kit tests, swiftlint --strict clean, CI green. The Homebrew formula test now creates a workspace and a widget instead of only printing the version.

agent-widgets 0.3.0

Your agent's widget work now finishes in any MCP client, installs in one step and tells the truth about the desktop.

brew install surdeddd/tap/agent-widgets

In Claude Code, the plugin brings the skill and the MCP server:

/plugin marketplace add Surdeddd/agent-widgets
/plugin install agent-widgets@agent-widgets

	0.2	0.3
aw_ship in Codex or Claude Desktop	cut off after 60 s	answers within 45 s with a job id, aw_wait returns the result
Progress and cancel	none, cancel ignored	a notification per stage, cancel stops the build
Install	git clone + make install	Homebrew or the Claude Code plugin
Tool metadata	read-only hint	titles, hints, output schemas with the summary inside
A wrong argument	missing "id"	INVALID_ARGUMENT with the reason
A dev slot behind windows	SHOT_MISMATCH 9 %	WIDGET_HIDDEN: show the desktop, then aw shot --dev

What's new

• Long MCP calls fit every client. aw_ship, aw_dev, aw_slot and aw_feed_run run as jobs: a call answers within its budget (none for Claude Code, 45 s for other clients, aw mcp --call-budget) with a job id and stage, and the new aw_wait returns the final result. Codex and Claude Desktop, which stop a tool call after 60 s, now get through a ship.
• Progress notifications for every stage of a long call, and a pulse every 10 s.
• Cancelling an MCP call stops its work and sends no reply: a build is interrupted, waits end, an install swap already under way still finishes.
• Claude Code plugin: /plugin marketplace add Surdeddd/agent-widgets, then /plugin install agent-widgets@agent-widgets installs the skill and the MCP server and asks for the widgets folder. A SessionStart hook explains how to install aw when it is missing.
• Every MCP tool has a title, read-only, destructive, idempotent and open-world hints, and an output schema. The structured content carries the reply text under summary, because Claude Code shows the model that JSON instead of the text block.
• MCP arguments are checked against the input schema: unknown names, wrong types and missing values are INVALID_ARGUMENT. Invalid widget ids are WIDGET_ID_INVALID everywhere, unknown jobs JOB_UNKNOWN.
• Hints in MCP replies name the tool to call (aw_explain {"code": "…"}) and mark commands that only exist in a shell.
• A dev slot covered by windows is WIDGET_HIDDEN instead of a misleading SHOT_MISMATCH: macOS does not draw desktop widgets that are not on screen, so their capture is an empty frame. aw dev no longer waits 30 s for a redraw that cannot happen, aw slot waits until the slot is visible, aw ship without a visible slot ends unverified, and aw doctor tells a placed but invisible slot from a missing one.
• aw ship and aw dev capture and compare only the dev slot sizes the widget supports.
• aw_preview takes lang (en / ru), like aw preview --lang.
• Long issue labels under a preview cell wrap inside the tile instead of pushing the next cell out of the grid.
• SAMPLE_NOT_LOCALIZED fires only when the default sample holds text; a feed of numbers has nothing to translate.
• The contracts say how Date fields of a model decode: ISO 8601 or epoch seconds, as in the timeline envelope. The skill asks for the dev slot in the sizes the widget supports.

How it was checked

• 210 engine tests and 69 kit tests, swiftlint --strict clean; every new test was broken on purpose and went red.
• A protocol probe drove the MCP server by hand: with a 20 s budget a real aw_ship answered with a job id after 20 s and aw_wait returned the desktop shots 16 s later; a cancelled preview sent no reply and left no swiftc or xcodebuild behind.
• A fresh Claude agent installed nothing but the plugin and built an uptime widget end to end in 20 minutes; its report drove the fixes for invisible dev slots, compared sizes, lang in previews and the localization warning.
• A Grok agent on the same brief tried to script the desktop to reach the dev slot; the skill now forbids that outright.
• The plugin was installed from this repository with claude plugin marketplace add and claude plugin install and used in a fresh session; the Homebrew formula was built from source and tested.

agent-widgets 0.2.0

The loop is closed: an agent now sees its widget on the real desktop and compares it with the preview, and a ship nobody has seen is no longer a success. A free Apple ID is enough to sign.

Upgrade: git pull && make install, then aw geometry --measure once to read the real widget sizes of this Mac.

Behavior change: aw ship without a desktop screenshot now exits 5 (SHIP_UNVERIFIED) instead of 0. Put the dev slot on the desktop once; aw slot waits for it.

What's new

• aw slot waits until the person puts the dev slot on the desktop, then measures sizes and captures it (SLOT_TIMEOUT).
• A free Apple ID is enough for signing: docs and SIGNING_MISSING now say so; aw preview needs no certificate. Verified: this repository is built, signed and installed with a free Personal Team.
• aw ship without a desktop screenshot no longer reports success: exit 5, stage unverified (SHIP_UNVERIFIED).
• aw geometry [--measure] reads the real desktop widget sizes of this Mac from the system log; previews, the sheet and window matching use them, and aw doctor warns while they are unknown (GEOMETRY_UNKNOWN).
• The dev slot shot is compared with the preview cell of the sample it shows: aw shot and aw ship write <id>-<family>-compare.png (preview, desktop, outlines) and warns with SHOT_MISMATCH when the size or the outlines differ.
• Feeds are never silent: exit 127 / 126 become FEED_COMMAND_NOT_FOUND with the missing program and the feed PATH, the status keeps the exit code and the last stderr lines, and aw doctor reports every feed — ok N min ago, the last failure, or STALE_DATA after three missed runs.
• Feed secrets live in aw.local.json: a feed gets only the names it lists in feed.secrets, a missing value stops it with FEED_SECRET_MISSING, and aw doctor warns when secrets are in the shared aw.json (SECRETS_IN_CONFIG).
• A feed widget previewed with --lang ru and no samples/default.ru.json warns with SAMPLE_NOT_LOCALIZED, with the command that writes that sample.
• aw dev and aw_dev wait until the desktop has redrawn the dev slot, then capture it and compare it with the preview; before, a shot right after aw dev could still show the previous widget.
• The app window edits widget settings: every widget whose feed takes settings gets a form (text, numbers, toggles, JSON for the rest); edits are saved in the App Group, win over widget.json in AW_SETTINGS and make the feed run at the next tick. The kit is unchanged.
• Templates lay out extraLarge: metric, chart, list, ring, card, image and timer get two-column dashboards (the timer also a large layout with an elapsed ring), and new widgets from them include the family. The template test renders all of them.
• The preview matrix gets a Tahoe clear row: default is also rendered as dark clear glass in the accented rendering mode, where color disappears.

agent-widgets 0.1.0

First public version of agent-widgets: a harness that lets coding agents build native macOS desktop widgets. The agent writes a Codable model, a SwiftUI view and, for live data, a small feed script; aw previews every size and theme with layout checks, builds and signs the app, installs it with backups, shows the widget in a dev slot on the desktop and captures the real window.

git clone https://github.com/Surdeddd/agent-widgets && cd agent-widgets
make install && aw doctor
aw init ~/Widgets && cd ~/Widgets
aw new weather --template metric && aw preview weather && aw ship weather

Highlights

• aw preview renders family × light/dark × idle desktop × sample into one sheet in about a second and reports OVERFLOW (naming the tallest parts), TRUNCATION, DECODE and more, each with a hint.
• aw ship builds, installs atomically with three backups, keeps the installed app the only registered widget extension, points the dev slot at the widget and screenshots it.
• Feeds in any language, published only on change and scheduled by a LaunchAgent; buttons with state that do not spend the reload budget.
• MCP server with 11 tools (the preview tool returns the sheet image), the agent-widgets skill for Claude Code and Codex, --json everywhere, English and Russian throughout.
• Eight example widgets, each written by a fresh agent from a one-paragraph brief and the skill.

Requirements: macOS 14+, Xcode 16.3+, brew install xcodegen, an Apple Development certificate. Full list of changes in CHANGELOG.md.