Mods API

For a first example, see the worked test-chips mod. For finished mods to copy, see the showcase.

The module is one ES module that exports register. It may import type from fleet-mods and nothing else. A mod can also ship .html files, with their CSS, images and scripts, for the Page element.

import type { Register } from "fleet-mods";

export const register: Register = (on) => {
  on("ui.render", { component: "ToolUse", props: { tool: "bash" } }, async ($, e, next) => {
    return next(e);
  });
};

• on(event, matcher?, hook) registers a hook. Call it directly inside register, with a string literal event and an object literal matcher. Registering one event twice with no matcher is refused.
• A matcher is compared field by field with e. A value matches itself, an array matches any of its values, a RegExp matches a string by pattern, and a nested object matches a nested field.
• e is frozen. To change it, pass a copy: next({ ...e, text: "..." }).
• next(e) runs the rest of the chain (later mods, then Fleet) and gives you its result. Return it to observe, return your own tree to answer.
• .catch(handler) on a registration runs when the hook throws, times out or returns something the event doesn’t take. Inside it, next.error is { kind, message } and next.called says whether the hook had already called next.

ui.press, ui.input and ui.select carry sessionId, mod, element (the key) and surface. At the end of their chain, the control’s own callback (onPress, onSubmit, onInput, onSelect) runs in the mod that drew it. The other events from prompt.submit on are 0.51.0; session.start and ui.render are 0.50.0.

How prompt.submit, turn.complete, permission.ask and their limits behave is on the Mods page. In short:

• Matchers on prompt.submit see text as you typed it. Matchers on permission.ask work on kind, tool and title.
• A deny reason is a non-empty string of at most 500 characters. Anything else counts as a failure and the ask goes on to you.
• $.prompt.submit({ text }) queues a message and rejects with Fleet’s reason when refused: empty, over 100,000 characters, the session is archived, or the cap of 3 in a row.
• Each hook may run for 10 seconds. A prompt.submit or permission.ask hook gets 1.5 seconds. Fleet itself waits at most 2 seconds for the whole chain on prompt.submit, turn.complete and permission.ask. After that the prompt goes on as you typed it and the ask goes to you; a turn.complete that runs over is simply not waited for.
• Side conversations (/btw) and subagent sessions don’t fire turn.complete.

next(e) at a place gives you what the rest of the chain draws. A tree you return replaces it. To keep Fleet’s own body at ToolResult, put await next(e) inside a Box of yours, at most once.

Inline elements are Text, Pill, Icon, Button and a row Box holding only those. Anything else at ToolUse makes the tree invalid.

Fleet draws a tool row’s places when the row first shows, when the call’s status changes, and when the mod calls $.ui.invalidate. It never redraws on streamed output, so a running call’s output is what had arrived at its last status change. Renders are per session: desktop, phone and other tabs get the same tree.

$ is the only way out of a mod. Write each call in full, like $.state.get("count").

There is no file, process, network or model access, and no setTimeout. Use $.clock.

Call $.ui.open and $.ui.close from a callback or an event, not while drawing. A ui.render hook that calls them throws. A $.ui.open in session.start runs again every time the host restarts.

Fleet draws a tree with its own components and theme, on desktop and phone. A mod never runs script in Fleet’s page.

• Icon names: check, x, alert, info, circle, dot, clock, loader, play, skip, test, bug, terminal, file, folder, git-branch, search, sparkles, zap, gauge, arrow-right, chevron-right, external-link, copy, eye, eye-off.
• Colours are roles: text, muted, accent, good, warn, bad. No hex values.
• Keys: every Button, Input, Select and Page needs a key, unique in the tree. Letters, digits, _, - and ., up to 64.
• Invalid trees: an unknown element or prop, a missing or duplicate key, a non-inline element at an inline place, or a tree over the limits. Fleet draws the place as if the mod weren’t there and counts a failure. The reason is in the mod’s log. Text past 100,000 characters per tree is cut, not refused.

Before a module loads, Fleet reads it without running it. The same report is what you see as “what this mod touches” when you keep a mod. It lists:

• every on(...) call with its matcher
• every $ call as ns.method, once each
• every $.state key
• every Page path, checked to exist inside the folder
• the panes in mod.json
• errors and warnings with line and column

A module doesn’t load when:

• mod.json is missing, invalid, or names a module outside the folder
• it can’t be parsed as an ES module (TypeScript is stripped first)
• it imports anything but import type ... from "fleet-mods", or uses require, import() or import.meta
• it reads a global outside JavaScript’s own, or one of globalThis, window, process, Bun, fetch, setTimeout, eval, Function, Reflect, Proxy and similar
• it uses $ in any way but a full $.ns.method(...) call: aliasing it, $[name], destructuring, spreading or storing it
• it reads .constructor, .__proto__ or .prototype, or uses with
• on is called outside register, with a non-literal event or matcher, or for an event that doesn’t exist
• a $.state key isn’t a string literal
• it is over 512 KiB or 2,000 nested scopes

This is not a sandbox. Every mod runs in one program, as you, and a hook that never returns blocks the others until Fleet restarts the program.

• Order. Hooks on one event form a chain. Kept mods run first, by name, then the session’s drafts by name. A draft with a kept mod’s name takes its place in that session. Within a module, hooks run in the order register called on.
• Time. A hook gets 10 seconds of its own time per dispatch, not counting time inside next or a $ call. A .catch handler gets 1 second. A prompt.submit or permission.ask hook gets 1.5 seconds. Past its time a hook is skipped.
• A failure is a hook that throws, times out or returns something the event doesn’t take. With no .catch, a hook that failed before calling next is skipped and the next one runs in its place.
• Three strikes. Three failures in a row from one mod, not caught by .catch, turn it off. Any success resets the count.
• A blocked program. After 15 seconds on one dispatch, Fleet restarts the mod program and strikes the mod that was running. All mods reload, $.state is lost and session.start fires with reason: "reload".

The rest are in the sections above.

Kept mods are stored under Fleet’s data folder, per user: mods/<user>/<name>/, with immutable v1/, v2/ folders, a versions.json and a store.json. Drafts are in mods/<user>/drafts/<session id>/<name>/. Undo changes which version is active and deletes nothing.

• Mods covers turning mods on, keeping and undoing them, and what each hook does for you.
• Mods showcase has finished mods and a prompt for each.
• Troubleshooting is the place to look when something doesn’t work.