Skip to content
Docs0.9GitHubInstall

Building on itPlugin UI

Plugin UI

The slots, pages, and node kinds a plugin publishes, and what the web client, the iPhone app, and the chooser draw for each.

This page is for plugin authors who want a button or a page in the apps. It lists what a plugin can publish and how each client draws it.

A plugin publishes UI as data. The apps draw it with their own pieces, and none of the plugin’s code, HTML, or script reaches a device. Every kind is drawable without a browser: layouts are rows, columns, and pages; colours are tones; text is plain.

Write a plugin publishes a first page. The methods are in Plugin protocol, and the frames the apps receive are in App protocol.

plugin ──ui_set_page──▶ worker ──ui event──▶ app plugin ──ui_page / ui_patch──▶ app
app ──ui_action──▶ app plugin ──ui_call──▶ worker ──ui_call event──▶ plugin
  • The plugin sends the whole page every time. It never diffs.
  • The worker checks bounds and structure, compares the page node by node, and keeps the last 64 patches.
  • The app plugin carries patches to the devices that have the page open.
  • The app applies each patch. A key is a node’s identity: the same key in another place is the same node, moved.
  • The chooser reads pages from the worker directly with ui_page, and acts with ui_call.

Everything a plugin published goes when its connection ends.

A slotSlot. A place in the apps that takes a plugin's entries, such as the sidebar or a chat's menu. is a place that takes contributions. An app skips a contribution for a slot it doesn’t know.

Slot Where it shows Context sent with a click
nav The sidebar on the web, the tab bar or sidebar on iOS, tabs in the chooser’s Advanced mode none
chat_menu A chat’s actions menu {topic}; the app plugin adds conversation_key
connections Settings → Connections {secret} from a secret flow
new_project New project, one source per contribution {query?, cursor?}
people The admin’s People screen none

ui_set_contributions replaces a plugin’s contributions, at most 16:

{"id": "notes", "slot": "nav", "label": "Notes", "icon": {"symbol": "list"},
 "badge": 2, "on": {"page": "notes"}}
Field Meaning
id, slot, label Required. id and slot are lowercase words; label is one line of up to 64 characters.
icon {symbol}: a provider’s symbol, or grid, plus, team, list, bell. Any other draws as box.
badge A count the plugin keeps current.
home nav only. The desktop’s main area shows this page when no chat is open. The first such contribution wins.
modes simple, advanced; both when absent.
order Sorts within a slot, then by id.
inline people only: true draws its page on the People screen itself.
when chat_menu only: {live: bool} narrows which chats show it.
on What a click does.

on holds exactly one of these, on a contribution, a button, a row, or any node that takes one:

on Effect
{page: ID} Opens one of the plugin’s pages.
{navigate: ROUTE} Opens an app page: {chat: {topic}}, {terminal: {topic}}, {new_agent: {project?}}, {schedules: {}}, {schedule: {id}}, {tasks: {}}, {task: {id}}, {project: {name, person?}}, {settings: {}}, {home: {}}.
{action: NAME, args?} Calls the plugin. The reply may carry a notice to show and an on to follow.
{filter: {FACET: [VALUES]}} Pages only: sets those facets of the page’s filter, on the device.
{url: "https://…"} Opens an https page outside the app, at most 2,000 characters.

An action reaches the plugin as a ui_call event. ui_take returns the action and args as the plugin published them, with the device’s context and the caller. A device names a node; it can’t forge an action or its arguments.

A page is a flat map of keyed nodes and the key of its root:

{"page": "notes", "title": "Notes", "root": "top", "nodes": {
  "top": {"kind": "list", "empty": "No notes yet", "children": ["n1"]},
  "n1": {"kind": "row", "title": "Ship it", "on": {"navigate": {"tasks": {}}}}}}

Every node has a kind. A layout has children, a list of keys. Any node may also set:

Field Meaning
label Its accessible name
show wide or narrow: draw it only at that width
facets, search What the page’s filter and query match it on
required An app that can’t draw this node shows “Update the app to see this page” in place of the page
At most
Pages per plugin 8, plus 32 built on request
Nodes per page 4,000
One node 16 KiB
One page 2 MiB
A key 200 bytes
An action’s context 4 KiB

The worker checks these, that every key in children, footer, and trailing names a node, and that every on is well formed. It never checks kinds, so a new kind needs no change to the worker.

