#menubar

That is already a tab in the switcher, a row in ⌘K, a line in Settings you can switch off, and a portion Home can place. Everything past it is opt-in.

The plugin table at the top of this file, the widget catalog below, and the plugin list on menubar.sh are all written by bun run docs, out of each plugin's own meta:

They used to be three hand-maintained lists and all three had drifted: the catalog was four plugins behind, both of its counts were wrong, and the site mapped the Playing row to a plugin called playing when the folder is nowplaying, so that row's popover asked the demo for something that isn't there. A slug read from the folder can't be wrong that way, and a count nobody types can't be stale.

scripts/docs.ts reads the source rather than importing it — a plugin's module body starts pollers and wants a DOM — by finding the meta literal, stripping the TypeScript with bun's own transpiler, and evaluating it in a scope where every free identifier is undefined. icon and Component evaluate to nothing, which is all they are worth in a table.

A plugin in ~/.menubar/plugins needs no docs: it isn't in anyone's README.

Home is the first tab and it is always there — src/mainview/plugins/home, a plugin like any other, pinned to the front by order: 0 and kept on by removable: false. It holds nothing of its own. Every plugin registers the portions of itself worth glancing at, and the person using the app decides which of them are on Home and in what order.

Home has two layouts, picked by the shell the view was loaded into, each with its own saved arrangement:

Registering a widget

A widget is a component plus a few lines of metadata, pointed at by meta.widgets. Every built-in keeps its catalog in a widgets.tsx beside its index.tsx — the components a widget draws are usually the plugin's own rows, trimmed, and keeping them out of index.tsx keeps the tab file about the tab.

Typing the array as PluginWidget[] is worth the import: the catalog is data, and a mistyped field or a missing Component is otherwise a broken tile at runtime rather than a red squiggle.

Widgets never fetch. Several are on screen at once and the plugin's own tab may be closed, so a widget reads what the plugin's background service already holds and renders it.

A widget that wants to know how much room it has asks:

useSurface() gives the full answer — "tab", "home-grid" or "home-stack" — which matters for a component a plugin renders in both its own tab and a widget.

The same widget, more than once

Home stores instances, not widgets. Add World clocks twice and the second tile is a copy with its own id, its own size and its own settings — one on your zones, one on the team's. The picker never hides what is already placed; it counts it.

widgetKeyOf(id) from @/lib/widget-instance turns an instance back into the widget it renders — the layouts, the picker and the config store all key off one or the other, never both. Copies are told apart by name: every tile's gear opens a panel with a Name field, and an unnamed tile keeps the widget's own.

Settings for one tile

A plugin's own settings section belongs to the plugin: every surface it draws reads the same stores, which is right for a token or a poll interval. A tile often wants something narrower — the whole Clocks tab, but only two of its zones on Home, and the copy next to it on three others. Declare a Settings panel and it joins the tile's gear:

Both sides call the same hook and neither names a key: the panel and the widget body are rendered inside the tile's instance id, and everything written lands under it in one menubar:widget-config store. Two copies of one widget are two ids, so they configure apart. A widget rendered anywhere else — a plugin reusing the component in its own tab — has no id and gets the defaults.

The gear is on every tile — the name alone is worth one — and it tints when the tile has been configured. Taking a tile off Home forgets what it was told, and so does Reset, for the tiles it drops; adding one back is a fresh copy.

Five built-ins ship with a panel, which are the ones marked ⚙ below: World clocks (which zones), Next cron runs (its own expression and zone), My pull requests (failing only, drafts), Deployments (one project), and Unread (one feed, and how many rows).

A widget hands off rather than growing a second copy of the tab. openPlugin(slug) from @/lib/navigation opens the plugin the tile came from, and the stores the tab reads its filters out of are ordinary stores — the Reader's feed tile sets feedFilterStore on the way through, so the timeline opens on the feed you clicked.

A plugin that declares no widgets still reaches Home: its whole view becomes one tile, marked view. That is how anything in ~/.menubar/plugins gets there without knowing widgets exist — it just isn't on Home until you add it, because a wall of shrunken tabs is a worse first impression than a short Home.

The built-in catalog

Forty-two tiles ship, of which fourteen are on a Home nobody has arranged — the one or two per plugin worth a glance. ★ marks those; everything else is one click away in the picker, and ⚙ marks the ones with a settings panel of their own. Home offers none, and Settings is an overlay rather than a workspace, so neither is here.

The Commits tile is the one exception to "widgets never fetch", and it earns it the same way the Commits tab does: that query is four year-scale requests the plugin deliberately never polls until something asks, so the tile calls ensureCommits() on mount and when the popover comes back — never on render.

registerSettings and registerCommands are called at module load, beside meta, rather than inside the component. Every plugin's module body runs at startup — that is what the eager glob buys — but menubar only ever mounts the plugin whose tab is open, so anything registered in a useEffect wouldn't exist until a visitor happened to go looking for it.

