Built-in GUI plugins

Built-in features of the desktop and web app, each behind the GUI plugin SDK, @opencode/plugin/gui in packages/plugin/src/gui/. The window host lives in packages/app/src/runtime/plugin/, the main-process host in packages/desktop/src/main/plugin/. README.md is the author guide: it explains every rule below, with diagrams and source-checked code from the shipping plugins, and walks through src/pairing/. These are the rules.

Structure

The SDK and the contracts file, review, browser and updater live in packages/plugin/src/gui/; all but updater publish with @opencode/plugin as @opencode/plugin/gui*. Built-ins, hosts and third-party plugin bundles all import them by that name; this package holds only the built-ins. Three subpaths are workspace-only and never published: gui/host (the hosts' protocol), gui/builtin (what only built-ins use) and gui/updater (the app's own updater contract).
Keep the public SDK for third-party plugins. API only built-ins use goes in @opencode/plugin/gui/builtin (packages/plugin/src/gui/builtin.ts), which no public SDK module imports: import onIdle, BuiltinStore, BuiltinPanel, BuiltinPanelTab, BuiltinCommand, BuiltinSlot, builtinContext, builtinMainContext and builtinCatalog from there. Each built-in registry token has the public token's id; the hosts read every item through it.
Built-ins declare with Plugin.define like any plugin, as TUI built-ins do; "built-in" is only the host's flag for what src/renderer.ts and src/main.ts load. A third-party ./gui-experimental bundle default-exports one Plugin.define({ setup?, main?, ...declarations }). No definition declares an id: the host gives a built-in its key in compose and a bundle the server plugin's id, as ctx.id. Main alone lists the plugins on the app's own server and sends windows their bundles; both hosts evaluate bundles only through evaluatePluginBundle in @opencode/plugin/gui/host, which owns the shape checks.
Every declaration field is declared once, in Plugin.Declarations (packages/plugin/src/gui/declarations.ts). Plugin.Definition adds the setups; the host's Entry (@opencode/plugin/gui/host) adds the lazy windowEntry and mainEntry. Every OS check goes through runsOn. A plugin from the config whose os leaves out this system never runs, and Extensions › Plugins keeps its row with "Not available on this system."
One folder per built-in: index.ts (Plugin.define({ os?, stores?, i18n })), contract.ts, renderer.tsx, an optional main.ts, and i18n/<locale>.ts.
src/renderer.ts and src/main.ts are the only files that list the built-ins, each through compose from @opencode/plugin/gui/host, which attaches the lazy windowEntry and mainEntry. Main never imports window code.
Every plugin here ships. Do not add a plugin, fixture or wrapper only to document or demonstrate the SDK; the guide shows shipping code.
Another plugin may import only your contract.ts (tokens and schemas, no runtime code). Contracts are not declared: provide your own with ctx.provide (contracts from the window, Ipcs from main, each with an id under your plugin's id), call your own main entry with ctx.main(Ipc), and follow another plugin's token with ctx.use(token). Every built-in keeps working while any other is not active. To avoid loading an Ipc's schemas at startup, import its token only in the chunk that calls it.
A contract that returns components binds each with bindPlugin in the provider's setup, so usePlugin inside reads the provider's context, not the consumer's. Annotate the bound component's props (bindPlugin((props: FileTreeProps) => ...)): TypeScript cannot infer them inside ctx.provide. Do not wrap data methods such as Changes.diffs.
SDK icon fields take an IconName: the names of @opencode/ui/icons/catalog, which the SDK carries in a generated file (bun run generate in packages/plugin); src/icon-name.typecheck.ts fails when they drift.
The APIs the host always provides are context properties (ctx.layout, ctx.sessions, ctx.storage, ctx.desktop, …; in main ctx.storage, ctx.windows, ctx.serverEndpoints, …). usePlugin<typeof definition>() returns the same context in components. Registries and contracts stay tokens: ctx.add(Registry, item), ctx.provide(Contract, impl); main provides Ipcs with ctx.provide(Ipc, impl).
Fonts follow the Fonts section of packages/app/AGENTS.md. Terminal-rendered output uses ctx.appearance.font("mono") (the terminal font); other UI uses the code and UI font CSS variables. Never bundle font files or write literal families, except for documents that carry their own fonts (Office, font previews).
Never import @opencode/app, @opencode/desktop, or @/ paths. Import CSS with ?inline and contribute it through ctx.add(Style, css). No module-level state: keep state inside setup. bun run lint enforces these rules.
Never call crypto.randomUUID() directly in window code; use uuid() from @opencode/util/uuid so plain HTTP LAN origins keep working (see the Insecure Origins section of packages/app/AGENTS.md).
bun run lint:changed must pass before you finish: every file you add or edit has no oxlint problem at all, including the warn-level anti-slop rules (unknown parameters and returns, unchecked type assertions, widened types, unsafe dictionaries, missing spacing). Touching a file means leaving the whole file clean, older warnings included. Fix the code; suppress only with a SAFETY: comment that states a real checked invariant.

SDK docs

Every exported declaration in packages/plugin/src/gui/, every interface member, every field of an object type (options, results, union members) and every parameter has TSDoc. Say what it is, when to use it, its default, and what happens on failure. Document each value of a union. Primitives, token kinds, registries and context properties carry an @example.
bun run lint runs script/sdk-docs.ts, which fails on a missing doc comment or @param, a @param that names no parameter, a ctx.<member> in the guide or this file that no context declares, and a guide code block marked  (a whole file) or  (the declaration, object property or call named name, with the comments directly above it) that differs from that shipping source.
When you change the SDK, change its TSDoc and the guide in the same change. When the check names a guide block your change made stale, copy the new source into the guide; do not reword the source to fit the guide.

Host boundary

Host code must not name a plugin or know its internals: no plugin ids, command ids, DOM selectors, or stored key formats. When the host needs something from plugins, add a generic, documented field to the SDK (for example PanelTab.file, Command.featured, Command.section).
A plugin owns its settings: declare a store and render the toggle from your SettingsPage, as a page, a section on a host page (page), or rows in a host section (section). The host exposes no preferences of its own.
Accepted exceptions: the built-in lists, the keybind rename map in packages/app/src/settings/keybinds/migration.ts, the legacy type: "browser" comment decode in packages/app/src/composer/schema.ts (drafts and message metadata written before plugin notes), and the crash page's use of the updater contract.

Lifetimes

An instance lives from setup until it is disabled, reloaded, removed, or its window closes. A reload can land at any await, so code that outlives a tick must prove it still belongs to the live instance.

Everything registered through ctx (contributions, contracts, Ipc listeners, dialogs, embeds) is withdrawn with the current owner (a component, a createKeyed run), else with the instance. ctx.dialogs.open returns a handle whose close() closes that dialog alone. Anything else you start (timers, DOM listeners, subscriptions) needs teardown: in the window, Solid's onCleanup (setup runs under the plugin's root owner); in main, ctx.onCleanup, which runs at once when the instance is already gone. setup may instead return a cleanup, as server and TUI plugins do; window setup stays synchronous.
Window setup is synchronous: an async one fails to compile, and the host fails it at runtime. Put async work in createKeyed or createLatest, with ctx.signal or a signal derived from it. Only main setup may be async. After every await, return if ctx.signal aborted before touching state or contributing; there is no owner after an await, so window teardown that starts later listens to ctx.signal. Pass the signal to Ipc calls and long work. Methods without an input schema take options only, e.g. pairing.screenActive({ signal }).
Never keep a value from a shorter lifetime in a longer one. Read a server's client, data and url from its live ServerRef each time: a restarted or re-authenticated server gets a new controller under the same id. Keep per-session state in a session-scoped store, or in a map keyed by session.key that you prune.
Each routed session gets its own frozen MountedSession, and a new one when it moves to another directory (same key and visit, new directory). A render receives the next one through props.session (panels), input.session (slots) or state.session (tab labels) without remounting. Read those getters where you use them; never copy the object into a variable or key a cache by it, which would rebuild on every switch. A MountedSession has no actions that follow the route: the workspace files, comments and composer belong to the session screen, one object while it routes A, B and A again. Panel callbacks take one named input with a non-null, constant screen; every session.* slot gets it too, but window.bottom does not. Render tab and session fields are live getters; lifecycle callbacks keep their event's tab and call metadata. Key per-screen caches by the screen. Commands and link handlers read ctx.screen.current() where they act, never once in setup. It is defined exactly when ctx.sessions.current() is: from just after the screen's first render until the route leaves it, so never on Home or a draft. Renders and render effects use their inputs, not these accessors; pass the owning screen on, as Changes.watch(screen, source) takes it.
Main: builtinMainContext(ctx).lifecycle.restart(handoff) disposes every other plugin and keeps the caller active until the handoff settles; when it rejects, return to a state the user can retry from.

