Node.js SDK

Handlers, calls, the panel UI builders and the context object — the full surface of agentty-plugin.mjs.

agentty-plugin.mjs is a single file with no dependencies. Type definitions live next to it in agentty-plugin.d.ts. Press Developer Guide on the Plugins page to unpack both into ~/.agentty/plugins/.sdk/.

Note

A plugin written this way runs as a program on the user's machine, with Node.js 18+ on their PATH, and is installed from a folder or a Git repository. The marketplace lists WebAssembly modules only — for one of those, see Rust and WebAssembly.

js
import { createPlugin, ui } from './agentty-plugin.mjs';

const plugin = createPlugin();
// register handlers…
plugin.start();

Register every handler before calling start().

Handlers#

All handlers may be async. Errors are logged and shown to the user as a notification.

HandlerCalled when
onActivate(info => …)The plugin started. info has plugin.dataDir, language and context
command(id, ({ context, args }) => …)A command runs, from the command palette
tool(name, handler)An AI agent calls a tool; handler receives { args, context } and returns the answer (string, JSON value, or MCP content); errors are caught and sent as tool errors
onPanelOpen(context => …)The panel became visible — render here
onPanelClose(context => …)The panel was hidden
onEvent(elementId, (event, context) => …)A UI element with that id was used
onAnyEvent((event, context) => …)Any UI event not handled by onEvent
onContextChange(context => …)The focused pane, its status or its folder changed
onUrl(path, ({ path, query, url }) => …)agentty://plugin/<id>/<path>?… was opened
onShutdown(() => …)Agentty is stopping the plugin

Calls#

Every call returns a promise.

CallPermission
setPanel(tree) — replace the panel content
showPanel() — open this plugin's panel
notify(message, kind) — info, success, warning, error
setBadge(text) — up to 8 characters on the tab-strip button
getContext()
hostInfo() — Agentty's version, API version, language, and the panel elements it draws (uiFeatures)
openUrl(url) — http/https
copy(text) — put text on the clipboard
revealPath(path) — show a file in the file managerworkspace.read
injectPrompt(request)prompt.inject
sendToTerminal({ paneId, text, submit })terminal.write
setTerminalProxy({ port, token }) · setTerminalProxy({ port: null })terminal.proxy
getSession({ paneId, maxTurns })session.read
listWorkspaces()workspace.read
fetch(request) — an HTTP requestnet.request
log(...) — writes to the plugin log (stderr)

The protocol also has storage/get, storage/set and storage/keys — a JSON document in the plugin's own folder, no permission needed, and synced between the user's computers with their settings — and, from API version 2, host/timer and pane/status. A Node plugin can write its own files instead, but storage works the same for both kinds. See the protocol.

plugin.info holds the data from initialize; plugin.context is the latest context.

The panel#

The panel is 360 px wide and scrolls vertically. The plugin describes it as a tree and Agentty draws it natively, so it matches the application and needs no web view. Send a new tree whenever something changes — text fields keep what the user typed unless you send a different value.

BuilderElementEvents
ui.column(children, { gap }) / ui.row(children, { gap, wrap })Layout. gap: none, small, medium, large
ui.section(title, children)Titled group
ui.text(text, style)body, title, muted, small, code, error, success
ui.button(id, label, { icon, variant, disabled })primary, secondary, ghost, dangerclick
ui.input(id, { placeholder, value, rows })Single-line field, or a text area with rows > 1 (max 24)change after a pause, submit on Enter; event.value is the text
ui.list(id, items, { empty })Rows { id, title, subtitle, detail, icon, tone, actions }select with event.item; row buttons send action with event.item and event.action
ui.choice(id, [{ value, label }], value)Segmented choicechange with the value
ui.toggle(id, label, value)Switchchange with the new boolean
ui.badge(text, tone)neutral, info, success, warning, error
ui.spinner(text)
ui.divider()
ui.flow(id, steps)Steps { id, title, subtitle, icon, state, selected, side }; state: off, on, active, done, errorselect with event.item
ui.popover(id, title, children)A card beside the panelclose
ui.card(children, { title, subtitle, icon, tone })Raised box; tone colors the icon and edge (API 4)
ui.grid(children, { columns, gap })Equal columns, 1–6 (API 4)
ui.tabs(id, [{ id, label, icon, badge }], value, children)Tab strip; children are the picked tab's content (API 4)change with the tab's id
ui.table(id, [{ label, align, grow }], [{ id, cells, tone }], { empty, selected })Rows under headings (API 4)select with event.item
ui.keyValue([{ label, value, tone, mono }])Label and value pairs (API 4)
ui.stat(label, value, { detail, icon, tone })One number, large (API 4)
ui.progress(value, { label, detail, tone })Bar, value from 0 to 1 (API 4)
ui.callout(text, { title, icon, tone })Tinted note, info unless told otherwise (API 4)
ui.select(id, [{ value, label }], value, { placeholder, disabled })Drop-down (API 4)change with the value
ui.checkbox(id, label, value, { description, disabled })Box to tick (API 4)change with the new boolean
ui.code(text, { language, title })Colored code with a copy button (API 4)

