Plugin Settings Panel (a plugin's own settings screen)
Settings → Plugins is one list of identical rows — the built-in apps and every listed plugin — each opening in place when you click anywhere on its header. A plugin can ship its own settings screen instead of only generated controls; it appears inside the plugin's open row, below its declared fields, with no new permissions. Inside an open row the settings sit flat on the card with thin dividers, without a page's own title and intro. The agent full-access switch that used to sit on the Marketplace card is in a plugin's open row; Marketplace cards no longer carry settings.
On this page
What it is
Settings → Plugins is one page with one list. Image Studio, Mission Control and Council Templates come first, then every turned-on plugin (and any plugin loaded from a folder). Every row looks the same: an icon, the name and one line about it. Clicking anywhere on the row header, out to the card edge, opens the row in place, and clicking again closes it.
- An open plugin row holds the re-approval notice when one is needed, the Open button, the agent full-access switch, its options, its own settings screen when it has one, its version and source, the developer tools for a plugin loaded from a folder, and what access it holds.
- An open built-in app row holds that app's whole settings page.
- A plugin that needs re-approval starts open; a row header also shows DEV, the backend status and Needs re-approval when they apply.
A plugin can ship its own settings screen instead of only the flat list of generated controls; it appears inside the plugin's open row.
Why it exists
A plugin manifest can declare a settings array, and Omniscio generates one control per entry — a
toggle, dropdown, text box, number, or password field. That covers simple preferences and nothing
else. A plugin that needs a "Test connection" button, a list of connected accounts, a chart, or a
sign-in flow had no way to build one.
Where to find it
Settings → Plugins → click the plugin's row. The plugin's own screen shows inside the open row while the plugin is turned on, below its declared fields; nothing replaces the list. A link or search result for Image Studio, Mission Control or Council Templates — or for a setting inside one of them — lands on Settings → Plugins with that app's row already open (on a phone those apps stay ordinary pages).
How it behaves
What the user sees
- Clicking a plugin's row opens it in place; a plugin that declares a panel shows that panel inside the open row (only while the plugin is enabled).
- The page shows the plugin's declared fields first, then the plugin's own screen below them.
- Going back restores the list with your search, sort, and filters intact.
Rules worth knowing
- The panel never replaces the declared fields. They always render above it. If a plugin's own screen fails to load, those fields remain the working way to configure it — a broken panel can never lock you out of your own settings.
- A card shows the button or the inline field list, never both. The detail view already renders those same fields, so showing both would duplicate the same controls in two places.
- Plugin settings stay with the plugin. The panel is reachable only through its own plugin's card, inside the Plugins section. It gets no row in the Settings sidebar and no section id of its own, so a plugin physically cannot place itself in the top-level Settings list.
- No new permissions. The panel is the plugin's own webview at its own entry point, running in the same sandbox with the same bridge access its main screen already had. Declaring a panel grants a plugin nothing extra.
- A plugin's own screen can read and change the fields it declared. The bridge's
settings.getAllandsettings.setread and write the same keys the generated controls use, so a value changed inside the plugin is the value the card shows the next time it opens, and the other way round. The write is validated against the manifest (declared keys only, never a password field, a select value must be one of its options), and the card stays the fallback if the plugin's own screen fails to load. Forms' Settings door is the first plugin surface to do this from inside the plugin's main screen; the write needs no permission. - The settings panel writes under the same rules as the main screen. A plugin's
settings panel is a separate webview from its main screen, so the two are answered
separately: the panel's
settings.setreaches the host, saves the plugin's own manifest-declared keys, and refuses everything the main screen refuses — a key the manifest does not declare, another plugin's key, a password field, and an over-long value. The write is bound to the plugin whose webview made the call, not to anything in the payload, so one plugin cannot save another's settings. A panel that saves its own settings therefore behaves the same whether it is driven from its card or from the plugin's own screen, and a saved value shows up in both. - A field is read-only while its plugin's settings are loading, and after a load failure. The card is showing the declared default then, not the stored value, so typing into it would save a guess over what you actually had. Every control of a plugin shares one settings load, and saving one field merges into that shared copy — so two fields on the page cannot overwrite each other's change. A failed load is reported once under the plugin's fields, not repeated under every one of them.
- Generated fields look like the rest of Settings. The text, number and password fields wear the app's standard compact input, so a plugin setting is never styled differently from a built-in one, and a toggle is announced by its visible label.
- Loaded only when open. The panel is mounted only while its row is open, so opening the page never starts every plugin's settings screen at once.
- Works the same on a phone as any other plugin surface: the declared fields work everywhere, and the panel follows the normal plugin-webview mobile path.
Changing a plugin's settings without leaving it
A plugin's declared fields can also be changed from inside the plugin, in a small window over it.
- Where: the gear in the plugin's side column header (beside the "+" for a new item), or Plugin settings… when you right-click the plugin in the sidebar.
- Shown only for an enabled plugin that declares at least one setting. A plugin with no settings shows no gear and no menu item.
- The same controls as the plugin's card. The window lists exactly the fields its card in Settings → Plugins shows, with the same rules: a change saves at once, a field is read-only while the values load, and password fields work. A value changed here is the value the card shows, and the other way round, because both read and write the one shared copy.
- "More options in Settings" closes the window and opens that plugin in Settings → Plugins, where its own settings screen, its on/off switch and its permissions live. The window never loads a plugin's own settings screen, so a plugin still runs only one screen at a time.
- Done (or Esc) closes it. There is no keyboard shortcut: it is a rare, set-once action.
- A plugin that fills the whole screen (Decks, Forms, GitHub, Newsletter Builder, Calendar
Scheduler) has no side column, so it draws its own gear in its own top bar and asks the app to
open this same window with
Omniscio.host.openSettings(). Until a plugin adds that gear, the right-click item is the way in.
For a plugin author: the gear in your own top bar
- Call
Omniscio.host.openSettings()from your screen. It takes no arguments and always opens YOUR plugin's window: the app reads which plugin called, never a name you pass. - Show the gear only when
Omniscio.host.getCapabilities()lists'open-settings'. An older Omniscio does not list it and has no such call, so a gear shown there would do nothing. The token is offered to a plugin screen on the desktop only, not over the phone relay and not to a plugin's background worker. - Show it only when your manifest declares at least one setting; the window lists exactly those.
Finding a plugin setting from Settings search
- Type a plugin setting's name, or the plugin's name, in the Settings search box or the Ctrl+K search. The result looks like any other: the setting's name, the plugin's name and the setting's description, and Plugins as its section.
- Choosing it opens Settings → Plugins on that exact control: the card's Plugin Settings fold opens for a plugin without its own screen, and the plugin's settings screen opens for a plugin that has one. A search or filter you had typed into the plugin list is cleared for a jump into a card fold. A jump into a plugin's own settings screen keeps the list filters.
- Only enabled plugins appear. Turning a plugin off or uninstalling it removes its settings from search straight away, and a host setting with the same name always comes first.
- What is searchable is exactly what a plugin declares in its manifest: its settings, and any
control of its own screen it named under
ui.settingsSearch. Nothing a plugin's screen draws without declaring it is searchable. - A plugin's text is shown exactly as written, never translated or interpreted, with hidden characters removed. It is not given to the AI search fallback or the agents' settings search, and search statistics record a plugin setting only as "a plugin setting", never by the plugin's name.
Settings a plugin draws itself
A plugin keeps some controls on its own screens: a settings page of its own, a tab inside its main view, or a section inside such a tab. Those controls are the plugin's, so the host never draws a second copy — but the plugin can still make them findable.
- It declares them under
ui.settingsSearch: a name, an optional one-line description, optional extra words a person may type, and a destination. Up to 20 per plugin. - A destination is the plugin's own: a screen (
app-settings), a tab (availability), or a tab with a finer anchor the plugin defines (account#developer). The host passes it through exactly as written and never interprets it. - Choosing such a result opens the plugin's own screen at that destination. Nothing is changed, no action runs, and no record is picked on the person's behalf.
- An entry holds words and a destination, never a stored value, a record, an account or a secret — a plugin cannot index data through this field even by mistake.
- A host older than the field ignores it: the plugin installs and runs, and those entries simply
do not appear in search. An author who wants a hard floor sets
plugin.minAppVersion. - An author validating with an older SDK sees
ui.settingsSearchrefused as an unrecognized key. Update the SDK (@agent-mc/plugin-sdk) or leave the block out.
{
"ui": {
"entryPoint": "web/index.html",
"settingsSearch": [
{ "label": "Font", "description": "The typeface your issues are written in",
"keywords": ["typeface"], "route": "app-settings" },
{ "label": "Timezone", "route": "availability" }
]
}
}
label is 1–200 characters, description up to 500, each keyword 1–40 characters (up to 10),
and route 1–200 with no control characters.
Related
The Plugins page this panel lives inside — installing, enabling and removing plugins — is plugin-marketplace.md. A plugin that ships a screen of its own is the same kind of opt-in its widget makes, described in plugin-widgets.md, and the wider set of capabilities a plugin's own screen may call is plugin-bridge-capabilities.md.
Last verified 2026-11-17