Most of what a menu bar app is for is something the OS already knows and the webview cannot ask: how much battery is left, what is listening on 3000, what was just copied, whether a screenshot landed. Three capabilities in @/lib/bridge cover it, and each is deliberately narrower than the general version of itself.

runCommand — a fixed list of local commands

The name is the only thing a plugin chooses. Which binary that is, where it lives, what flags go in front of the arguments, what environment it runs in and how long it may take are fixed in src/bun/exec.ts, and any arguments are checked by that entry's own validator. Three rules hold it up:

• argv, never a shell, so there is no quoting to get wrong.
• Absolute paths, never a PATH lookup, so a binary planted earlier in PATH changes nothing.
• A validator per entry, refusing anything that starts with - — an argument that becomes a flag is the one way argv-only execution still bites.

A non-zero code is an answer, not a failure: git status outside a repository and pmset on a desktop both mean something. error is set only when the command never ran or never finished.

The list today covers power and devices (battery, battery-detail, bluetooth), the machine (uptime, memory, processes, disk, time-machine), security posture (filevault, sip, gatekeeper), the network (listening-ports, net-interfaces, dns, wifi, ping), developer tooling (brew-outdated, docker-ps, docker-stats, tailscale-status, simulators, git-status, git-branches) and the rest of the desktop (shortcuts-list, shortcuts-run, audio-devices, audio-set).

Adding one is two edits — the id in COMMAND_IDS in src/shared/rpc-schema.ts, and its spec in src/bun/exec.ts. They are a Record keyed by that union, so an id with no spec fails the build rather than shipping a hole.

Some commands are the effect rather than a source of one — caffeinate holds the machine awake for exactly as long as it runs. Those are held instead:

Everything held is killed when the app exits, because a caffeinate that outlives it is a machine that never sleeps again with no UI admitting to why. listHolds is the other half of that: a hold survives a view rebuild, so the Caffeine plugin asks what is actually held on start rather than trusting the deadline it wrote down — see src/mainview/plugins/caffeine/service.ts.

readClipboard — the pasteboard, and every change to it

changeCount is NSPasteboard's own counter, which ticks once per copy from any application. Handing back the last one seen is what makes polling this cheap: the answer comes back unchanged and the contents are never read at all.

A copy marked org.nspasteboard.ConcealedType — the convention by which a password manager asks every clipboard manager on the machine not to record it — arrives with concealed: true and an empty text, because the bun side does not read it. Passing includeConcealed reads it anyway; that is off by default and the Clipboard plugin puts it behind a setting, because what it unlocks is passwords in plain text. transient marks a copy that is fine to show and not to keep.

A copy is not always text. Passing media reports what else was on the pasteboard as snapshot.media — paths, a size, pixel dimensions and a rendered thumbnail, never bytes. Copying a file in Finder puts paths there, so the entry points at a file the user already has and menubar touches nothing; copying a screenshot puts bytes there instead, and those are gone the moment the next copy happens, so the watcher writes them into ~/.menubar/clipboard and owned says so. Thumbnails come from sips and QuickLook, which is why a video gets a poster frame and a PDF its first page. The view is served from views:// and cannot load a path, so a picture is fetched inline when there is a row to draw it:

forgetClipboardMedia only ever deletes inside ~/.menubar/clipboard, so a clip pointing at one of the user's own files cannot name a path it would touch. Like the concealed rule, media lives in the watcher's arguments: with it off the script is given no folder, reads nothing and writes nothing.

The watch is the one thing in the app that polls with nothing on screen, which is deliberate: a clipboard history that only recorded copies made while the popover happened to be open would miss everything worth keeping. It stays off until a plugin turns it on, and a plugin that can be switched off should turn it off again. The Clipboard plugin is the one that does — see src/mainview/plugins/clipboard/service.ts for the full lifecycle, including turning the watch back off when the plugin is disabled in Settings.

watchDir — a folder, as it changes

entries is what is in the folder already, newest first — a shelf that only knew about arrivals would be empty after every restart. Events are coalesced over 200ms, so one save is one event, and a file that appeared and vanished inside the same window produces none.

Watches are refused outside the home directory, on the home directory itself, and on the folders that hold credentials or messages — ~/.ssh, ~/.aws, ~/Library/Keychains and the rest of the list in src/bun/watch.ts. Symlinks are resolved before that check rather than after, since ~/link-to-root is a real directory entry and a string comparison believes it. What comes back is names, sizes and timestamps; reading a watched file is a capability that deliberately doesn't exist.

For the same reason, a plugin that polls does it from a module-level service: a plain module holding the state, the listeners and the interval, with the component only subscribing through useSyncExternalStore. A poller owned by a component would stop the moment you switched tabs, and the badge and tray title would freeze with it.

src/mainview/plugins/status/service.ts is the short one to read. It caches its last payload in a store, so reopening the popover paints rows instead of skeletons; it stops its interval whenever the popover is off screen and refetches on the way back if what it holds has gone stale; and it publishes both a tab badge and a tray count on every change.

A plugin that throws on render is caught by PluginErrorBoundary and shown as one failed tab with a Reload button. The rest of the app carries on.