Divergence plugins

This folder is the plugin system of Divergence. Every part of the app that a user sees is a plugin in this folder: the sidebar, the chat view, the file tree, the git panel, the settings page and the agent providers. Divergence opens this folder as the "Plugins" workspace so a coding agent can change any of them in place. Saving a file reloads the plugin without restarting the app and without stopping running agents.

Read this file first, then docs/ for the full reference:

  • docs/ui-plugins.md: the plugin API (definePlugin, views in JSX, slots, elements, tabs and layouts, kernel primitives, host API, events, commands, slash commands, files, network, programs, environment, timers, tools, hooks, agents, tool renderers, limits, hot reload).
  • docs/host-api.md: every host/* method, its params, its result and the permission it needs.
  • docs/events.md: every host event and the permission it needs.
  • docs/tools.md: tools and rules a plugin gives every agent (code mode on OpenCode's interpreter, api.tools.register).
  • docs/agent-protocol.md: how an agent provider works (agent/* methods and agent/event notifications) and the event shapes.
  • docs/process-plugins.md: running a program from a plugin (api.process.start), why no plugin is a native program, and the wire protocol the runtime speaks for a plugin.
  • examples/: small complete plugins for each extension point.

Installing, updating, scanning or publishing a plugin from the marketplace: read Marketplace below first.

One runtime

Every plugin is JavaScript or TypeScript. It runs in a Bun process of its own (official plugins too), under an OS sandbox the app compiles from its grants (plans/bun-plugin-runtime.md): Seatbelt on macOS, Landlock and seccomp on Linux; Windows has no plugin sandbox yet, and Settings and the enable card say so. Inside it the plugin has Bun's and Node's APIs, but what they reach natively is what its grants open: its own files and dependencies, a scratch folder (HOME, TMPDIR), the paths of its fs.read/fs.write grants, programs only with process.sandboxed (they inherit the sandbox), the network only through its network or net grants. The host's APIs (api.fs, api.net, api.process.start with outsideSandbox, api.env) are checked by the broker. Settings shows each plugin's sandbox: Sandboxed, Partly sandboxed (with what does not hold), or Sandbox not available. A plugin whose process uses too much memory is stopped, not the app (docs/ui-plugins.md, Limits). One whose event loop stays blocked freezes only itself; the user reloads it.

What that means for code:

  • Bun's and Node's built-ins are there (node:fs, node:child_process, fetch, WebSocket, timers, crypto, ...), limited by the sandbox as above. Import the plugin's own files with ./ paths, the built-in modules (divergence, divergence/jsx-runtime, zod, effect/<Module> such as effect/Effect, divergence/effect, divergence/services; the effect barrel is not built in), and npm packages the plugin ships: list them in the plugin's package.json dependencies and commit the bun.lock that pins them. A package installs them for production from that lockfile, with no install scripts, as regular files; the plugin loads them offline. A dependency's own dependencies resolve to its own copies, never to the built-ins.
  • A module may be TypeScript (.ts, .mts) or hold JSX (.tsx, .jsx), which Bun compiles (an enum runs; a .d.ts has no code). JSX compiles to the divergence element factory whatever the plugin configures, so a view needs no build step and cannot be pointed at React. An import a module does not use is dropped, as TypeScript drops it. Own modules import with their extension (./grouping.ts); another plugin's files are reached only with import type, never at runtime. plugins/tsconfig.json checks the types; plugins/node_modules (pnpm install) is for tsc and node --test only, the app never reads it.
  • The official plugins are written in TypeScript with Effect and Zod, per plans/typed-plugins/STYLE.md (the plan plans/typed-plugins/PLAN.md explains why). Check and run them with pnpm -C plugins typecheck, pnpm -C plugins test (every *.test.ts, *.test.tsx and *.test.mjs under plugins/, through the Node resolver in plugins/testing/) and pnpm -C plugins format (Prettier). Tests may import divergence/effect/testing, whose testLayer records host calls with in-memory fakes.
  • What a plugin starts outside its runtime (a program, a host watch) it stops in api.onUnload(fn), or in the function its definition's activate returns (docs/ui-plugins.md, Cleanup).
  • A program the plugin needs runs inside its sandbox with api.process.start(program, args, options) and process.sandboxed: it inherits the plugin's policy (its files, network, environment), and an npm SDK's own child_process and Bun.spawn calls are held the same way. A program that must run outside the sandbox uses api.process.start(program, args, { outsideSandbox: true }), with process for a named program such as gh, or process.any for anything else; the option grants nothing by itself.
  • Plugins share nothing but the app state (api.app) and the host: one plugin's globals are not another's.
  • Everything is asynchronous: a host or kernel call returns a Promise.

Layout of a plugin

plugins/<name>/
  plugin.json     manifest (required)
  main.tsx        the entry ("main": "main.tsx"); its default export is the plugin
  ...             other modules, JSON files, anything else the plugin needs

plugin.json:

{
  "id": "alice/hello",
  "name": "hello",
  "version": "0.1.0",
  "description": "One line.",
  "pluginApi": ">=5 <6",
  "main": "main.tsx",
  "permissions": {
    "ui.slots": { "slots": ["right"], "reason": "Show the Hello panel" },
    "fs.read": { "scopes": ["workspace"], "reason": "Count the files of the workspace" },
    "net": { "hosts": ["api.github.com"], "reason": "Load pull requests" }
  },
  "contributes": {
    "hooks": ["before_prompt", "after_turn", "tool_call"],
    "themes": ["theme.json"],
    "rules": ["rules.md"]
  }
}
  • id is publisher/name (lower case letters, digits and -; the publisher at most 39 characters, the name at most 64). A plugin without one is a local plugin, known as local:<folder>. version is semver when there is an id. pluginApi is the range of plugin API versions the plugin works with; this app runs plugin API 5 and nothing else, so the range must admit 5 (docs/ui-plugins.md, One plugin API). basedOn: { id, version } marks a changed copy of another plugin (a mod).
  • permissions lists everything the plugin does beyond drawing in its own views, each with a one-line reason the user reads (see Permissions).
  • listing is what the marketplace shows beside a published plugin, all of it optional: { "icon": "media/icon.png", "screenshots": [{ "path": "media/panel.png", "caption": "The panel beside a chat" }, "media/settings.png"], "homepage": "https://…", "repository": "https://github.com/…" }. Every picture is a file of the plugin, so it is published with it and belongs to that version. The icon is a square PNG, JPEG or WebP of 64 to 1024 pixels (at most 512 KiB), or an SVG. There are at most 6 screenshots, each a PNG, JPEG or WebP of 320 to 4096 by 200 to 4096 pixels between 1:2 and 5:2 in shape (at most 2 MiB), with a caption of at most 120 characters. Both links are https URLs. A top-level README.md is shown on the listing's Overview whether or not there is a listing. The registry checks all of this when the plugin is published and refuses it with the file that is wrong; the app runs the plugin the same with or without it, and older versions of the app ignore it.
  • main is the entry module. A manifest with ui fails with "use main instead of ui"; one with a main array (a native program) fails with "native plugins are not supported; use api.process.start", and so does one with legacyNative, for official plugins too (docs/process-plugins.md).
  • provides, inject and optional declare the typed services between plugins (docs/ui-plugins.md, Services): provides maps each service name (publisher/name) to the contract module inside the plugin that defines it; inject maps a needed service to the semver range the plugin needs (it waits, Waiting, until a provider runs one that matches); optional is the same for services the plugin uses when they are there. A name is never in two of the three.
  • contributes: hooks lists the hooks the host may call (api.hooks.on), as a name or { "hook": "tool_approval", "order": -10 } (default 0; lower first, ties by plugin name); rules are Markdown files whose text every agent session follows; themes are theme files, each one preset { name, mode, tokens } that Settings > Themes offers beside the stock ones, its backdrop pictures as paths relative to the file (docs/ui-plugins.md, themeBackdrop); commands declares every command api.command registers (<name>.<command>, its title, category, default key and when); settings declares the plugin's settings, which the settings page draws as its own section (docs/ui-plugins.md, Commands and keys, Settings). Everything else (views, slash commands, tools, agents, tool renderers) is registered from code.
  • A setting of the plugin's own belongs in contributes.settings, read with api.settings.get, never in the app's settings; a token or a password is a secret, which only the plugin reads (api.settings.secret) and nobody writes into a file. A permission can name a setting as a whole scope entry ("hosts": ["${settings.serverUrl}"]): the user approves each new value on a card, and the plugin cannot change that setting itself.
  • Tools every agent can call come from api.tools.register (docs/tools.md); examples/hello-tools is a complete one. A tool can show its work as a subagent under its call (ctx.subagent), and a plugin with models.use can run prompts through the user's agents and define subagent types (docs/ui-plugins.md, Models and subagents).
  • optional/ holds official plugins the marketplace offers but the app does not install, such as optional/subagents (divergence/subagents: the spawn_subagent tool and the composer's agent/model/effort @ tags). The app does not load them from there; install one from the marketplace.

Permissions

A plugin asks for permissions in its manifest; the user grants them on a card the app draws itself, which no plugin can draw, cover or click. Until then the plugin does not run. The host and the kernel check every call: one without a grant fails with PermissionNotGranted and does nothing, and the rest of the plugin keeps working.

Permission Scope field What it allows Risk
fs.read, fs.write scopes: workspace, plugin (its own folder), data (its own data folder, api.paths.data), or a path glob (/abs/**, ~/x/*.json) fs.* host calls on those paths; a link counts by where it lands, so a link out of a granted folder needs a scope for its target medium; high for a glob over ~ or /
net hosts: whole host names, localhost:<port>, localhost:* (no *.host) api.net to those hosts, and links api.openUrl opens without a click medium
process programs: program names (not shells, interpreters or launchers such as sh, node, python, npx, env, nohup, busybox, awk, java, open; the full list is INTERPRETERS in crates/protocol/src/permissions.rs) api.process.start(..., { outsideSandbox: true }) and api.process.which of those programs, outside the plugin's sandbox medium
process.sandboxed starting programs inside the plugin's own sandbox (api.process.start, and the plugin's or its dependencies' native child_process/Bun.spawn); they get the plugin's native file, network and environment access and nothing more medium
network destinations: a preset (local: this machine and LAN/VPN/private networks; cloud: the public internet; full: both), alone or narrowed to one host (cloud/api.example.com, local/localhost:3000) native network access (fetch, Node's HTTP clients, WebSockets, an SDK's) to those destinations, through the app's proxy; a host list narrows its preset and never adds to it; Off is no grant medium
network.listen accepting connections from other devices (listening on this machine comes with local and full) high
approvals.auto answer the agent's approval requests for you (tool_approval gate) dangerous
process.any running any program, by path or through an interpreter dangerous
native.binaries shipping its own binaries in binaries (needs process.any) unsafe
env vars api.env.get of those variables medium
chats.read workspaces, chats and transcripts, and their events medium
chats.control creating, changing and deleting chats and workspaces; prompts; answers to questions high
agents.provide providing agents (api.agents.register, and passing their tool calls to plugin tools); api.openUrl of a web link while the user signs in to one of its agents medium
agents.manage enabling agents, signing in and out, updating them high
models.use running prompts through the user's enabled agents in hidden sessions (api.models), and defining and running subagent types (api.subagents); the user's own accounts pay high
tools.provide giving every agent tools (api.tools.register) medium
settings.read, settings.write the app settings low / high
git.read, git.write git status and diffs / any git command low / high
terminal terminals and their events dangerous
ui.slots slots: left, center, right, rail, bottom, status, title views in those shell slots low
commands.run running other plugins' commands and palette modes high
market, plugins.manage the marketplace; managing plugins official plugins only
storage, settings.own its own storage and settings always granted
"permissions": {
  "net": { "hosts": ["api.github.com"], "reason": "Load pull requests" },
  "process": { "programs": ["gh"], "reason": "Create pull requests with the GitHub CLI" }
}

An unknown permission, a scope field the permission does not have, a permission that needs a scope with none listed, or a missing reason fails the manifest: the plugin shows as failed with the message. So does a setting template (${settings.key}) that is not a whole entry, names no declared setting, or names one whose type cannot fill the permission (url/host for net, path for fs.*, a select of program names or a file path for process).

  • A new plugin does not run until the user enables it in Settings > Plugins ("Review and enable…"). The app shows a card with every permission, its reason and its risk, and nothing is granted until the user clicks Enable there (for process.any, holds it for two seconds).
  • A plugin whose manifest asks for more later keeps what it has; the new permissions wait for "Review permissions…" in Settings > Plugins, and the calls that need them fail until then. The user can revoke any grant there.
  • Plugins with a divergence/ id in the app's own folder (the built-in ones) are official: they get what they ask for at every load. A copy that someone changed in an installed app is no longer official; it "claims an official id" and waits for its card like any other (a shield in the title strip opens it).
  • Ask for what the code uses and nothing more, with a reason a user understands in one line. Every api.host.*, api.fs, api.net, api.process and api.env call, every api.host.kernel(...) call, shell slot and link needs its permission (docs/host-api.md, docs/ui-plugins.md).

When you make or change a plugin for the user, tell them what to do next: a new plugin needs Settings > Plugins > "Review and enable…", and a plugin that asks for new permissions needs "Review permissions…". Name the permissions you added and why. You cannot enable a plugin or grant it anything yourself, and neither can any plugin.

Marketplace

Plugins come from, and go to, the Divergence marketplace. In this workspace you have the marketplace tools of the official market plugin: use them first. dvg, the marketplace CLI, is second: it is on PATH in the Plugins workspace's sessions, for what the tools do not cover. Reading and downloading need nobody's approval, because a downloaded plugin is not enabled and cannot run. Enabling, publishing, reporting, bug reports and fixes are the user's: each is a card the app draws itself, which you only ask for.

The tools

Tool What it does What the user sees
market_search { query?, category?, sort?, page? } searches the listings (id, publisher, official flag, latest version, installs, rating) nothing
market_read { id, version?, path? } a release read from its verified package, without installing it: the file tree, permissions, basedOn and publisher, or with path one file's text. Nothing is saved, nothing runs nothing
market_similar { id } publishers and plugins with similar names, with creation dates, install counts and the verified flag nothing
market_install { id, version? } verifies, downloads and extracts a release into this folder, not enabled; answers the folder nothing
market_update { name } updates an installed plugin by folder: an unmodified official plugin is replaced at once; anything else answers needsAgent with the versions, the local changes and the permission changes, for you to merge nothing
market_request_enable { name } asks for the enable card of a folder in this chat (the permission card when it is enabled and asks for more) the enable card
market_publish { name, visibility?, share? } only when the user asked you to publish: puts the publish row in this chat the publish row
market_report { id, version, reason, files } only when you are highly confident (Reports below): prepares a report the report card, with exactly what is sent
market_bug_report { plugins, preview: true } lists the attachments a bug report would send (Bug reports below); sends nothing nothing
market_bug_report { text, plugins, attachments?, fullSource?, contactEmail? } only when you are highly confident, after the user checked the text and chose the attachments: prepares a bug report the send card, with the full preview of everything that is sent
market_attach_fix { report, folders? } after a fix works: asks for the attach card of a bug report the attach card: the diff, the changed permissions, the contributor agreement on a first contribution

dvg

A plugin's settings (never its permissions, whether it is on, or a secret) change from a terminal while the app runs: dvg settings get <folder> [key] and dvg settings set <folder> <key> <json> (plain text that is not JSON is a string; null resets the default). The change applies at once, as if the plugin had set it; a setting a permission refers to is the user's alone, in Settings. The theme is the themes plugin's settings: presets (your presets by id: { name, mode, tokens }, tokens as in ThemeTokens in types/divergence.d.ts) and active ({ light, dark }, a preset id each, stock ids divergence-*, vscode-*, high-contrast-*, compact-*). For example, a dark preset with larger type and slow violet fog behind the new chat page, chosen for dark mode: dvg settings set themes presets '{"big":{"name":"Big","mode":"dark","tokens":{"type":{"baseSize":17,"textSize":14},"backdrop":{"newChat":{"scene":"fog","color":"#7c3aed","speed":0.5}}}}}' then dvg settings set themes active '{"light":"divergence-light","dark":"big"}'. Read presets first and write the whole object back: a set replaces it.

The same marketplace from a terminal, for scripts and CI: dvg search, dvg info <id>, dvg read <id>[@version] [path], dvg similar <id>, dvg install <id>[@version] [--chat <chatId>], dvg update [folder], dvg list, dvg status <folder>, dvg diff <folder> (the local changes against the release it came from), dvg request-enable <folder> [--chat <chatId>], dvg init <name>, and the account (dvg login, dvg whoami). Add --json to read the output. dvg install lands not enabled, as the tool does. In a chat prefer the tools: they put the cards in the right chat. Never run dvg publish or dvg report for the user: publishing goes through the publish row and reporting through market_report, so the user sees what leaves. dvg bug [--plugin <folder>] [--text <text>] opens the app's bug report form, and dvg bug attach <report> [--folder <f>] the attach card of a fix; both need the app running, and only the user's click on the card sends anything. dvg contrib apply <report> is for the maintainers (it needs an admin account): it checks that each fix's base version is the version in the repository and applies the fixes on a new branch, without committing or pushing.

Installing a plugin

The user's Install button opens a chat here with the listing id, the version and the scan prompt. Then:

  1. Read the release remotely with market_read and scan it with the checklist below. Write your result first: a one-line verdict, then the findings with files and lines.
  2. If it is safe, install it with market_install, then call market_request_enable with the folder it answered. The enable card shows the plugin, its permissions and your scan; the user decides.
  3. If you find a problem, do not install it. Explain the problem with files and lines, and offer market_report only as Reports below allows.

A plugin with process.any or native.binaries can run any program: name every command and binary you found in your result, since the card shows them in red and the user must hold Enable to turn it on.

Scanning a plugin

Scan every plugin before it is installed or updated, the official ones included:

  1. Compare the permissions with the code. Every permission must be used for the reason it states, and the code must not reach for more. A permission nothing uses is a finding too.
  2. Find the network endpoints and the spawned commands: every api.net.fetch, api.net.websocket and api.net.sse URL, and every api.process.start program and its arguments. Say where each one leads.
  3. Find obfuscated, encoded or minified code: long base64 or hex strings, eval, new Function, code built from strings, packed or minified bundles you cannot read. Code you cannot read is not safe.
  4. List bundled binaries: files that are not text, and the manifest's binaries. A binary cannot be scanned; say so.
  5. Diff a mod against its base: for a listing with basedOn, read the base release (market_read { id: basedOn.id, version: basedOn.version }) and scan what the mod adds or changes.
  6. Check market_similar for impersonation: a publisher or plugin name close to a well-known one (divergence is the only official publisher), a recent creation date and few installs are warning signs.
  7. Never run third-party code outside the plugin system: no node, bun, sh or npx on its files, no installing its dependencies, no opening its links. Read it only.

Mods

A mod is a changed copy of another plugin (basedOn: { id, version }, filled in by the app when it is published). If the original is not installed here, install the mod as any plugin. If the original or another mod of it is installed, read three trees remotely (the base at basedOn.version, the mod, and the local copy here), merge the mod into the local copy so the user's own changes stay, and ask for the enable card only if the permissions changed.

Updating

An update chat starts with what market_update answered: the versions, the local changes against the installed release and the permission changes. Read the new version with market_read, scan the difference with the checklist, merge it into the local copy (keep every local change), and call market_request_enable only if the permissions changed. An unmodified official plugin needs no chat: the app replaces it.

Publishing

After a turn that changed a plugin here, the app itself shows a publish row below your response (for a plugin with no publish setting that is not an official plugin as shipped), with the plugin and its permissions. Do not ask the user whether to publish, and do not call market_publish on your own. When the user asks you to publish, check the manifest first: a semver version higher than the published one, pluginApi, and a one-line reason for every permission. Then call market_publish; the user publishes from the row. The app fills in basedOn and signs the upload; a changed official plugin is published as the user's mod.

Reports

A report goes to the marketplace's moderators, and a false one is noise that costs them time. Report a plugin with market_report only when you are highly confident that it is malicious or has a security vulnerability, and name the files and lines that prove it (files: ["main.js:42", "lib/net.js:10-18"]). Never report on a hunch, for style, for a missing feature or for an ordinary bug. Tell the user what you found first; the report card then shows exactly what would be sent, and nothing is sent unless the user sends it.

Bug reports and fixes

A bug report goes to the Divergence maintainers (and, for a third-party plugin, to its publisher), with attachments the user chooses: the diff of a changed official plugin against its base version, a third-party plugin's full source when chosen, config with secrets removed, diagnostics and screenshots. Maintainers read every report, so it must not be noise.

  • Use market_bug_report only when you are highly confident that the bug is real and you can name the plugin. Not for questions, wishes, or a problem the user can change in Settings.
  • Before you call it, show the user the report text you propose and the attachments you propose (market_bug_report { plugins, preview: true } lists them with their ids and sizes, and sends nothing). Ask the user to check the text and to choose what to attach. Only then call it, with the text and the attachments the user chose. The native card shows the full preview of everything that is sent; nothing is sent unless the user sends it there.
  • A user who is not signed in may give a contact email; never invent one.

Most bugs can be fixed in the plugins here. A chat opened with "Try to fix it with an agent" starts with the report's number and text:

  1. Find the cause in the related plugins' folders, and change as little as you can. Do not change version, id or basedOn. Add a permission only when the fix needs it, and say why.
  2. The plugins reload when you save: ask the user to try the fix.
  3. When a turn changed an official or marketplace plugin, the app shows an "Attach fix to report #N" row below your response, in place of the publish row. The user reviews the diff, the changed permissions and, on their first contribution to an official plugin, the contributor agreement on its card, and attaches the fix there. Do not call market_publish for a fix.
  4. When the row is gone (a later turn changed nothing), or the fix is for another report, call market_attach_fix { report } once the user confirmed the fix works.

A fix to a third-party plugin goes to its publisher as a suggestion.

The smallest plugin

// main.tsx
import { definePlugin } from "divergence";

export default definePlugin({
  views: {
    hello: {
      slot: "right",
      title: "Hello",
      state: { count: 0 },
      render: ({ state, set }) => (
        <column padding="medium">
          <text style="heading">Hello</text>
          <text style="body">Clicked {state.count} times</text>
          <button id="hi" label="Click" onClick={() => set({ count: state.count + 1 })} />
        </column>
      ),
    },
  },
});

Its manifest says "pluginApi": ">=5 <6" and "main": "main.tsx", and asks for the one slot it draws in: "permissions": { "ui.slots": { "slots": ["right"], "reason": "Show the Hello panel" } }.

The default export is the plugin: definePlugin({ views, commands, slash, tabs, activate }), or runPlugin(...) for one written with Effect. A view's state survives draws and reloads, and set changes it and draws the view again. div is the general container, and <column> and <row> are a div laid out as a column or a centred row: their style props, theme tokens, data-only events (onClick, onPointerMove, onKeyDown, ...), canvas (a draw list) and motion (animations the kernel runs) are in docs/ui-plugins.md, Views in JSX and div. Native components are tags of their own (<button>, <input>, <select>, <popover>, <scroller>, <markdown>, ...), and so are the ui plugin's components (<item>, <card>, <setting>, ...).

Every built-in UI plugin is written this way; git/ and sidebar/ show the patterns. examples/hello-panel adds a command and a slash command, examples/chart draws with canvas, follows the pointer and animates with motion, and examples/hello-settings declares settings of every type (with a custom section view), a net permission that takes its host from a setting, a secret, commands with a key and a when key, and a palette mode.

Slots: title (the strip above the main area; a view whose root is a <region over="center"> sits over the center slot), left (sidebar), center (main area; the chat plugin draws a task's panes and the side split there), right (panel before the rail; plugins show it when ctx.app.shared.rightPanel names them), rail (one icon button per view; order >= 100 sits at the bottom), bottom, status. A view returns null to hide itself (for example when ctx.app.route is not its route). A view in any other slot name is not placed by the shell; another view embeds it with <view view={id} /> (the chat plugin's pane views, one per chat), or <view plugin name /> by its plugin and key (a tab another plugin draws). A plugin that shows something in a task's panes or the side split declares a tab kind instead (docs/ui-plugins.md, Tabs and layouts).

Rules of the built-in plugins

  • sidebar (left): workspaces and their tasks (tasks.list, chats.list) in status sections, never grouped. A row is a task: its first chat, or the name the user gave it, on one line, with a child row per chat while the task holds two or more and is on screen or expanded, and a preview of its chats in a popover after a second's hover. It selects chats with api.app.select; renames, checks off and archives tasks (tasks.update, tasks.archive), and Cmd+W closes the chat on screen (chat.closeTab). Its footer draws, above its last row, every view whose id a plugin shares under a key starting with sidebarItem. (api.app.share("sidebarItem.<plugin>", view.id), null when it goes), in the order of the keys. Views shared under sidebarButton. keys stand in the last row just before Options, each in a 22px square: the settings plugin's update button, shared only while something is behind. The last row ends with Options, whose menu draws, above Settings, every view shared under a key starting with sidebarMenu. in the same way: the market's account row and its Marketplace row. A view shared under sidebarPicture is drawn in Options' 22px circle in place of its person mark (the market's picture of the signed-in publisher, shared only while there is one).
  • chat (center, route chat): the task on screen as panes side by side or stacked, each with its tab strip in the title strip over it, its + button and its split buttons, and the side split beside them (layouts.*; ⌘T a new chat in the focused pane, ⌘D a split, ⌘W closing a tab, ⌘⇧T reopening it, ⌘⇧B the side split). One pane view per chat, kept for the last ten shown, with the transcript (rows built here from <markdown>, <list>, <diff>, <code>, buttons; placed in a <scroller>) and the prompt composer (input, selects, list, buttons). Streaming re-renders the pane of that chat only. Approvals, plugin requests, the publish row and report cards are the app's own cards: the plugin places them with a <security_card> node and never answers them. Its Session panel (rail button + right panel, under Files and Source Control) shows the chat in the center: agent, model, approval, workspace, status, session id and times; the context window; the agent's usage limits; and the chat's subagents and workflows, each opening its tab. A subagent is one activity row in the transcript; its transcript is in its tab.
  • files (rail button + right panel): a <tree> from fs.search; a click opens the file through the divergence/tabs service.
  • tabs (no slot): the file, diff, terminal and diagram tab kinds, which show in the side split or a task's panes: <editor> for files with a Markdown and HTML preview, <diff> for diffs. Other plugins open them through its divergence/tabs service (open({ kind, workspaceId, path, diff?, chatId? })).
  • terminal (rail icon + hover fly-out + terminal tabs): the integrated terminal. Hovering the icon at the foot of the rail opens a wide, short window with the tab strip and the live shell; a terminal pops out into a tab of the side split for the full height. New, close, rename (from the tab's right-click menu), one set of shells per workspace. The kernel runs the shells and draws the grid; everything else is here. Its divergence/terminal service runs another plugin's command (run({ command, title? })): a new shell in the open workspace, opened as a tab, with the command typed in (an agent's update).
  • git (rail button + right panel): source control like VS Code's: commit box with a message an agent can write (models.use) and Commit and Push, Merge/Staged/Changes sections with hover actions, branch picker, sync, pull/push/fetch/stash menu, and the branch's pull request on GitHub through gh (process); file diffs open as tabs. It follows the repository through git.watch and git_changed.
  • market (a Marketplace row in the sidebar's Options menu, above Settings, + center route market): the marketplace: browse, search, listings with their files, permissions and comments, Install (a scan chat here, with the agent, model and effort next to the button), update notices (the row's count and an Update button per plugin), sign-in, and the marketplace tools of this workspace (Marketplace above). A link divergence://market/<publisher>/<name>[@version] opens a listing there.
  • settings (center route settings): appearance, agents, plugins, tools, Keyboard Shortcuts, updates, and one section for each plugin with settings (its fields from plugins.settings, its commands and keys, its permissions with Manage). The Plugins page lists every plugin with its badges, state and grants; enabling and new permissions go through the app's card (plugins.requestEnable), and so does a changed setting a permission refers to (plugins.set_setting). Keyboard Shortcuts searches every command, records a key natively (keys.record), shows conflicts with Assign, resets, and opens keybindings.json. Its update button in the sidebar's last row lists every enabled agent whose program is behind (AgentInfo.maintenance), a new Divergence and new default plugins. An update waits until the runs it would cut off end (the agent's own, or every chat's for the app and the plugins), one installer runs at a time, a command an agent can only run itself goes to the terminal service, and a skipped version or a snooze until tomorrow is kept in the plugin's storage.
  • palette (a view in the title strip that is only an overlay): ⌘⇧P lists every command with its key (a command in conflict with Assign, which opens Keyboard Shortcuts), ⌘P searches chats by title and workspace, and other plugins add modes (api.palette.provider). It runs what the user picks in the plugin that owns it (commands.run).
  • ui (no view): the look of the components every plugin draws (button, item, card, setting, callout, markdown's blocks and tables, ...), one file each in ui/components/, sent to the kernel with kernel/components.set (docs/ui-plugins.md, Components). Edit a file to restyle that component everywhere; add one to give every plugin a new tag. After a change run UI_WRITE_STOCK=1 pnpm -C plugins test, which writes the copy the kernel draws with before the plugin starts (crates/kernel/components/divergence.json).
  • codex, claude, opencode, acp: the agent providers. Each runs its agent's own program with api.process.start(..., { outsideSandbox: true }) and shares the provider SDK in sdk/ (docs/agent-protocol.md, Providers in JavaScript); each folder's NOTES.md records how it maps its agent. Each reports the long-running processes it keeps to the host's process pool with the SDK's reportProcess (agent/process, docs/agent-protocol.md, Processes): started once the process answers, sessions with the full list of native session ids whenever it changes, stopped on every exit. One process per session is shared: false and answers suspend_session (stop it, keep everything a resume needs; never the same as close_session); one server for many sessions is shared: true and answers stop_process through its normal exit path; a server the user runs is external: true and is never stopped. Short helper processes (probes, auth checks, history reads) are not reported. Claude reports one process per session; Codex reports its app-server as shared.

Replace any of them by editing its folder, or by adding a new plugin that renders into the same slot, enabling it, and disabling the built-in one in Settings.

A change to a built-in UI plugin that must not change what it shows (a refactor) is checked without a window: copy the plugin's folder to <folder>/<name> before the change (for example under target/), then run DIVERGENCE_UI_BASELINE=<folder> cargo test -p divergence-kernel --test plugin_equivalence. The test runs the old and the new copy side by side on the same fixture data, fires every handler their views show, and requires equal trees, app state and host calls after every step (docs/ui-plugins.md, Checking a view).

Native components

No feature is native. The kernel keeps only generic stateful primitives, keyed by id, whose state survives re-renders and reloads:

Element Purpose
<markdown id text> rendered markdown; with an id, streaming appends are cheap
<scroller id>{items}</scroller> virtualized list that follows its end (transcripts, logs)
<tree id items selected onSelect> collapsible tree with retained expansion
<editor id text language readOnly onChange onSave> highlighted editor with line numbers; onSave hears Cmd+S
<diff path diff> or <diff path oldText newText maxLines> unified diff
<terminal terminal> the grid of a shell the kernel runs (terminal.create gives the id)
<split>, <pane>, <region> resizable groups of two or more children, a pane on the ground, and a title view placed over the center slot
<input>, <select>, <combobox> text and choice controls

Reloading

The app watches this folder. A changed plugin loads again once its files have stayed unchanged for 30 seconds, also while an agent is still working: its runtime keeps running while the new code loads, its views keep their identity (see docs/ui-plugins.md, Views), so inputs keep their text and focus, and the old trees stay on screen until the new code has its data. A changed provider waits while one of its own agents has an active run, and restarts when that run finishes (Settings > Plugins shows "Reload pending"). A changed version that does not compile, throws while it starts, or dies within 10 seconds of starting never replaces a version that worked: the previous version comes back and keeps running. While a Divergence turn runs in a workspace that holds the plugin, that failure stays quiet, since the agent may be halfway through an edit; when the turn ends the plugin is tried again, and a failure then shows in Settings > Plugins and in a notice. A plugin that fails to load with no working version to keep, or that its limits stopped, is shown failed in Settings > Plugins with its error; the rest of the app keeps working.

What each kind of change needs before it shows:

Changed Needed
a plugin (*.js, *.ts, *.tsx, *.jsx, *.json, plugin.json, a theme) nothing; it reloads 30 s after the last save, and a new version that fails does not replace the running one (see above). New permissions of a plugin that is not official wait for the user's review
the app itself (crates/: kernel, host, protocol, the plugin host in crates/sandbox, whose prelude is the divergence module) a new app: cargo run -p divergence for the dev app, or pnpm install:macos:dev for the installed Divergence Dev, which quits and reopens it unless given --no-open (the install-dev-app skill has the full command an agent should run). Never pnpm install:macos:alpha: Divergence Alpha is the stable app the user works in, and only the user promotes it.

Both installed apps read this folder, so a changed plugin (a provider too) reloads in both at once, while each app keeps the host and plugin helper it was installed with. A plugin that needs a kernel or runtime feature Alpha does not have yet must fail softly there.

Nothing in this folder can change the native controls (the select, the input, the tabs): those live in crates/kernel, and a plugin only describes what it wants drawn. Say so instead of editing the kernel from a plugin task.

Source: plugins/AGENTS.md in the Divergence repository, built with this site.