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.
How it flows
Section titled “How it flows”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 withui_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 |
Contributions
Section titled “Contributions”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. |
What a click does
Section titled “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 |
Limits
Section titled “Limits”| 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.
Layouts
Section titled “Layouts”| 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 |
Elements
Section titled “Elements”| 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:
spansare 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.toneis one ofask,alarm,ok,accent,muted. A plugin never sends a colour; theme and accent belong to the app.askis a dialog before acting:{title?, text, note?, cancel?, choices: [{label, style?, on?}]}. Each choice runs its ownon.mark {item, labels?}lets the owner mark a node, or a line or range of itslines, and send the marks to the agent as a prompt.
The agent card
Section titled “The agent card”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.
Pages on request
Section titled “Pages on request”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.
What stays on the device
Section titled “What stays on the device”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.
What each client draws
Section titled “What each client draws”| 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.
Who may do what
Section titled “Who may do what”- Only supervised plugins publish. A plugin named
vendettais refused: that name is the worker’s own UI. - Any of your callers may call an action, agents included.
ui_takenames thecaller, withownertrue for a supervised plugin or a process no agent runs. A plugin that changes what only you decide refuses a caller withoutowner. - The app plugin checks that an action’s
topicis 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.
Pages to read
Section titled “Pages to read”| 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 |