---
title: Plugin Settings Panel (a plugin's own settings screen)
---

# Plugin Settings Panel (a plugin's own settings screen)

## What it is

A plugin can ship its **own settings screen** instead of only the flat list of generated controls.
Its card gets a **Settings** button that opens that plugin's settings full-width, with a back link
to the plugin list.

### 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 → the plugin's card → Settings.** The button sits on the plugin's card and
shows only while the plugin is enabled. Clicking it replaces the plugin list with that plugin's
settings, full width, with a back arrow in the header that returns you to the list.

## How it behaves

### What the user sees

- A plugin that declares a panel shows a **Settings** button on its card
  (only while the plugin is enabled).
- Clicking it replaces the plugin list with that plugin's settings, full width,
  with a back arrow in the header.
- 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.
- **One screen at a time.** The panel is loaded only while its detail view is
  open, so a plugin never runs its main screen and its 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.

## For agents

### What a plugin author does

Add one optional block to `manifest.json`:

```json
{
  "ui": {
    "entryPoint": "web/index.html",
    "settingsPanel": { "entryPoint": "web/settings.html" }
  }
}
```

`entryPoint` is a path **relative to the plugin's own folder**. A value with a
scheme (`file:`, `http:`), an absolute or drive-qualified path (`/etc/…`,
`C:\…`), or a `..` segment is rejected when the manifest is validated — so a bad
path fails at install with a readable reason instead of at runtime with a blank
frame.

The field is optional. A plugin that omits it keeps today's behaviour exactly.

Contract: [plugin-settings-panel-contract.md](../../.claude/memory/contracts/plugin-settings-panel-contract.md)

## Related

The Plugins page this panel lives inside — installing, enabling and removing plugins — is
[plugin-marketplace.md](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](plugin-widgets.md), and the wider
set of capabilities a plugin's own screen may call is
[plugin-bridge-capabilities.md](plugin-bridge-capabilities.md).