Kind Fields Draws
stack axis (column, row), style (strip for a footer bar) Children in order
lanes open (a lane’s key), animate: "move" lane children side by side when wide; when narrow, one lane at a time under tabs with counts
lane id, title, tab_title?, tab_count?, state, tone?, count, empty, footer? A titled column
list title?, empty?, style? (notices) Rows. Nothing when empty and no empty text is set
grid min_width, in characters Cells, in fewer columns when narrow
sections, section title Titled groups
tabs, tab title One shown at a time
Kind Fields
header title, subtitle (wide only), search: true for the page’s query field, search_label?, trailing (keys of buttons)
text text, style (title, body, caption, mono, kicker), tone
badge text or count, tone
button label, icon, style (primary, secondary, ghost), on, confirm? (a sentence asked first), ask?, back?
row kicker?, title?, spans?, project?, tone?, on?
notice kicker, text, tone, project?, on
filter_bar facets: [{id, label, style: chips|menu, icon?, options: [{value, label, project?, provider?}]}]
empty title, text?
agent agent, answers?, actions?
usage None: the app’s usage summary
segmented label, options: [{label, short?, count?, selected?, on?}]
picker label, options: [{label, spans?, selected?, on?}]
provider, toggle_row A connection as Connections draws it; a row with a switch
file_tree, diff_file, diff_hunk, thread A change’s files, diffs, and comment threads

Smaller parts that several kinds share:

  • spans are inline parts of a row: {text, tone?, mono?, faint?}, or {time: MS, style: run|due|age}, a time the app words and keeps current.
  • project {name, person?} draws the project’s colour mark, in the app’s own colour for that project.
  • tone is one of ask, alarm, ok, accent, muted. A plugin never sends a colour; theme and accent belong to the app.
  • ask is a dialog before acting: {title?, text, note?, cancel?, choices: [{label, style?, on?}]}. Each choice runs its own on.
  • mark {item, labels?} lets the owner mark a node, or a line or range of its lines, and send the marks to the agent as a prompt.

The agent element is the app’s own agent card. The plugin passes an entry from the worker’s overview as it read it, and the app adds what it holds from the chat: the state glyph, provider mark, running tool, team badge, and the answers to an open question or approval when answers is set.

Open chat, Terminal, Stop, and Resume are the app’s own requests. actions are extra buttons the plugin adds. A plugin cannot answer, stop, or resume an agent through a page.

ui_set_contributions may name on_demand page id prefixes, such as ["change-", "file-"]. When someone opens a page that isn’t published and whose id starts with one, the worker publishes ui_wanted {plugin, page} and waits up to 8 seconds for the plugin to set it.

fresh names prefixes whose pages are built again each time one is opened whole. Use it for a view of something that isn’t watched, such as uncommitted changes in a work tree.

vendetta://page/PLUGIN/PAGE in a chat message’s Markdown is a link the apps open as that plugin’s page.

Filters, focus, scroll, the open lane, and cards answered there stay on the device and never reach the plugin. A filter is {facets: {ID: [values]}, query}, kept per device and per page.

A node with facets passes when, for each facet with picks, its values meet them. A node with search passes when the query is empty or found in one of its texts. Nodes with neither always pass. Layouts hide nodes that fail, a lane’s count: "visible" counts what passes, and empty shows when nothing does.

Web client iPhone app Chooser
nav Sidebar entry with its badge Home dock with its badge A tab, in Advanced mode
home page The main area when no chat is open The detail area when wide and nothing is open The page shown first
chat_menu A chat’s actions menu A chat’s row and header menus An agent card’s actions
lanes Columns when wide; tabs when narrow Columns from 900 points; else pages a swipe apart under tabs Columns from 100 columns; else one lane under tabs
A page without lanes Its nodes down the page A document, with the header in the navigation bar One scrolling column
animate: "move" Cards move between lanes Cards move between lanes Nothing
diff_hunk Unified when narrow, side by side when wide Unified under 700 points, side by side from there Unified
picker A button that opens a list of rows The platform’s menu or sheet A line that Enter opens into rows
back buttons Drawn Left out by an app with a back button of its own Left out: Esc goes back
usage Drawn Not drawn yet Skipped
connections, new_project, people Drawn Drawn Skipped
settings and url routes Opened Opened The chooser says where to go

An app skips a node of a kind or route it doesn’t know, with its subtree. New kinds and fields are additions within version 1 of the layer.

  • Only supervised plugins publish. A plugin named vendetta is refused: that name is the worker’s own UI.
  • Any of your callers may call an action, agents included. ui_take names the caller, with owner true for a supervised plugin or a process no agent runs. A plugin that changes what only you decide refuses a caller without owner.
  • The app plugin checks that an action’s topic is one of this person’s chats before it passes the call on.
  • Text in a page is drawn as plain text, never as Markdown or markup. Agent text in a page is untrusted.
Plugin Shows
plugins/dashboard The Overview: lanes, agent cards, a filter_bar, notices, and a strip
plugins/diff Changes: segmented, picker, file_tree, diffs, threads, marks, and pages on request
plugins/github A connections provider and a new_project source
tests/plugin_ui.py A scripted plugin with a chat_menu action, run against a paired device