What #1446 asked for that #1445's draft API didn't cover: - `zeron.compose(text, { replace = true, session? })` ("compose"): the words put in place of the draft's (its chips stay, so a rewrite keeps what it carries), and in another chat's draft (`session`). Words alone are added after what's there, as ever. Nothing is sent. - `zeron.draft_of(session)` ("draft"): a promise of any chat's draft as it is, as `zeron.draft()` says it (text, chat, chips by kind and name, never a path), read once in the host where the app keeps it. The composer's handling of a plugin's words is one path now (words alone come as a string). Consent: "compose" says it may replace what you wrote; "draft" says it sees your words in any chat. Docs, SDK (and its copies). Tests: src/plugins `compose_takes_words_alone_or_with_replace_and_a_chat`, `a_chats_draft_is_read_where_it_is_kept_without_paths`; ui/tests/plugin_compose_replace.test.luau. Full UI suite (1422) and plugins:: (248) pass. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
70 KiB
Writing a Zeron plugin
A plugin is a folder: zeron-plugin.json (its manifest), init.luau (its code) and zeron.luau (Zeron's helpers, the SDK). It runs in Zeron's window in a sandbox of its own, with only what its manifest asks for and the person allowed. Agents make plugins through Zeron's MCP tools. This guide is the whole reference: read it once, then use the loop at the end.
Manifest
{
"id": "focus-timer",
"name": "Focus timer",
"version": "1.0.0",
"description": "A timer in a chat's header.",
"icon": "icon.svg",
"entry": "init.luau",
"permissions": ["ui.add", "sessions.read"],
"ui": { "change": [], "replace": [] },
"tools": []
}
id: 2 to 40 lowercase letters, digits and dashes.templates,zeronandappare taken.icon: an SVG in your plugin's folder ("icon.svg", 32 KB at most). Zeron draws it tinted in the text's colour on a neutral tile where your plugin is listed (Settings → Plugins, and your plugin's settings page), so draw it in one colour (currentColor) on a square viewBox. Without one, your plugin gets its initial on a coloured tile. GitHub's is the GitHub mark.permissions: only what you use. The person allows them once, in Zeron. Asking for more later asks them again.ui.change: the selectors you replace, each written exactly as inzeron.place { at = … }. Needs"ui.change".ui.replace: whole screens you replace ("@app/screens/…"; never@app/screens/pluginsor@app/screens/shell/settings). Needs"ui.replace". A screen replacement runs as Zeron's own code; preferui.change.tools: tools agents can call, each{ "name", "description", "input" }.nameis^[a-z][a-z0-9_]{0,40}$without__, andinputis a JSON Schema. Needs"tools".settings: what the person can set for your plugin (see Settings). Needs no permission.commands: the programs it runs as you (["gh", "git"]), each by its name as it's found on the PATH, never a path. Needs"commands", and the person sees each name when allowing it (see Programs and a database).service: its headless half ("service.luau"), which Zeron's engine runs on each device that allowed the plugin. Needs"service"(see Services).network:{ "hosts": ["api.example.com", "*.example.org", "localhost:8080"] }, the hosts its requests may reach, from its window and its service alike (see Reaching the network). Without it,networkreaches any public address and never this device, your network or a cloud's metadata address. With it, only those hosts; a private one (localhost,10.…,nas.local) is reachable only when it's named exactly, and the consent sheet says so.AuthorizationandCookieheaders go only to hosts named here. Needs"network".mcp:{ "command": "./bin/server", "args": ["--quiet"], "env": { "LOG": "off" } }, a program of its own that Zeron starts as an MCP server beside your agents on this device, namedplugin-<id>.commandis required:./…is a file in your plugin's folder, anything else runs as named.argsis a list of text,envnames and text values. Needs"native".settings_description: a line under your settings page's title, in place of Zeron's own. Plain text, 200 characters at most; line breaks and runs of spaces become one space.author: your name, as text. Optional. It's kept in the manifest (and signed with it), but Zeron never shows it as who made the plugin: that comes from the signature (see Who made it).signature: Zeron writes it when it signs the plugin; never write it yourself.{ "key", "files", "sig" }:keyis the signer's public key (ed25519, base64url),fileseach file's path and its SHA-256 (hex), andsigthe signature over the manifest withkeyandfilesin it.filescovers every file in the folder except the manifest and anything whose name starts with a dot. Changing any file, or the manifest, breaks the signature until it's signed again.
Your own plugins are signed as yours, and re-signed and reloaded each time you save.
Permissions
| permission | lets the plugin |
|---|---|
ui.add |
place nodes before or after Zeron's elements (zeron.place), add menu items |
ui.change |
replace the elements listed in ui.change |
ui.replace |
replace the screens listed in ui.replace |
sessions.read |
read sessions' title, status, project, device, times, branch, worktree |
messages.read |
read the open chat's messages (role, text) |
profile.read |
read your id, name, username, avatar |
account.email |
read your email (unless you hide email addresses) |
files.read |
read file paths, and folders: a session's (cwd) and a project's (path) (without it a file is an id of the plugin's own) |
panel.tabs |
open tabs of its own in a chat's panel |
pages.add |
add pages of its own to the sidebar |
navigate |
open chats and pages (zeron.open) |
links.open |
open http(s) links (zeron.open_url), where you open links (Settings → Links) |
notifications |
send you notifications (zeron.notify), as Zeron's own: Settings → Notifications decides whether they show, a few a minute at most |
compose |
put text in the message box, after what's there or in place of its words (zeron.compose), or a review comment on it (zeron.compose_comment); you still send it |
draft |
read the message box's draft as you type it (zeron.draft), or any chat's (zeron.draft_of), and take it whole, put it back, swap it or let it go (zeron.take_draft, put_draft, swap_draft, drop_draft). See The composer's draft |
github, github.write |
read (and write) GitHub through Zeron's engine (older calls; prefer commands with gh) |
network |
the internet: ui.fetch, and remote images (ui.image { src = "https://…" }). See Reaching the network |
clipboard, files, web, windows |
zgx's clipboard, file dialogs, web views, windows |
tools |
tools for agents (the manifest's tools) |
devices |
send data to itself on your other devices |
native |
run a program of its own (the manifest's mcp) |
commands |
run the programs its manifest's commands names, as you, on this device (zeron.run) |
service |
run its service (the manifest's service) on this device, with no window open, for its windows and agents here and on your other devices |
usage.read |
read each agent account's usage: its windows (session, week, …), how much is used, when each resets, its plan. Not who the account is. See Your agents |
accounts.read |
read the saved agent accounts: which is active, which can be switched to, each one's email and name |
accounts.switch |
make another saved account the active one for a provider, on this device or one it names. Always asked, even for your own plugins |
accounts.pin |
run one chat on a saved account of its own, beside the active one (which stays as it is), and decide the account a new chat starts on. Always asked, even for your own plugins. See Pinning chats |
models.read |
read each harness's models, efforts and options, and a chat's model |
models.set |
set a chat's model, effort and options, and what new chats start with. Always asked, even for your own plugins |
messages.send |
send a chat a message, start a chat, answer a chat's question, as you would from the composer. Always asked, even for your own plugins. See Sending messages |
Reaching the network
With network, ui.fetch, remote pictures and the service's zeron.fetch all keep to one rule. It's checked for the address you ask, each redirect, and every address a name resolves to, before anything connects.
| Where | Reached |
|---|---|
| A public address | Yes, unless the manifest names hosts, and then only those |
This device, your network (localhost, 127.…, ::1, 10.…, 192.168.…, 172.16–31.…, 100.64–127.…, fc00::/7) |
Only if the manifest names it exactly (no *.) |
A cloud's metadata address and link-local space (169.254.…, fe80::), 0.0.0.0, ::, multicast |
Never, even named |
Naming a local host. Write what the URL says, in network.hosts:
"permissions": ["network"],
"network": { "hosts": ["localhost:8080", "127.0.0.1:8080", "[::1]:8080", "nas.local"] }
- With a port, only that port. Without one (
"localhost","nas.local"), any port on that host, which suits a dev server that changes ports. There's no port wildcard or range. localhostand127.0.0.1are different hosts: name the one you use.- Naming any host narrows the plugin to the hosts you name, public ones included: a plugin that reaches
localhost:8080and the internet lists its public hosts too (*.example.orgcovers names under it, never a private address). - A host named exactly asks the person again when an update adds it, whatever it reads as, because it reaches where it resolves. The sheet says a named host can be on this computer or their network. A
*.name never reaches a private address, so it needs no asking. A name likebox.tailnet.ts.netthat resolves to your network works once it's named and allowed.
A refused request fails with an error that names what to add, such as add "localhost:3000" to "network": { "hosts": [] } in its manifest. Host, Connection and the like can't be set, and Authorization and Cookie go only to hosts named here. A program it runs (commands) isn't under this rule: what it can reach is what you can.
Placing by selector
local zeron = require("./zeron")("focus-timer") -- your plugin's id
zeron.place { at = "#session-header", after = function(): Node
return ui.text { "25:00" }
end }
at is a selector. before, after or replace is a function that builds a node. It runs as a component of its own, so ui.use_state works in it.
#id: one element..class: every element with that class..a.b: both classes.#a >> .b: a.binside#a.role:button "Send": by role and name.- One node per match.
.session-rowmatches every row, so your node is built once per row. Each copy reads its own row's context. - What fails in your node draws nothing there. It's reported once, as your plugin's, and the rest goes on.
- A replacement sees what's provided above the replaced element, not the element's own
provide. Zeron puts each element's context on its parent for this reason (see the table). To place inside an element that provides something, place by a part inside it (.session-title, not.session-row).
describe_elements (MCP) lists every named element in the window running now: its selector, where it is, what it provides, whether it's present, and whether it's stable. Stable names are kept across Zeron's updates and by every template. Place by stable names where you can.
| stable selector | where | provides |
|---|---|---|
#sidebar |
the sidebar's list | sessions |
.session-row |
a sidebar row (place inside: .session-title) |
session |
.project-icon |
a project's icon, wherever it shows: the sidebar's group headers and rows, tabs, the composer's project, project pickers, the panel, the palette, archived chats. Replace it (ui.change) to draw each project's own |
project |
#session-header |
a chat's header (title: #page-title) |
|
.message |
a message (.message-user, .message-assistant) |
message |
#chat-composer |
the message box | |
#new-chat-background |
behind a new chat, under Zeron's effect: replace it (ui.change) to offer a wallpaper (see below) |
pointer |
.file-row, .file-tab |
a file's row in the tree, its tab | file |
.panel-tab |
a tab of the side panel | panel |
.md-code (+ .lang-<language>) |
a reply's fenced code block | code = { lang, source } |
.md-math |
a reply's display formula | tex |
.md-table, .md-image, .md-quote, .md-heading |
a reply's table, picture, quote, heading |
Everything in the window also has profile, appearance and route. A chat's page and all in it has session.
Slots: places a plugin offers other plugins
A selector reaches Zeron's elements, never another plugin's. A plugin that wants others to add to what it draws offers a slot: zeron.slot(name, props?) is a column (styled by props) holding what each plugin adds there, named under the offering plugin's id. A raw ui.slot(name) must be <your id>.… too: any other name, or one starting with zeron, fails the plugin as it loads, and its row says why. Put a provide above it for what they read there: plain data, or a state of it (never a function).
-- Git's Changes head: its branch, for whoever adds a button beside it.
ui.row { provide = { git_branch = branch }, zeron.slot("branch", { direction = "row", gap = "$space.1" }) }
-- GitHub: Create pull request there ("ui.add").
zeron.place { at = "slot:git.branch", after = function(): Node
local branch = zeron.live("git_branch") -- follows it as it changes
…
end }
before and after both add to a slot, in plugin order; a slot can't be replaced. Zeron offers slots of its own under zeron., a name no plugin can take: slot:zeron.panel.branch, the end of the panel home's branch row (panel_branch: { session, device, cwd, branch }), where the Git plugin says what the branch adds over its base. Zeron's Git plugin offers slot:git.branch (in its Changes head, git_branch: { session, device, cwd, branch, upstream, remote, remote_url, pushed, ahead, behind, base, base_ahead, head }), and in History, each giving git_commit ({ sha, subject, author, email, at, parents, refs, remote_url, session }): slot:git.commit (after a row's refs), slot:git.commit.face (over the author's face; git_face is its size) and slot:git.commit.head (an opened commit's head). The GitHub plugin puts its pull request in the first, and in History the author's picture, the pull request a commit came in by, and View on GitHub.
Menus a plugin offers
Selectors and slots place nodes; a menu's items are data with a function to run, and a function never crosses from one plugin to another. So a plugin offers a menu by name, and other plugins add items to it the way they add to Zeron's own menus:
-- Git: a History row's menu, its own items then what others added.
ContextMenu { items = function()
local entries = { …its own… }
for _, e in zeron.menu_entries("commit", { sha = c.sha, remote_url = url }) do table.insert(entries, e) end
return entries
end, row }
-- GitHub ("ui.add"): an item in Git's menu; `run` gets the context Git gave.
zeron.menu { kind = "git.commit", id = "view", label = zeron.s("view"), run = function(c) zeron.open_url(…c.sha…) end }
The menu's name is the offering plugin's id and a name (git.commit), so only Git offers it. Zeron keeps every plugin's items, tells each plugin only those for its own menus, and runs a chosen one in the plugin that added it, with the context the offering plugin gave (plain data). A plugin runs items only in its own menus.
Context
Inside a build function:
zeron.context(name): what the place provides, or nil.zeron.need(name): the same, or draw nothing here. Settings → Plugins then says why ("Focus timer needs a session, but it's in the title bar").zeron.live(name): a function that readsnameas it changes (a list that moves:sessions).zeron.context_of("session", id): a session's record by id, read live in a reactive function.
Read at the top of the build function and close over the value: a function run later (a reactive prop) is outside the build.
What a place provides is read-only. Don't pass it to a component as its props (Board(page) fails: "attempt to modify a readonly table"). Give the component props of its own: Board { page = page }.
Records hold only what you were allowed. A field you weren't allowed is absent, never an error.
| name | value |
|---|---|
session |
{ id } + title, status, project, device, updated, created, branch, worktree with sessions.read |
message |
{ id } + role, text with messages.read |
project |
{ id } + name, device, icon ({ emoji?, image?, hue? }, as its people chose it) with sessions.read |
profile |
{} + id, name, username, avatar with profile.read, email with account.email |
file |
{ id } + path, name with files.read (else an id of your plugin's own) |
panel |
{ id, session, open_tab } |
code, tex |
plain data from the block |
appearance |
"light" or "dark" |
route |
{ name, session?, page? } |
pointer |
{ x, y }: where the pointer is over the page, 0 to 1 (0.5 at rest). Read it with zeron.live("pointer") |
A new chat's background
A plugin can offer a new chat's wallpaper. Replace #new-chat-background (list it in your manifest's ui.change) and declare a wallpaper setting:
"ui": { "change": ["#new-chat-background"] },
"settings": [ { "kind": "wallpaper", "section": "Wallpaper" }, … ]
Zeron draws that row on your settings page: "Use as wallpaper", and while it's on, Zeron's effect (dither, ASCII, halftone, scanlines) to draw over your wallpaper. Only the person turns it on, there. While it's on, a new chat opens on what you build at #new-chat-background and Settings → Appearance says the wallpaper is from your plugin, with a way to your page; choosing None or Image there takes it back. One plugin's wallpaper at a time: turning yours on replaces another's. Turned off or removed, Zeron goes back to Appearance's choice. Zeron fades what you draw from the top and lays the effect over it, so draw it plain: fill the box (absolute, every edge 0) and keep your pictures in your plugin's folder. The row has no value of yours. Zeron's own Parallax scenes plugin (plugins-builtin/parallax-scenes) is this whole.
Doing things
| call | what | needs |
|---|---|---|
zeron.open("home" | { session = id } | { settings = page }) |
open a page | navigate |
zeron.compose(text, { replace?, session? }) |
text into a chat's draft: after what's there (on a line of its own), or in place of its words (replace = true, its chips kept); the chat shown's draft, or session's (below) |
compose |
zeron.compose_comment { file, line, note, to?, side?, snippet?, key?, session? } |
a review comment on a file or a diff, as a chip on a chat's draft (below) | compose |
zeron.composed() |
in a build: your comments still on a draft, by key: { session, hovered } |
compose |
zeron.draft() |
in a build: the message box's draft, { session?, text, attachments = { { kind, name } } } (below) |
draft |
zeron.take_draft(key), zeron.put_draft(key), zeron.swap_draft(key), zeron.drop_draft(key) |
the draft taken whole and kept by Zeron under your key; put back; traded with what the key keeps; let go (below) | draft |
zeron.drafts() |
in a build: what Zeron keeps for you, by key: { session?, text, attachments, at } |
draft |
zeron.draft_of(session) |
a promise of chat session's draft as it is now, as zeron.draft() says it ("": a new chat's) |
draft |
zeron.toast(text) |
a short note at the window's foot | (always) |
zeron.need("panel").open_tab { kind, title, icon?, data? } |
a tab of yours in the chat's panel; asked again, the one there is brought forward (found by data.key when you give one, else by its title) |
panel.tabs |
zeron.tab(kind, function(tab) return node end) |
how a kind of your tabs draws (tab = { kind, title, data }) |
panel.tabs |
zeron.page { id, title, icon?, build = function(page) … end } |
a page of yours, in the sidebar (title may be zeron.t("…"), following the language) |
pages.add |
zeron.menu { kind = "session" | "file" | "<plugin>.<menu>", id, label, run } |
an item in a row's menu (run gets { id } or { path, session }), or in a menu another plugin offers (its context) |
ui.add |
zeron.menu_entries(name, context) |
the items others added to a menu of yours (<id>.<name>), as ContextMenu entries |
|
zeron.store(key, default) |
kept between runs (1 MB): :get(), :peek(), :set(v) |
(always) |
zeron.every(seconds, fn) |
now and then, 30 s at least; returns a stop function | (always) |
zeron.window(peek?) |
{ shown, active }: whether the window shows (not hidden, minimised or covered) and is in front, read as states (an effect reading them runs again). Leave work no one would see for when it shows |
(always) |
zeron.db.exec(sql, params), zeron.db.query(sql, params) |
its own SQLite database: promises of { changes, last_id } and of rows |
(always) |
zeron.run(program, args, { cwd, stdin, timeout, env }) |
a program its manifest names, as you: a promise of { status, stdout, stderr } |
commands |
zeron.send(to, data), zeron.on_message(fn), zeron.devices() |
the same plugin on your other devices | devices |
zeron.github.watch_pr(session_id) |
in a build: a function reading that session's PR { number, title, url, state, base, head } |
github |
zeron.github.pr(url), zeron.github.diff(url) |
promises of a PR's details or diff | github |
zeron.github.at(session?, project?) |
the same calls, asked on the device that session's or project's checkout is on; also .line_comment(url, { path, line, side, commit }, body), .reply(url, thread, body), .resolve(url, thread, resolved), .comment(url, body) |
github, writes github.write |
zeron.github.repository(project), zeron.github.list(project, repository, { filter, after, refresh, cached }) |
a project's repository (owner/name; its folder stays Zeron's) and its open PRs a page at a time |
github |
zeron.notify { title, body?, session? } |
a notification, as Zeron's own: under Settings → Notifications, a few a minute; a click opens session. A promise of "posted", "off", "held", "paced" or "unavailable" |
notifications |
zeron.open_url(url) |
an http(s) link, where you open links (Settings → Links) | links.open |
zeron.sessions(), zeron.projects() |
your sessions and projects by id, as they change | sessions.read |
Cost. Zeron times each build of your nodes. Past 1 ms a build (a row's badge) or 8 ms of builds in one frame, your row in Settings → Plugins says so ("Slow: 4.2 ms per row"), and plugin_status gives the numbers. Do the work outside the build (in zeron.every, or once per id), and read what changes in reactive functions.
Commands and shortcuts. zgx's own ui.command { id, title, menu, key, run } works in a plugin. It shows in Zeron's menu bar as <plugin>/<id>, with key as its shortcut ("cmd+shift+t"). A shortcut Zeron (or an earlier plugin) already has stays theirs: yours shows without it, and your row in Settings → Plugins says so.
A shortcut needs a modifier: "k", "enter", "f5" or Shift alone on a character ("shift+k") would take that key from every field, page and terminal. Written so, the plugin fails as it loads, and its row says why. A key alone that a state or function gives is dropped: the command stays in the menu bar without it, and the row says so. For letters while your own view has focus, use on_key on your element, or panel_key in the panel. A command's id can't start with zeron, those names being Zeron's own.
Tools for agents. List each in the manifest's tools (and ask "tools"), then:
zeron.tool { name = "count_words", run = function(args, call)
local words = 0
for _ in string.gmatch(args.text or "", "%S+") do
words += 1
end
return { words = words }
end }
run returns the answer, or error() fails the call. It runs as a task, so it can await (ui.fetch). call.chat is the chat that called. Tools run while Zeron is open on this device; a plugin with a service can answer them there instead, with no window open.
Review comments on the composer
zeron.compose_comment leaves a review comment on a file or a diff on a chat's draft (session; without one, the draft shown), as the files pane leaves its own: a chip in the composer naming the file and lines (graph.rs:10–12), its note under it. Nothing goes until the person sends. Then, after their words, every comment goes in Zeron's review comments block, as production's composer writes it (crates/ui comments.rs), so the agent reads each as its file, its lines, its side and its note, with the code under it:
Comments on the diff (each cites the file and line it belongs to; L = line number in the original file, R = in the changed file):
- src/graph.rs:10-12 (R): Keep the old name.
```
fn lanes() {}
-fn rows() {}
+fn rows(n: usize) {}
```
file is the project's path; line (and a range's last, to) the line numbers; side "L" for the original file's lines (a line taken out), "R" for the changed file's; snippet the code (at most 40 lines go); note what the person said. Without a side, it's a comment on a file (- src/app.rs:12: …, under "Review comments").
Give each a key of your own: zeron.composed() lists yours still on a draft by it (taken off or sent, gone), and says which one's chip is under the pointer (hovered), so the lines it was left on can keep a mark and light up as its chip is pointed at. Zeron's Git plugin does all of this in its Changes (plugins-builtin/git/changes.luau): the diff's + (or a drag from it over lines) opens ds/comment's composer under them, using ds/git_changes's on_comment, ranges and marks.
The composer's draft
With draft, a plugin reads what you're typing and can set it aside and bring it back: a stash for a prompt written in the wrong chat, a counter of its length, a bar that says what it carries.
zeron.draft(), read in a build or an effect, is the draft shown as it changes:session(the chat it's for; nil on a new chat),text(the words as typed) andattachments, each chip'skind("file","image","chat","comment", …) andname. A file's path is never in it.zeron.take_draft(key)takes the draft shown whole (its words, its chips, the passages quoted in it) and clears the composer. Zeron keeps it, under yourkey(1 to 64 characters), so your plugin never holds a file's path. An empty draft isn't taken; taking under a key that's kept replaces what it kept. Up to 16 at once.zeron.put_draft(key)puts whatkeykept back on the draft shown, in whichever chat is open, and lets it go. Onto an empty composer it's as it was taken; onto words already there, its words follow after a blank line and its chips after theirs.zeron.swap_draft(key)trades the draft shown with whatkeykeeps. Either may be empty, so one call sets the draft aside (nothing kept), brings it back (an empty composer), or swaps the two.zeron.drop_draft(key)lets whatkeykept go.zeron.drafts(), read in a build, is what Zeron keeps for you, by key:{ session?, text, attachments, at }(atasos.time()). Drafts are kept while Zeron runs, as chats' own drafts are.zeron.draft_of(session)reads another chat's draft once, shown or not: a promise of{ session?, text, attachments }, aszeron.draft()says it (""for a new chat's, with no session).
With compose too, a plugin can change the words in place: zeron.compose(text, { replace = true }) puts text in place of the draft's words, leaving its chips where they are, and session names another chat's draft. A rewrite or a snippet that expands is a read and a replace:
-- ("ui.add", "draft", "compose"): /bug alone in the box becomes the template.
ui.effect(function()
local d = zeron.draft()
if d and d.text == "/bug" then
zeron.compose("## What happened\n\n## What I expected\n\n## Steps\n", { replace = true, session = d.session })
end
end)
Nothing is sent: the person sees the new words in the composer, and sends or edits them. zeron.compose takes 20,000 characters at most.
Each is done in the order you ask. A prompt stash is one shortcut and one chip:
-- ⌘⇧S (Ctrl+Shift+S): set the draft aside, bring it back, or swap the two.
ui.command { id = "stash", title = "Stash prompt", key = "cmd+shift+s", run = function()
zeron.swap_draft("stash")
end }
-- While one is kept, a chip over the composer: click to bring it back.
zeron.place { at = "#chat-composer", before = function(): Node
return ui.show(function(): boolean
return zeron.drafts().stash ~= nil
end, ui.button { "Stashed", on_click = function() zeron.swap_draft("stash") end })
end }
Programs and a database
A plugin can do real work of its own: run the command-line tools you already use, and keep what it learns.
Programs (commands). Name the programs in the manifest and ask for the permission. The person sees each one, and a shell or an interpreter (sh, python3, node) says plainly that it gives you full control of their computer, so name one only if you must:
"permissions": ["commands"],
"commands": ["gh"]
zeron.run("gh", { "api", "user", "--jq", ".login" }):after(function(r)
if r.status == 0 then zeron.toast(`Signed in to GitHub as {r.stdout}`) end
end)
- Each runs as you, on this device, with your login shell's PATH and your sign-ins (gh's GitHub login, git's credentials). The consent sheet names the programs and says so. Most programs can run others or write any file, so the sheet says a plugin that names one (git, gh, a shell, an interpreter, or anything not known to be harmless) can do anything you can, and asks every time.
- No shell:
argsreach the program exactly as given, so nothing in them is expanded or split.stdinis written to it;cwd(an absolute folder) is where it runs. envsets harmless variables over yours:LANG,LC_…,TZ,TERM,NO_COLOR,FORCE_COLOR,COLUMNS,CI, git's identity (GIT_AUTHOR_…,GIT_COMMITTER_…),GIT_TERMINAL_PROMPT,GIT_OPTIONAL_LOCKS,GIT_INDEX_FILE(a.indexfile in a repository's git folder), gh's quiet switches (GH_PROMPT_DISABLED, …,GH_REPO), and your ownZERON_PLUGIN_…names. Nothing that changes what runs or what loads into it (PATH,GIT_SSH_COMMAND,BASH_ENV,NODE_OPTIONS,PYTHON…,DYLD_…, …).- git runs as git's own commands only (no aliases, no
git-<x>from the PATH), with-conly for how it prints (core.quotepath,color.…,core.pager=cat,user.name, …), never--upload-pack,--exec,--output,--templateor--config,-Cinside the run'scwd, andgit configread only. Every run has a repository's own fsmonitor turned off, noext::transport, no pager, editor or prompt. Hooks run only where git would run yours and Zeron knows the checkout: a commit, merge, pull, push, rebase or branch switch from a service, in one of this device's chats' or projects' folders. Reading, anything elsewhere, and runs from a window run none. gh runs its own commands only: neveralias,extension,codespace,authexceptauth status(without the token), orconfigexcept reading. - A run waits
timeoutseconds at most (60 unless you say, 300 at most), then is stopped (status-1). What it prints is kept up to 16 MB. - Only the programs you named run; anything else is refused.
A database (zeron.db, no permission). Your plugin's own SQLite file: removed with the plugin, 100 MB at most, and no other file reachable through it. Use it for a cache, an index or a history, anything past what zeron.store's small JSON file holds.
zeron.db.exec("CREATE TABLE IF NOT EXISTS seen (url TEXT PRIMARY KEY, at INTEGER)")
zeron.db.exec("INSERT OR REPLACE INTO seen VALUES (?, ?)", { url, os.time() })
zeron.db.query("SELECT at FROM seen WHERE url = ?", { url }):after(function(rows)
local first = rows[1] and rows[1].at
end)
Parameters are always bound (?), never put into the SQL. exec with no parameters runs a script of several statements (a schema). Each call is a promise.
Zeron's GitHub plugin is built this way: it asks GitHub's own API through gh (GraphQL and REST), keeps what it read in its database so a pull request opens at once, and polls each repository once a minute for the sidebar's badges.
Services
A service is your plugin's headless half: service.luau, run by Zeron's engine on each device, with no window open. Your windows call it on this device or on another of yours, and agents' tools can be answered by it. It's how a plugin does real work where the work is: a Git plugin runs git on the device a chat's checkout is on, whether that's your laptop or a devbox.
"service": "service.luau",
"permissions": ["service", "commands"],
"commands": ["git"]
-- service.luau
local zeron = require("./zeron")("my-git")
zeron.serve("status", function(args, call)
local r = zeron.run("git", { "-C", args.cwd, "status", "--porcelain" }):await()
if r.status ~= 0 then error(r.stderr, 0) end
zeron.emit("checked", { cwd = args.cwd })
return { clean = r.stdout == "" }
end, { safe = true })
-- init.luau: on the device the session's checkout is on (nil: this one)
zeron.service(session.device):call("status", { cwd = session.cwd }):after(function(s)
zeron.toast(if s.clean then "Clean" else "Changes")
end, function(err)
zeron.toast(zeron.reason(err)) -- "offline", "not_approved", …
end)
Each device decides for itself. A device runs your service only if the plugin is installed there, on, and allowed (with service), in the same version as the caller's, signed by the same author. Its commands run as the person on that device, with that device's sign-ins. The person allows it once per device, as with every plugin.
In service.luau, require("./zeron")(id) gives the service's helpers (the window's ui.* isn't there):
| call | what | needs |
|---|---|---|
zeron.serve(method, fn, { safe? }) |
answer zeron.service(…):call(method, args): fn(args, call) returns the answer, error() fails it. call.from is the calling device ({ id, name }). safe = true: running it twice does no harm (see below) |
|
zeron.tool { name, run } |
answer an agent's tool (one the manifest's tools lists), with no window open |
tools |
zeron.every(seconds, fn) |
now and then (30 s at least), even while nothing calls it: Zeron starts the service to run it. Register timers at the top level, in the same order each time | |
zeron.on_stop(fn) |
told before it stops (idle, an update, Zeron quitting) | |
zeron.emit(event, data) |
to your windows: those on this device, and those watching from another (:on). 64 KB at most |
|
zeron.watch(folders, fn, { quiet? }) |
changes under whole paths on this device, each all the way down: fn(changed) once a burst has been quiet quiet ms (250), changed by folder: its changed paths (relative, /-separated), or true when anything may have (as it starts, too many, events lost). Reads aren't changes. Returns a stop function; it lasts while the service runs. Pair it with emit to tell windows, instead of their polling |
files.read |
zeron.run(program, args, { cwd, stdin, timeout, env }) |
a promise of { status, stdout, stderr }, as the window's |
commands |
zeron.fetch(url, { method, headers, body, timeout }) |
a promise of { status, headers, body } (http and https; public addresses, or the manifest's network.hosts) |
network |
zeron.folders() |
a promise of this device's chats' and projects' folders (whole paths) | sessions.read |
zeron.notify { title, body?, session? } |
as the window's | notifications |
zeron.store(key, default) |
:get(), :set(v): kept on this device between runs (1 MB), the service's own (not the window's store) |
|
zeron.sleep(seconds), zeron.task(fn) |
a promise done later; run fn as a task of its own |
|
zeron.json.encode(v), zeron.json.decode(text), zeron.device |
JSON; this device's { id, name } |
Handlers, tools, timers and :after callbacks each run as a task, so :await() works in them. A service shares nothing with your windows but what it answers and emits.
In your windows:
zeron.service(device?): the service ondevice(an id: a session's or project'sdevice), or on this device without one.:call(method, args, { timeout }): a promise of what the method returned. 30 seconds unless you say, 300 at most.:on(event, fn):fn(data, event)for eachzeron.emitit makes. For another device, its events reach this one while a window here is open. Returns a function that stops listening.zeron.reason(err): why a call failed, as a word.
Failed calls are yours to handle. Zeron never retries a call for you, and says why it failed:
| reason | the device that was called… |
|---|---|
offline, timeout |
couldn't be reached, or didn't answer in time |
not_installed, off, not_approved |
doesn't have the plugin, has it turned off, or hasn't allowed it (or its service) yet |
version_mismatch, other_author |
has another version of it, or someone else's plugin by the same id |
no_service, not_loaded |
has a version with no service, or one whose service.luau failed to load (the message says why) |
unknown_method, failed |
doesn't serve that method, or your handler failed (error(), or a refused program); the message is yours |
interrupted |
stopped during the call, and the method isn't safe |
old_engine |
runs a Zeron from before services |
The one exception: when the service stops during a call (it ran out of memory, or crashed), a method marked safe = true runs once more on a fresh start. Mark only what can run twice: reading, not posting.
When it runs. A service starts on its first call, tool call or timer, and stops after 5 minutes with nothing to do. An update loads the new version beside the old one, which answers until the new one has loaded and finishes the calls it has. Each call or resumed task has 2 seconds of work before it fails (await between parts: waiting costs nothing), and the service has 64 MB. plugin_status shows the service on this device: running or not, what it serves, its last log lines (print) and why it didn't load.
A service has zeron.on(event, fn, opts) and the agent calls of Your agents too: register listeners at the top level, in the same order each time (they're known by their place, as timers are), and Zeron starts the service to tell it, with no window open.
Zeron's Git plugin (plugins-builtin/git) is built this way: its service does every piece of git work on the device a chat's checkout is on (status, what changed through an index of its own via GIT_INDEX_FILE, diffs, staging, commits, pushes, branches, history), and its window says each refusal in its own words. plugins-dev/checkout-status is the small version, whole: a session row's menu asks the service on that session's device for the checkout's branch and changes, and agents get the same through a tool.
Your agents: usage, accounts and models
A plugin can watch how much of your agents' plans you've used, switch which saved account a provider uses (as Settings → Providers' switcher does), and choose a chat's model, and hear each of those change. The same calls work in a window and in service.luau; each is a promise, and a refusal fails it with "<reason>: <words>" (zeron.reason(err)).
| call | what | needs |
|---|---|---|
zeron.usage { provider?, device? } |
each account's usage, as Zeron last read it: { { provider, account, active, plan?, fetched_at?, error?, windows = { { label, used, remaining, resets_at? } } } } (percent; resets_at in ms) |
usage.read |
zeron.usage_refresh { device? } |
read usage again now: once every 5 minutes per plugin (paced otherwise) |
usage.read |
zeron.accounts { provider?, device? } |
the saved accounts: { { provider, account, active, switchable, email?, name?, organization?, plan? } } |
accounts.read |
zeron.switch_account { provider, account, when_idle?, device? } |
make a saved account the active one: a promise of { status = "switched" }, or "waiting" with when_idle |
accounts.switch |
zeron.pin_account { provider, chat, account?, device? } |
run a chat on a saved account of its own, from its next run, while the active account stays as it is; no account takes the pin back: a promise of { provider, chat, account? }, or already when nothing changes |
accounts.pin |
zeron.pins { provider?, device? } |
the chats pinned to an account: { { provider, account, since, chat? } } (chat with sessions.read) |
accounts.read |
zeron.models(harness, { device? }) |
a harness's models: { { id, label, efforts, options = { { id, label, default, choices } } } } |
models.read |
zeron.chat_model(chat) |
a chat's { provider, model, effort, options } |
models.read |
zeron.set_model { chat, model?, effort?, options? } |
a chat's model, effort or options, for its next turn, on the provider it has | models.set |
zeron.set_default_model { harness, model, effort? } |
what a new chat starts with in this window (a window's call only) | models.set |
zeron.on(event, fn, opts?) |
fn(data, event) for each event below; returns a function that stops it |
the event's |
provider and harness are a harness's id ("claude-code", "codex", …); account is an account's id from zeron.accounts or zeron.usage.
What it never gets. No sign-in, token or password; it can't add or remove an account, or read another plugin's grants. A read never makes Zeron ask a provider again (that can spend a saved login's one-time refresh); only usage_refresh does, paced.
Switching. A switch happens at once, chats running or not; pass when_idle = true to switch once that provider's chats on that device have finished (within 30 minutes). Switching to the account that's active already is refused (already). Each change says which plugin made it: in its event (by = { plugin, name }), and in plugin_status (agents.actions).
Another device. Name it per call (device = id, a session's or project's device): that device decides with what it allowed your plugin there (installed, on, the same version by the same author, and the permission), as a service call does. A service acts on its own device; to act on another, call your service there.
Events
They're told as Zeron learns of a change, never by polling: when Settings, the composer's usage ring or a plugin reads accounts, a provider reports usage, a chat's status or config changes, or a catalog is listed. A window hears them while it's open; a service's zeron.on hears them with no window open.
| event | data | needs |
|---|---|---|
usage.changed |
an account's usage, as zeron.usage gives it |
usage.read |
usage.threshold |
{ provider, account, window, remaining, below, resets_at }, once as remaining crosses under opts.below (percent), again only after it's back over |
usage.read |
usage.reset |
{ provider, account, window, next_reset_at }: a window reset |
usage.read |
limit.hit |
{ provider, account?, window? }, or { provider, blocked_turn = true, chat? } when a turn was stopped by a limit |
usage.read |
account.switched |
{ provider, account, from?, by? } |
accounts.read |
account.pinned |
{ provider, account, from?, by?, chat? }: a chat now runs on account |
accounts.read |
account.unpinned |
{ provider, account, by?, reason?, chat? }: a pin was taken back, or (reason = "removed") its account is gone |
accounts.read |
run.preparing |
{ provider, chat? }, asked of a service right before a chat's first run: what its listener returns is the answer. See Pinning chats |
accounts.pin |
account.signed_out, login.expired |
{ provider, account?, chat? } |
accounts.read |
model.changed |
{ chat, provider, model, effort, options, by? }, or { default = true, provider, model, effort, by } |
models.read |
models.updated |
{ provider, models }: a catalog changed |
models.read |
turn.started |
{ chat, by? } (by: the plugin whose message set it off) |
sessions.read |
turn.finished, turn.errored |
{ chat, outcome, by?, reply? }: completed, errored, interrupted or limited; reply, its final words (the last 16 KB), with messages.read |
sessions.read |
chat.awaiting_input, chat.input_answered |
{ chat, by? }: an agent asked a question or needs approval, and was answered |
sessions.read |
- Narrowing.
opts.provider,opts.account,opts.windowandopts.chatlet only matching events through. A threshold watches the active account unlessopts.accountnames one. - A threshold starts from what it sees. The first reading only learns which side of the line each window is on, so read
zeron.usage()as you start to act on how things stand now. - Only what you were allowed. A field your plugin wasn't allowed is left out, never blanked:
emailis there withaccounts.read,chatwithsessions.read, a turn'sproviderwithmodels.read. - A handler can't hold Zeron up. Events are told after the change, never before it. A listener that fails (or takes past its time) stays on and hears the next event; your row in Settings → Plugins and
plugin_status(agents.notices) say the latest failure and how many in a row. - A loop is stopped. A plugin told of its own change (
byis it) that answers with another change, and so on 16 times in a row, has that next change refused (loop), and your row says so. A message counts as a change: a turn your message set off is told with yourby, so sending again on itsturn.finishedis counted. What you heard last decides: answering anyone else's change starts the count over. How often you change things never counts, only your changes setting off your own.
-- service.luau ("service", "usage.read", "accounts.read", "accounts.switch")
zeron.on("usage.threshold", function(e)
for _, a in zeron.accounts({ provider = e.provider }):await() do
if not a.active and a.switchable then
zeron.switch_account({ provider = e.provider, account = a.account, when_idle = true }):await()
return
end
end
end, { below = 10, provider = "claude-code" })
plugins-dev/account-rotate is this whole: its service switches Claude Code to the next saved account with more left when the active one drops below 10%, once its chats finish, and its window says so in a toast.
Pinning chats to accounts
Switching moves everything on the device to another account at once. Pinning moves one chat: zeron.pin_account makes a chat run on a saved account of its own while the active account stays as it is, so your other chats and your own terminals keep running on it. Zeron holds the pins and delivers the credential; which account a chat gets is the plugin's to decide.
- A pin lasts the chat's life. From its next run, until a plugin (or the same one) takes it back. Resume and prompt caching assume stable credentials, so a pin changes only when you or a plugin change it. A chat parked on the old account is replaced, and resumed, before its next turn.
- What can be pinned. Each row of
zeron.accountssayspinnableandmechanism: Claude Code logins ("env": the saved login's token goes to that chat's process alone) and Muse's kept accounts ("root"). Other providers saypinnable = falsefor now, and an API key never can (it bills per token). A pinned Claude Code chat can't use features that need the account's profile (Remote Control). Rows also saysigned_out;zeron.usagerows saylimited_untilwhile a full window hasn't reset. - The first run. A service listening for
run.preparingis asked right before a chat that has no pin runs for the first time, one chat at a time. What its listener returns is the answer:{ account = "…" }pins the chat there, anything else leaves it on the active account. It has 3 seconds; a listener that's late, fails or names an account that can't be pinned is passed over (its row says so), and each chat is asked once. - Pins follow accounts. An account that's removed takes its pins with it (
account.unpinnedwithreason = "removed"), and its chats run on the active account. - Attributed and stopped like a switch. Each pin is recorded as the plugin's (
by,plugin_status), and the loop guard counts it.
-- service.luau ("service", "accounts.read", "accounts.pin", "sessions.read")
zeron.on("run.preparing", function(e)
for _, a in zeron.accounts({ provider = e.provider }):await() do
if a.pinnable and not a.signed_out then
return { account = a.account }
end
end
end, { provider = "claude-code" })
plugins-dev/account-pin is the whole of it: it answers with the saved account that has the fewest chats (counted from zeron.pins()), so new chats take turns.
Sending messages
With messages.send, a plugin talks to your agents as you do: it sends a chat a message, starts a chat, and answers a chat's question or approval. The same calls work in a window and in service.luau, and each goes the way the composer's would, so a chat behaves exactly as if you'd sent it: queued behind a running turn, steering it, or a turn of its own, wherever the chat runs (its host may be another of your devices).
| call | what | needs |
|---|---|---|
zeron.send_message { chat, text, attachments?, mode? } |
a message into chat: a turn of its own when nothing runs; while a turn runs, queued for its end (mode = "queue", the default) or steering it ("steer"). A promise of { status = "sent", chat, delivery = "run" | "queue" | "steer", id } |
messages.send; attachments (files' paths on the chat's device) also files.read |
zeron.new_chat { prompt, device?, project?, harness?, model?, effort?, cwd? } |
a new chat, sent prompt as its first message: on device or in project (a project's id), with harness (else this device's default) and model and effort from its catalog. A promise of { status, chat, id }: chat is the new chat's id |
messages.send |
zeron.answer { chat, answers, request? } |
the question (or approval) chat waits on, answered as you would: answers = { [question] = label } (or { labels }, or a list of { question, labels }); request names one, else the latest. A promise of { status = "answered", chat, request } |
messages.send |
- What it sends is yours. Your agents read it as your message, and do what it says, so
messages.sendis always asked, even for your own plugins, and the consent sheet says so plainly. - Who sent it is kept. Each message a plugin sends is recorded as its (
{ plugin, name }) beside the chat's transcript, synced with the chat, and inplugin_status(agents.actions). The transcript shows it as any message. - Its turns say so. The turn your message sets off (or, queued, the next one) is told with your
by:turn.started,chat.awaiting_input,turn.finished,turn.errored. - A loop is stopped, as with switches: sending on your own message's
turn.finished, 16 times in a row, has the next send refused (loop), and your row in Settings → Plugins says so. A send on something else (your own turn ending, say) starts the count over. How often you send never counts. - Refusals.
not_allowed(the permission, orfiles.readfor files),not_found(no such chat, model, effort or question waiting),bad_call(no text;"steer"while a chat waits for an answer: answer it, or queue),loop.
-- service.luau ("service", "sessions.read", "messages.read", "messages.send")
zeron.on("turn.finished", function(e)
if e.outcome == "completed" and e.reply and string.find(e.reply, "%[continue%]%s*$") then
zeron.send_message({ chat = e.chat, text = "continue" }):await()
end
end)
plugins-dev/keep-going is this whole: its service sends "continue" to a chat whose turn ends with the line [continue], with no window open, and its window says so in a toast.
Settings
Declare settings in the manifest; Zeron draws their page. While your plugin is on, it has a page of its own in Settings, under "Plugins", titled with its name and built from Zeron's own rows, so it looks native in every theme and template. You never draw it, and no plugin can draw into it. Settings search finds each one.
"settings": [
{ "id": "show", "kind": "switch", "label": "Show the timer", "description": "In each chat's header.", "default": true },
{ "id": "length", "kind": "number", "label": "Length", "min": 5, "max": 90, "unit": "minutes", "default": 25 },
{ "id": "sound", "kind": "choice", "style": "segmented", "label": "Sound",
"options": [ { "value": "bell", "label": "Bell" }, { "value": "none", "label": "None" } ], "default": "bell" }
]
Each setting has an id (letters, digits, - _ .), a kind, a label, and optionally a description, a default and a section (consecutive settings with the same section share a titled card). By kind:
| kind | value | extra fields |
|---|---|---|
switch |
true / false (default off) |
|
choice |
one option's value (default the first) |
options [{ value, label, description? }] (an option's description stands in for the setting's while it's chosen), style "select" or "segmented" |
text |
text, 2000 characters at most | placeholder |
number |
a number, kept within min and max |
min, max, step, unit |
shortcut |
"ctrl+alt+space" (with ctrl, alt or cmd held), or "" |
|
folder |
the absolute path of a folder the person chose, or "" |
|
wallpaper |
none of yours: Zeron's "Use as wallpaper" row, for a plugin that replaces #new-chat-background (above) |
Read them in your code (no permission):
local length = zeron.setting("length") -- :get() follows it, :peek() doesn't
local all = zeron.settings() -- every value by id
zeron.on_setting(function(id, value, was) -- each change the person makes
zeron.toast(`{id} is now {tostring(value)}`)
end)
Status. Your plugin can say how a setting stands, and Zeron draws it beside the control: a short badge in a fixed tone (neutral, success, warning, danger) and words in the description's place. Plain text only; it goes when your plugin is off.
zeron.set_status("shortcut", { badge = "Set up", tone = "warning", text = "Another app has these keys. Choose others." })
zeron.set_status("shortcut", nil) -- cleared
Permission rows ({ "kind": "permission", "permission": "screen-recording" | "accessibility" }) are for Zeron's own plugins only; anyone else's is left out. Zeron supplies the row's words, whether it's granted, the button to grant it and Check again.
- Only the person sets them, on that page; your plugin reads them.
- A setting never set reads its
default, so changing a default in an update reaches everyone who left it alone. A value that no longer fits (an option you dropped) reads the default again. - What the person sets is kept for your plugin alone, across restarts, and removed with the plugin.
Translations
Zeron speaks the language chosen in Settings → General → Language (English or 简体中文 today, or System: your computer's own). A plugin can too: its words go in locales/, beside zeron-plugin.json, a file per language, with en.json the source:
my-plugin/
zeron-plugin.json
init.luau
locales/
en.json { "timer": { "start": "Start", "left": "{n, plural, one {# minute} other {# minutes}} left" } }
zh-Hans.json { "timer": { "start": "开始", "left": "还剩 {n} 分钟" } }
ui.button { zeron.t("timer.start"), on_click = start } -- follows the language as it changes
ui.text { zeron.t("timer.left", { n = minutes }) } -- a state or function argument follows too
tooltip = zeron.s("timer.start") -- the text now, where only a string goes
zeron.toast(zeron.s("timer.done"))
- Keys are nested in the file and dotted in code (
timer.start). Messages are ICU MessageFormat:{name},{n, plural, one {# item} other {# items}}(and=0 {…}),{x, select, a {…} other {…}}. Plurals follow English's rules (onefor 1, elseother); a language with one form (Chinese) writesotheralone. zeron.t(key, args)is for text (a child,ui.text, a label): it follows the language, and the arguments if they're states or functions.zeron.s(key, args)is the text now, for what takes only a string (a tooltip, a toast, a menu item's label). Read in a function, it follows as well.- Falling back: a language the plugin has no file for, or a key that file lacks, shows the plugin's English (
zh-Hans, thenzh, thenen), and a key English lacks shows the key itself. A plugin withoutlocales/loses nothing: plain strings work as they always have. - Zeron's own words in what the plugin uses (the design system's buttons, menus and states) follow the language by themselves.
- Language files are part of the plugin: signed and shipped with it like any other file, up to 1 MB together. Zeron reads them as the plugin loads, so after editing one, save
init.luau(or turn the plugin off and on) to see it. ui.tis Zeron's own catalog, not the plugin's: usezeron.tfor the plugin's words.
plugins-dev/session-words is a working example: session-status's word in a chat's header, in English and Chinese.
The loop
create_plugin { id, name, description, permissions }makes the folder and signs it as yours. Its reply gives the folder, its files and a link to this guide.- Edit
init.luau(and the manifest, for permissions). Zeron re-signs and reloads it on every save. If the manifest asks for something new, the person allows it in Zeron. plugin_status { id, snapshot = true }answers without a person:- its status (on, off, pending review, tampered, broken, and why) and what it was allowed;
- each place it made: its selector, how many elements it matched and their boxes;
- what its Settings row says (a need its place doesn't give, places this template lacks, an error);
- with
snapshot, a PNG of the window around its nodes. Read the file atsnapshot.
- Fix and save, then ask again. Matched 0? Check the selector against
describe_elements. A need? Place it inside something that provides it.
list_plugins lists them all. Selectors that aren't stable may move; templates may rename elements. plugin_status and Settings show "Not shown in this template" when yours aren't there.
Sharing and installing
A plugin travels as its folder, signed. The person installs it with Settings → Plugins → Install…; an agent uses these tools:
install_plugin { path }installs a.zeron-pluginfile.install_plugin { url, ref?, folder? }installs from a link:- a link to a
.zeron-pluginfile; - a GitHub release (
…/releases/latest,…/releases/tag/<tag>), from its.zeron-pluginasset; - a git repository:
owner/repo, its GitHub page,…/tree/<branch>/<folder>, or any https git URL.
- a link to a
update_plugin { id? }only checks. It looks where a plugin installed from someone else came from (its file, link, release or repository) and reports any newer version: its version and the permissions it adds or removes (added,removed). Withoutid, it checks every one. It never installs anything: the person installs an update in Zeron, with Update on the plugin in Settings → Plugins. Tell them what you found. (check = trueis still accepted and changes nothing.)
Zeron checks the signature over every file before anything is written, so an unsigned or changed plugin is refused.
When installing or updating fails, the error reads "<reason>: <words>", for example rate_limited: GitHub is turning away requests…. The reason is a stable word (git_missing, repo_unreadable, rate_limited, release_not_found, no_package, download_failed, tampered, other_signer, not_newer, …); Zeron's window says each one in the person's language. rate_limited means GitHub answered 403 or 429: wait, or sign in with gh auth login (Zeron looks up releases as you when gh is signed in, or GITHUB_TOKEN/GH_TOKEN is set). git_missing means installing from a repository needs git on that device; a release or a .zeron-plugin file doesn't.
- Signed with this device's key, installed from Zeron's window: what it does inside its sandbox is allowed at once. Anything outside it (
commands,native,service,devices,ui.replace,accounts.switch,models.set,messages.send) waits for the person. Installed by an agent, it waits. - Signed by anyone else: it waits until the person allows it in Zeron. The reply says
waiting; you can't allow it for them. - An update: it must be signed by the same key as the installed version, or by another live key of the same account (the author on a new machine; an old key revoked still counts as theirs). One signed by a new key installs but waits for the person to allow it again. One that asks for a new permission still installs, but waits for the person to allow just that.
- Removing a plugin (Settings) takes away its folder, what it stored, its pages and its placements.
Making a package
To share a plugin, save it as one signed .zeron-plugin file:
export_plugin { id }(MCP), orzeron plugin export <id> [--to <path>]on the command line. Your own plugin is signed again first, so the file holds what's in its folder now. The reply gives the file'spathand its size (bytes).- Without
--to, it's saved in Zeron's data folder, asplugin-exports/<id>-<version>.zeron-plugin(an earlier one of the same name is replaced).--tois a folder to save it in, or a file whose name ends in.zeron-plugin. The tool takestotoo, but an agent's export always goes toplugin-exports: leavetoout and readpath.
Then attach that file to a GitHub release, or send it. People install it from the file, or from the release's link. You can also commit the plugin's folder, with its signed zeron-plugin.json, to a repository: Zeron re-signs your own plugins as you save them, so what you commit is already signed. The package format (zeron-plugin:v1) is the same signed package templates use: the manifest, plus every file as base64.
Who made it
Zeron says who made a plugin from its signature, never from its manifest. Each device makes a signing key of its own and registers it to the Zeron account signed in there (a new key needs a fresh sign-in). To check a plugin, Zeron asks Zeron's servers whose key signed it. The answer is kept for an hour, so a key revoked elsewhere stops counting within that.
| what people see | it means |
|---|---|
| by Zeron | one of Zeron's own, shipped in the app |
| by you, Made by you | signed with this device's key |
| Made on one of your devices | signed with your account's key from another of your devices. It's still asked, like anyone's |
| by @username, Made by @username | signed with a key registered to the account that holds that username, and not revoked |
| Unverified, Unknown author | Zeron can't confirm who made it: it's unsigned, its key was never registered or was revoked, its author has no username yet, or Zeron couldn't check (offline, signed out). The sheet says which, and where it came from |
| Changed since you allowed it | its files changed after you allowed it, in a way its author's signature doesn't vouch for (edited on disk, or an unverified plugin replaced). It doesn't run, and it can't be allowed as it is: its sheet offers Remove, or Reinstall (fetched again from where it came from, then asked again) |
Claiming a username. Your plugins read as "by @username" to others only once your account has a username. You claim it once, in Zeron's setup right after you sign in: 3 to 20 letters, digits, _ or -, starting with a letter or digit, kept lowercase. It can't be changed afterwards, and names that look like Zeron's, its staff's or a brand's are reserved. Until you have one, your plugins show as Unverified to everyone else.
A plugin you wrote that shows as Unverified here (one you copied in unsigned, say) can be made yours: the consent sheet's "It's mine…" signs it with this device's key. A plugin someone else signed can't be taken over; copy it under a new id to make your own version.
Trust model
- A plugin you install runs with the access you grant it, and nothing more. It runs in its own sandbox, and each call it makes is checked against what you allowed.
- What you grant, it has. A plugin with
commands,nativeorserviceruns programs as you, so it can do anything you can. Grant those only to a plugin you trust. - Only you allow a plugin, in Zeron's window. An agent can make and install plugins, but never allow one for you.
- Code already running as you on your computer (for example an agent with a shell) is trusted the same as you. Zeron doesn't try to confine it.
Three examples
A badge on each sidebar row
{ "id": "row-branch", "name": "Row branch", "version": "1.0.0", "entry": "init.luau",
"permissions": ["ui.add", "sessions.read"] }
local zeron = require("./zeron")("row-branch")
zeron.place {
at = ".session-title", -- inside each row, so the row's session is above it
after = function(): Node
local id = zeron.need("session").id
return ui.text {
function(): string
return zeron.context_of("session", id).branch or ""
end,
text_size = "$font.size.xs",
color = "$text.tertiary",
}
end,
}
A widget in a chat's header
{ "id": "focus-timer", "name": "Focus timer", "version": "1.0.0", "entry": "init.luau",
"permissions": ["ui.add"] }
local zeron = require("./zeron")("focus-timer")
zeron.place {
at = "#page-title", -- in #session-header, which has the session
after = function(): Node
zeron.need("session") -- only on a chat's page
local left = ui.use_state(25 * 60)
-- (A timer belongs to the node it's made in: it stops with it.)
ui.every(1000, function()
left:set(math.max(0, left:peek() - 1))
end)
return ui.text {
function(): string
local s = left:get()
return string.format("%d:%02d", s // 60, s % 60)
end,
tabular = true,
text_size = "$font.size.sm",
color = "$text.secondary",
}
end,
}
A renderer for a kind of code block
Replies' fenced blocks are .md-code.lang-<language>, and each provides code. Replace one kind, and the rest stay code blocks. A block still streaming in is built again as it grows. With your plugin off, it's a code block again. (plugins-dev/md-hello is this, with tests.)
{ "id": "mermaid-view", "name": "Mermaid diagrams", "version": "1.0.0", "entry": "init.luau",
"permissions": ["ui.change"], "ui": { "change": [".md-code.lang-mermaid"] } }
local zeron = require("./zeron")("mermaid-view")
zeron.place {
at = ".md-code.lang-mermaid",
replace = function(): Node
local code = zeron.need("code") -- { lang = "mermaid", source = "graph TD; A-->B" }
return ui.canvas {
w_full = true,
h = 240,
draw = function(c)
-- lay code.source out and draw it: boxes, arrows, labels
end,
}
end,
}
Zeron's components
Zeron lends your plugin its design system: the same components Zeron's own screens are built from, from whichever template is active, so your plugin looks native in every theme and template. It needs no permission. Require the modules you use from @ds/… (not @app/…, which plugins can't reach):
local Button = require("@ds/button")
local Badge = require("@ds/badge")
local Settings = require("@ds/settings")
local git = require("@ds/git") -- a change's pieces: header, diff, checks, activity
zeron.tab("my-review", function(tab: any): Node
return ui.column {
w_full = true,
gap = "$space.5",
git.header({ state = "open", number = 12, title = tab.title, branch = "fix", base = "main", added = 3, removed = 1 }),
Settings.Group {
Settings.Row { label = "Checks", description = "2 of 3 passed", control = Button { "Re-run", tone = "secondary" } },
},
}
end)
-
Use them before drawing your own. Text (
@ds/text), buttons and icon buttons, fields, selects, tabs, badges, callouts, empty states, settings cards and rows, markdown, comments and threads (@ds/comment,@ds/inline_block), and the git pieces (@ds/git,@ds/git_changes). They hold the theme's spacing, corners, focus rings and motion, which is what makes a plugin look like part of Zeron rather than beside it.ui/ds/*.luauis their source, each with its usage at the top, and the gallery (zeron-zgx gallery) shows each one. -
In your plugin's own VM. The modules load in your sandbox, with state of their own; nothing is shared with Zeron's copy or another plugin's. They lend no authority: what they do is limited by your permissions, as your own code is. Set a markdown link's destination with
require("@ds/links").opener = function(url) zeron.open_url(url) return true end(links.open). -
Require a module, not
@dsitself.@dsloads every component Zeron has;@ds/buttonloads one. -
A tab or a page fills its room. What
zeron.tabandzeron.pagebuild is given the room the panel or page has:h_fullon it, then scroll inside (ui.scroll) or keep to the height and scroll in parts. -
Faces take a picture from anywhere you can reach. A person (
{ id, name, src }) showssrcover their gradient, which shows until it arrives or if it never does;srcmay be a remote address withnetwork. -
The lightbox works in a plugin. Put one
require("@ds/lightbox").Host()in what you build (a tab's, a page's); a markdown picture then opens whole over the window on a click, as a chat's does. (Zeron tells your plugin the window's size for it, asui.shared("zeron.window"), sinceui.windowisn't a plugin's.)
Zeron's GitHub plugin (plugins-builtin/github) is built this way throughout, with nothing of Zeron's made for it: its pull request viewer and board are the gallery's review design on @ds/git, its sidebar badge is @ds/badge's, people's faces are their GitHub pictures (loaded with network), and everything it knows comes from GitHub through gh (commands), kept in its database. Its words are in locales/en.json (zeron.t, zeron.s), so it follows the language like the rest of Zeron.
Style
Prefer Zeron's components (above). Where you draw your own, use Zeron's tokens, never raw values: colours ($text.primary, $text.secondary, $accent, $border), spacing ($space.1…$space.8), radii ($radius.sm…$radius.xl) and type ($font.size.xs…$font.size.lg). Your nodes then follow the person's theme and accent. Inside something rounded, a corner is the outer radius less the inset.