Failure is part of the contract

ctx.use(token) is a Live accessor: pending while the provider loads or restarts, inactive while it is disabled or failed. Every Ipc is inactive on the web, where every ctx.main call rejects. Every user action branches on it and still answers: offer the action only while it can answer (register it in a createKeyed run), or show an unavailable state (as WSL's "WSL unavailable" does). Never a silent return or an endless spinner.
An Ipc that goes away is a suspension, not a failure: keep what the user had (for example the browser's tab inventory) and resume when it returns, without a retry timer.
An Ipc call can reject while the event that explains it is still in flight; events and call replies travel on different channels. When main reports an outcome as an event, let the event decide, and treat a rejection as final only for errors main throws before any event (validation, missing endpoint).
The host orders Ipc state for you: an event always wins over an older snapshot. Do not re-fetch state to fix ordering.

Stored state

Desktop storage loads over IPC; web storage is synchronous, so a read before load passes every web e2e test and still breaks desktop. Declare stores (Store.global, Store.session): a global store is loaded before setup, a session store's value is undefined until it loads, and update waits for the load. Storage.store, for keys only known at runtime, returns the same Persisted; derive nothing from it, such as a request, before value is defined.
Main-process state goes through ctx.storage.store, read synchronously and always loaded.
Stored keys live in your plugin id's namespace (plugin.<id>.<key> in the window, namespace plugin.<id> in main). The host imports each built-in store once from its earlier extension. key by itself; do not add that key to from. Move values through from with older homes newest first. To import a part of an app key, declare the store with BuiltinStore and a { key, sessions?, pick } home (sessions for one session's slice). A pick returns undefined when the old key holds none of its fields, never an object of undefined fields. Main's older homes are { settings: key, file? } or { state: [namespace, key] }, through builtinMainContext(ctx).storage. Keep old fields readable until every user has migrated; never drop user data.
When you rename a plugin that has shipped, migrate its stored keys with from, its command ids in the keybind rename map, and its panel keys with BuiltinPanel.legacy. Its enable setting starts again under the new id. Do not add a migration for an id that never shipped in a release.
update mutates a deep-mutable draft and returns nothing or undefined; a returned replacement fails to compile and throws at runtime in both processes. set replaces the value. Plain readonly Schema.Struct fields work without mutableKey. Window update and set wait for load and apply in call order with each other, including runtime-key stores; main writes reach disk at once. Do not batch main writes yourself.
Storage.remove(key, { from }) takes the store's from, so the older key is never imported again and the key reads as initial.

Panels and layout

Panel.focus(input): input.restored is true only for the selection the side region mounts with (for example after a reload). Run side effects that express user intent, such as switching the file tree's tab, only when it is false. All panel callbacks take one named input; read its getters and do not destructure.
The host selects the first tab with fallback: true in regular, first (BuiltinPanelTab.first), then pinned tier order while the stored selection is missing or cannot be selected. False or omission opts out. If you will restore a tab, keep listing its stored id, with hidden: true while its content is not known yet, so the fallback never runs.
Map keys stored before plugins, or under your plugin's earlier id, with BuiltinPanel.legacy. A transient panel's stored keys are dropped once it stops listing them.
A PanelTab.transient tab is a launcher (e.g. "Open file"): the next preview replaces it, and narrow screens neither store nor select it. closable only styles the close button; set both when you want both.
Layout.stored(session) returns your stored tab ids. Layout reads return nothing while session.location is undefined (for example after a server re-authenticates); writes made meanwhile wait and apply in order once it is known.
No host API throws before the app interface mounts, as during setup: reads return their documented defaults (Layout.ready() is false, state is "closed"), and writes, a server or session store's included, wait and apply in call order once it mounts. A dialog opened meanwhile waits too and shows after the interface's first render; its handle closes it before then.
Layout.sidebar.opened() is the inner sidebar preference side panels share, readable outside a panel render (for example in a tab's fields); do not mirror usePanel().sidebar into a store.
Narrow screens: a plain open switches to the panel's mobile view. Pass background when the user stays where they are (a palette pick, a composer chip) or the agent opened the tab, and tab: "select" to append and select without replacing the preview.

Solid

Read You Might Not Need an Effect and Solid.js Best Practices before writing reactive code here. In short:

bun run lint bans importing createEffect, createRenderEffect and createComputed in packages/gui-plugins/src (the SDK in packages/plugin/src/gui/ wraps them). Run side work per provider generation or value with createKeyed(source, fn, { otherwise }), fetch with createLatest, and keep per-visit state with createVisitState.
Derive, don't sync. A value computed from other state is a createMemo or a plain function, never an effect that calls a setter. Never mirror state into a second store, signal, or Map through an effect.
An effect (createKeyed) synchronizes with something outside Solid: the DOM, a third-party widget, an embed, an Ipc subscription, a chunk preload. Comment what it syncs with when that isn't obvious. A source that builds an object is a new key on every read; pass equals to compare the fields that should run it again.
Logic caused by a user action belongs in that action's handler, not in an effect that watches the state the action changed. If several handlers share it, call one function from each.
Reset state on an identity change by keying the subtree (<Show keyed>) or by storing an id and deriving the selection from it. To forget a selection when the user navigates away and back, use createVisitState. Never reset state in an effect.
No effect chains, and no effect that notifies a parent: update everything in the same handler or batch.
Don't destructure props; read props.x so the getter stays reactive (splitProps when you must). Call signals when passing them as JSX props. Use <Show> and <For>, not && and .map, in JSX.
Use createStore for objects and collections, createSignal for single values.
Async data goes through createLatest, a resource, or a guarded promise that ignores stale results, under the Suspense rules below, never an effect that fetches and then sets.
Lifecycles follow the State Machines section of packages/app/AGENTS.md: one union, a pure transition, selectors for the UI, and a driver whose results carry attempt ids. Keep the machine state in the plugin's store, not in module state. Precedents: src/terminal/machine.ts, src/wsl/machine.ts, src/updater/machine.ts.

Performance

renderer.tsx loads with the app: src/renderer.ts imports every built-in entry eagerly, because the window renders once all of them are active. Keep it small and put heavy UI behind lazy(). Preload a chunk with onIdle(() => void Chunk.preload()) (from @opencode/plugin/gui/builtin) from setup, so it compiles while the app idles (e.g. on Home) instead of when a session first opens. Never import a heavy chunk on the startup path.
A <Suspense> boundary decides what blanks when something beneath it suspends; it does not stop the suspension. Suspend at most once, on first load, and never after first paint:
- Read async data through createLatest, a store with an explicit loading flag, a resource's .latest guarded on state === "ready" || state === "refreshing" (unguarded, .latest suspends until the first value; see the Suspense section of packages/app/AGENTS.md), or a resource that resolves once (packages/app/src/runtime/server/runtime.tsx, packages/app/src/providers/connect/controller.ts). Never read a refetching resource() in render: a refetch blanks the nearest boundary, and without one of yours that is the whole session route, which detaches the screen and resets the timeline scroll.
- Wrap each lazy() component in its own <Suspense>, so a chunk that is still loading blanks only your area. Preload it with onIdle. If the area can be visible at startup (for example a side tab restored open), start the preload in setup from the stored state instead, so the first render never enters Suspense and nothing pops in.
- Give a fallback the area's size when the area has fixed geometry, so nothing shifts; leave it empty otherwise.
- Make a state change that may suspend inside startTransition, so the current content stays until the next is ready.
Return stable objects from Panel.list and reactive contributions, so the host never remounts a trigger or a panel.
Never add work to timeline rows. The session header slot is the only timeline surface, besides CodeBlock and CodeBlockAction content: the host renders it only for a complete fenced block of a language a plugin lists, and blocks of other languages cost a set lookup.

Localization

Each plugin owns its copy in i18n/en.ts with short keys. ctx.t falls back to the app's keys only for shared vocabulary such as common.*; feature copy belongs to the plugin. Count-sensitive copy goes through ctx.plural.
A plugin bundle's catalog holds every locale inline. A built-in loads its other locales lazily: wrap the catalog in builtinCatalog({ en, de: () => import("./i18n/de") }) from @opencode/plugin/gui/builtin.
Labels follow the language only when the host reads them again. Contribute items with labels in the function form, ctx.add(Command, () => ({ id, title: ctx.t("open"), run })); a plain title: ctx.t("open") in a fixed item never updates. An item with a field of a literal type (hidden: true, a section, an icon, a menu name) needs a return annotation, (): Command => ({ ... }). Objects the host keeps stable keep getters (get title() { return ctx.t("title") }): the tabs Panel.list returns, and items with a render, such as panels and settings pages.
When moving copy, keep the English byte-for-byte and carry every locale's translation. The localization rules in packages/app/AGENTS.md apply.

Tests

Follow the Tests section of packages/app/AGENTS.md.
Unit-test pure logic that carries a contract: path and security checks, storage migration, protocol parsing.
UI behavior is proven by the app e2e keeper suites in packages/app/e2e/regression/. Do not add unit tests that repeat them.
Test a main-process entry through its Ipc contract with real inputs, not through Electron mocks.
The hosts own their contracts, so a plugin does not test them again: main storage in packages/desktop/src/main/plugin/storage.test.ts, the real window host in packages/app/component-tests/plugin-host.spec.ts, and the built-in graph in packages/app/component-tests/plugin-graph.spec.ts.
For lifetime and ordering contracts, drive the race the user hits: a reload during async setup, a rejection that beats its event, a store that loads late (the e2e fixtures can hold desktop storage reads), an Ipc that goes away and returns.
The real window host runs only in the component tests (packages/app/component-tests/plugin-*.spec.ts, with plugin-host.fixture.tsx); they include the graph matrix, which boots the built-ins with each one disabled in turn. Run them with PLAYWRIGHT_STORIES_PORT=3294 bunx playwright test --config playwright.components.config.ts plugin- from packages/app.

23 KiB Raw Permalink Blame History Unescape Escape