# 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](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 `<!-- source: path -->` (a whole file) or `<!-- source: path#name -->` (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](https://react.dev/learn/you-might-not-need-an-effect) and [Solid.js Best Practices](https://www.brenelz.com/posts/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.

## 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.

## 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`.