Null and false children are skipped, so condition && ui.text('…') works.

Which element to use for what, with whole screens to start from: Designing a panel. The elements marked API 4 need "apiVersion": 4 in the manifest.

js
plugin.onPanelOpen(async (context) => {
  const notes = await search('');
  plugin.setPanel(
    ui.column([
      ui.input('q', { placeholder: 'Search notes' }),
      ui.list('notes', notes.map((n) => ({
        id: n.path,
        title: n.title,
        subtitle: n.folder,
        icon: 'notebook',
        actions: [{ id: 'insert', icon: 'send', tooltip: 'Insert into the focused pane' }],
      })), { empty: 'No notes yet' }),
    ]),
  );
});

plugin.onEvent('notes', (event, context) => {
  if (event.event === 'action' && event.action === 'insert') {
    return plugin.injectPrompt({ text: read(event.item), target: 'ask' });
  }
});
Note

Limits: 2 000 elements, 12 levels deep, 20 000 characters per string — a choice's options and a list item's buttons count as elements too. Panel updates are drawn at most every 50 ms and notifications at most one per 700 ms. A plugin sending more than 240 messages a second is stopped as a runaway.

Context#

Every command, event and panel call carries the context of the focused window:

json
{
  "workspace": { "id": 3, "name": "agentty", "cwd": "/Users/me/agentty", "active": true },
  "pane": {
    "id": 12,
    "kind": "claude",
    "tool": "claude",
    "title": "Claude Code",
    "cwd": "/Users/me/agentty",
    "sessionId": "…",
    "status": "idle",
    "running": true
  },
  "language": "ko"
}

What a plugin sees depends on what it declared. Folder and name fields (workspace.cwd, workspace.name, pane.cwd, pane.title) need workspace.read, and pane.sessionId needs session.read. Without them the context still carries ids, kind, tool, status, running and the language — enough to know which pane is focused, not where the user works.

kind is claude, codex or shell; other agent CLIs run in shell panes and tool names them.

statusMeaning
idleWaiting for input
workingA tool is running
thinkingA turn is open, between tool calls
finishedThe turn ended
permissionAsking permission
questionAsking the user something
interruptedStopped by the user
shellA plain shell
exitedThe program ended

Treat working and thinking the same when deciding not to interrupt.

Sending prompts#

js
await plugin.injectPrompt({
  text: 'Continue the release checklist.',
  title: 'Release',          // workspace name for new sessions, and the dialog heading
  target: 'ask',             // ask | active | newWorkspace | newTab | pane | workspace
  agent: 'claude',           // claude | codex | shell, for new sessions
  cwd: '/Users/me/project',  // folder for new sessions
  submit: true,              // press Enter (agents only)
});
  • ask (the default) shows Send to…, where the user sees the prompt and picks the destination.
  • active types into the focused pane, pane into paneId, workspace into workspaceId, and newWorkspace / newTab start a new session with the prompt.
  • Terminals only ever get the text typed in — Enter is never pressed for injectPrompt.
  • Prompts over 60 000 bytes are saved to ~/.agentty/prompts/ and the agent is asked to read the file. On Windows so is a prompt too long for the agent's command line (about 30 000 characters).

Prefer ask for anything the user starts from another app or from a link.

Tools for AI agents#

js
plugin.tool('list_containers', async ({ args }) => {
  const containers = await listContainers({ all: args.all === true });
  return containers.map((c) => `${c.name}: ${c.state}`).join('\n');
});

Register tools before calling plugin.start(). An agent calling the tool receives your answer (string, JSON value, or MCP-shaped content). Errors thrown in the handler are sent to the agent as tool errors.

A plugin must declare the mcp.tools permission and apiVersion: 5 to offer tools. At most 32 tools per plugin. See Manifest reference for schema and limits.

Sessions and terminals#

To route new terminals through a proxy, declare the terminal.proxy permission and apiVersion: 6, then call plugin.setTerminalProxy({ port, token }). plugin.setTerminalProxy({ port: null }) stops it. Agentty builds the address on 127.0.0.1 from the port, so the plugin cannot point terminals anywhere else. See Permissions.

js
const session = await plugin.getSession({ paneId: context.pane.id, maxTurns: 200 });
// { agent, sessionId, title, cwd, status, turnCount, turns: [{ role: 'user' | 'assistant', text }] }

await plugin.sendToTerminal({
  paneId: context.pane.id,
  text: 'Summarize what we did.',
  submit: true,
});

Check pane.status before typing into an agent: do not interrupt working, permission or question.

Next#