Plugin Marketplace
Omniscio’s built-in plugin catalogue: what the Marketplace is, where to find it, and how browsing, installing and uninstalling work — the gate on unverified third-party plugin backends, and the approval card an agent’s install request raises. Part 2 covers privacy, ratings and the developer side; part 3 covers updates, version compatibility and package signing.
On this page
Building your OWN plugin from a local source folder (no packaging/marketplace steps) is Plugin Developer Mode — Settings → Plugins.
What it is
A built-in catalog inside Omniscio that lets you browse, install, update, and uninstall Omniscio plugins — without copying files, editing JSON, or restarting the app. Plugins are first-class extensions of Omniscio: they can add virtual sidebar projects (like RepoGuard), drop new menu entries, expose webview-based UIs, and call a sandboxed bridge into Omniscio's IPC.
The Marketplace is one screen: a standalone Marketplace view (Store icon, accessible as a virtual project in the sidebar, with its own category sidebar beside a search + sort toolbar) where browsing, installing, updating, uninstalling, the plugin-detail pages and the developer dashboard all live. Settings → Plugins is where the plugins you already have are listed — it carries its own search box, A–Z/Z–A sort, and status (enabled/disabled) + source (built-in/marketplace/dev) filters over the installed list, shown once you have enough plugins to warrant the bar (the filter/sort logic is the pure, unit-tested plugin-list-filter.ts, and the bar reuses the same SearchInput + Select primitives the Marketplace toolbar does) — plus a Browse Marketplace button that opens that one screen. Settings used to embed a second copy of the catalog here, with its own Install and Uninstall; that is gone, so a plugin can only be installed or uninstalled from one place.
The marketplace solves three concrete problems: (1) you don't have to know which .json manifests Omniscio expects, (2) plugin files are checksum-verified so a tampered registry can't silently swap a malicious bundle into your install, and (3) updates look after themselves — an update that asks for nothing new is applied in the background, and one that wants new access is a single click — Omniscio compares your installed version against the registry and shows an amber Update chip next to anything stale.
Availability (ON by default)
The Marketplace is on by default since 2026-05-28. The sidebar row and Settings → Plugins browser render for every user. To hide it, toggle Settings → Workflow → Features → Enable Marketplace (marketplaceEnabled, default true).
A one-time reset on 2026-05-26 (force-off-features-migration.ts) originally flipped this flag — along with KMS, Marketplace Review, and Tasks Outliner — OFF for every install, including anyone who had been using the pre-flag Marketplace. A follow-up one-shot migration on 2026-05-28 re-enabled marketplace for existing users whose flag had been set to false by that reset, and dropped marketplace from the force-off list (KMS / Marketplace Review / Tasks Outliner are still reset). After that one-time fix, your toggle choice is authoritative.
What ships with Omniscio
Eight plugins are built in — they are already on disk when you install Omniscio, so there is nothing to download and they show in Settings → Plugins with their source as built-in. Only Nighty Tidy is switched on for you. A built-in plugin the online store does not list is on Marketplace → Inbuilt, with its own page and one Install to turn it on; Uninstall turns it off again without deleting its files or data (Inbuilt).
| Plugin | What it does |
|---|---|
AutoHotkey (autohotkey) |
A no-code manager for AutoHotkey hotstrings, hotkeys and snippets — author entries in the app and it generates the .ahk file for you. See AutoHotkey integration. |
Books (books) |
Import and read the EPUB and PDF books you own. See Books. |
Cashbox (cashbox) |
Money in, money out and profit for each of your side projects, captured in plain words; the records stay on this computer, but the sentence you type goes to Claude through your own Claude API key. See Cashbox. |
Daily Spend Report (daily-spend-report) |
Posts a daily inbox card summarising your AI coding value and real out-of-pocket spend from your live ledger. See Daily Spend Report. |
Nighty Tidy (nightytidy2) |
A standalone code-maintenance audit panel — its own audit list, run history and manual Start Run. Ships enabled. See Nighty Tidy 2. |
Pattern Oracle (pattern-oracle) |
Analyses your GitHub pull requests for recurring patterns and delivers weekly intelligence; it needs a GitHub token and your own Claude API key. See Pattern Oracle. |
Virtual Pets (virtual-pets) |
A pixel-art companion that roams your Omniscio window, reacts to your sessions, and keeps you company. See Virtual Pets. |
Whiteboard (whiteboard) |
A freeform infinite canvas for sketching and diagramming, with a board library and an AI agent that can read and draw on a board. See Whiteboard. |
Foundry (prdstack) is a separate case: it is not bundled, so it arrives through the Marketplace, but Omniscio turns it on for you on first run alongside Nighty Tidy. Everything else in the Marketplace — including the plugins listed in Plugin CLI Discovery — is optional and you install it yourself.
Where to find it
The Marketplace is a virtual project in the sidebar — look for the entry carrying the Store icon, usually labelled Marketplace. Opening it gives you the catalogue: a category sidebar down the left, and a search + sort toolbar above the plugin grid.
What you already have installed is also listed in Settings → Plugins, which carries its own search box, A–Z / Z–A sort, and enabled/disabled + source filters. That page is also where the per-plugin switches live: the auto-update check, the app's own agent-access switch, the session-history access panel, and the one-click re-approval a plugin may need.
Opening a plugin's row also answers "what can this app do?" long after the install: a What this app can do list names every power it was granted, one line per permission with what that permission allows, followed by the powers no permission list can show (a background program, AI agent sessions, its approved commands, and programs it ships and runs from its own folder). It is read from what is installed and from the approval you actually gave, so a permission you never granted is not listed, and a plugin that holds nothing yet shows no list at all. The dedicated panels below it (session history, workspace files, documents, email schedules, sign-in) are still where you see the detail and revoke.
Two further views hang off the same feature — the Plugin Developer view, a separate virtual project where a plugin author tracks their own submissions, and Marketplace Review, the admin queue that triages them.
How it behaves
Browsing
A warning strip just below the search bar on Browse, Inbuilt, Installed and Automations says its apps may still contain bugs, especially ones marked Beta. Its ✕ hides it for good: the dismissal is saved as the marketplaceBetaNoticeDismissed setting, so it stays hidden after a restart and on synced devices (MarketplaceBetaNotice.tsx).
- Open the Marketplace. Click the Marketplace entry in the sidebar (Store icon). It opens as two panes: a left filter sidebar (the category list, plus a footer summarizing what you have installed and whether it's current) and the panel holding the search box, the sort dropdown, and the plugin grid.
- Filter and sort. The Browse toolbar holds three controls in one row, all the same height: the search box, a category dropdown (All categories plus each category that has at least one plugin, in the shared category order; a category you picked stays listed even after it empties) and the sort dropdown. Sort offers Most Popular (download count), Newest (most recent publish), and A–Z (alphabetical); a fourth, Highest Rated, is hidden along with the rest of the marketplace's ratings (see Rating below). The category dropdown replaced a row of category chips under the toolbar (MarketplaceCategorySelect.tsx). Inbuilt, Installed and Automations open with the same bar (MarketplaceToolbar.tsx): search, the category dropdown, and a sort. Inbuilt and Installed sort A–Z or Z–A; Automations sorts Most Popular (installs), A–Z or Z–A, and its search also reads a listing's summary. A category that empties under the search falls back to All categories. My Plugins is the developer page and has no bar.
- Search. The search box sits in the panel toolbar beside sort, and matches against plugin name, description, author, and the developer-declared tags. Empty search shows everything in the current category.
Built into Omniscio. On the Inbuilt tab, a Built into Omniscio section lists the apps from the ⋯ header menu that are not already a tool card there; bundled plugins with no published listing are in that tab's Plugins section instead. Unreleased features stay hidden. Each one shows its name, a short description, a Built in badge and an on/off switch, or Always on when it cannot be turned off. Inbuilt search finds these apps too. On every Marketplace card the Install, Uninstall and on/off controls appear on hover or keyboard focus (always on a touch screen). Whether an app opens as a popup or full screen is never shown on a card: it only decides how the app opens and whether it can be pinned to the top toolbar (see customize the header toolbar).
One control, one home. These three used to be drawn TWICE — once in the sidebar and once in the Browse toolbar — bound to the same store state, so they mirrored each other live. Each now has a single home, chosen by what it acts on: search and sort sit next to the grid they reorder; categories sit in the sidebar, where seven items stay visible as a column instead of scrolling off the right edge of a toolbar with no affordance saying so. The same layout serves desktop and mobile — there is deliberately no form-factor variant.
Two things about that split are load-bearing:
- The sidebar's category labels resolve through
marketplaceView.category*. They were raw English literals while the (now-removed) panel pills were translated, so a Spanish user saw an English list mirroring a Spanish one. Now that this is the app's ONLY category filter, an untranslated label would be the only one 17 languages ever see — and no guard catches it, because the hardcoded-string detector cannot see literals inside a const-array of objects.- The panel's search box is the shared
SearchInput, not a hand-rolled<input>. The box this file used to carry was 14px text with no minimum height (a checked-in lint exemption).INPUT_CLASScarriestext-base md:text-sm+min-h-tapprecisely because iOS Safari auto-zooms on a sub-16px input andindex.htmlsets nomaximum-scale— so as the app's only plugin search, the hand-rolled one would zoom an iPhone and never zoom back. A test asserts the rendered classes so a future hand-roll cannot quietly return.On mobile the two panes are separate SCREENS, so
handleSelectCategorynavigates to the results screen unconditionally — including when you re-tap the category you are already on. That is not a redundancy: it is the only route from the filter screen to the results. An early-return-if-unchanged would strand the user on a dead list, so a named test locks it.
- Featured row. In the default browse state (no search, category All) a Featured section headlines the view with a curated shortlist of up to three plugins. There is no editorial
featuredflag on the registry — the picks are derived client-side from the two public signals every plugin carries (rating quality and download popularity) via a Bayesian-weightedcuratedScore, so a single 5-star review can't outrank a broadly-liked, widely-installed plugin. Only plugins with some signal (a rating or a download) are eligible, so a brand-new/empty registry simply hides the row. The moment you search or pick a category the Featured row steps aside, and its picks are held out of the main All plugins list below so nothing is listed twice. The row's old subtitle, "Top-rated, popular picks to get you started," is hidden along with the rest of the marketplace's ratings (see Rating below). The ranking formula is unchanged (a plugin's existing ratings still count), so while ratings stay hidden and no new ones come in through the app, the picks come down mostly to downloads. - Read the cards. Each plugin card shows the icon, name, one-line description, download count, version, author, and category (the star rating that used to sit here is hidden, see Rating below). An amber Update chip appears if you have it installed and the registry has a newer version. The download count goes up with every package download (a first install, a reinstall and an applied update all count), so it measures downloads rather than people. The store's catalog, each plugin's page, the download counts and the ratings can be up to 30 minutes behind for other people: the marketplace server keeps a copy for that long so browsing costs almost nothing however many people use it. While the list of plugins itself is unchanged, Omniscio reuses the catalog it already has instead of downloading it again, so in an app left open for days the download counts and star averages on the cards can be up to a day old; a new or edited review shows on that plugin's page on the next view. An admin who approves, edits or withdraws a listing sees the change straight away. Test and throwaway copies of Omniscio do not download Foundry automatically, so they do not inflate its count (details).
- Trust signals (A3) let you judge a plugin before opening it. A blue Official badge next to the name marks a plugin built and maintained by the Omniscio team (a Community badge marks every other, third-party plugin). Both are derived from a fixed first-party id allowlist in marketplace-trust-signals.ts — never a registry-supplied flag, so a third party can't claim "Official". Below the description a row of permission chips shows exactly what the plugin requests: elevated-access capabilities (network, process, filesystem, cloud, or your identity) are amber
warningchips with a shield icon; benign ones (storage, sessions, notifications…) are neutral. Past four chips the rest collapse into a +N more chip, and elevated-risk chips are always shown first so a benign one can't push a risky one under the fold. Below them a powers row names the things no permission row can express: that the app runs a background program on your computer, starts AI sessions, can start programs already installed here, or runs programs bundled in its own folder — the last two name them in the chip's tooltip. It reads from the listing's own declaration, so two apps can be compared by reach before either is installed, and each chip is simply absent when the app doesn't declare that power. A listing published before these fields were recorded says so instead of staying silent: the card carries a neutral Powers not listed chip and the detail page says the powers are unknown, rather than reading as "asks for nothing" (the install screen still always tells you what the package itself declares).
- Trust signals (A3) let you judge a plugin before opening it. A blue Official badge next to the name marks a plugin built and maintained by the Omniscio team (a Community badge marks every other, third-party plugin). Both are derived from a fixed first-party id allowlist in marketplace-trust-signals.ts — never a registry-supplied flag, so a third party can't claim "Official". Below the description a row of permission chips shows exactly what the plugin requests: elevated-access capabilities (network, process, filesystem, cloud, or your identity) are amber
- Open the detail page. Click a card's name, icon, or description to open the plugin's full page; the name is a real button, so Tab then Enter opens it too. The card's Install / Update / Uninstall / on-off / Settings controls keep their own jobs and never open the page. The page takes over the Marketplace panel (loaded on demand through
lazyNamedView). It opens at once showing what the card already knew: the back button, name, version, icon, the author's name as plain text (the View on GitHub link was removed, since it pointed at display names and was broken for most plugins), description, download count and a working install/update/uninstall button. Only the tabs and the detail cards below need the full plugin record, so only they show shape-matched shimmer placeholders until it arrives; the header and top card are the same elements throughout, so nothing jumps. On the first plugin opened in a session the page's own code is still loading for a moment, so the back and install buttons are briefly placeholders too. The page's icon matches the card's icon (uploaded logo first, then the declared glyph, then the first letter of the name), and reduced motion turns off the shimmer. Below it the page splits into tabs (UnderlineTabBar, which owns the WAI-ARIA tablist contract — roving tabindex,aria-controls, Arrow/Home/End): Overview (screenshots, the metadata grid — category, license, package size, minimum-Omniscio version, last-updated, each field self-omitting when absent and the whole card hidden if the registry record carries none of them — the README, the installed plugin's settings, related plugins, and the ratings panel, hidden for now — see Rating below), Permissions (the same powers written out in full sentences above the permission list, then version history), and Support. Opening a DIFFERENT plugin resets the tab to Overview, so you never land on a tab the new plugin does not have. The README is drawn in a restricted mode because a publisher wrote it — see Text a plugin's publisher wrote in part 2. Raw HTML in it (tags, comments, a badge written inside an HTML block) is dropped: the tags go, the words stay, and nothing prints as<p align="center">or. Publishing also refuses such a README up front:amc-plugin preflightfails a root README with raw HTML, a badge image, a Developer notes section or more than 3,000 characters, naming the line and pointing todocs/DEVELOPMENT.md. Opening it fetches:selectPlugin(id)loads theMarketplacePluginDetailrecord (MARKETPLACE_GET_PLUGIN_DETAIL) and the first page of reviews (MARKETPLACE_GET_RATINGS). Back, Esc (ignored while typing or while a dialog is open) or the Browse breadcrumb returns to the grid and puts keyboard focus back on the plugin's name (use-plugin-page-navigation.ts); a failed load keeps a Back button beside Retry. At phone width the install/uninstall button wraps under the description.- The page once had no way in for four months. A May 2026 change dropped the view's only mount of the page while the page itself kept compiling and passing its own tests. The guard renderer-screens-have-a-production-importer.test.ts now fails when any renderer screen loses its last production importer.
Installing & uninstalling
6a. Enlarge a screenshot. Each screenshot on the Overview tab is a real <button>, so it is reachable by Tab and opens full-screen in the shared ImageLightboxShell — arrow keys move between shots, Esc closes. Esc while the viewer is open closes only the viewer; the page's own Esc-to-go-back stands down until it is shut.
6b. See related plugins. The foot of the Overview tab lists up to four other plugins in the same category, so the page is not a dead end. It filters the registry list the store already holds (no extra fetch) and is absent when the plugin is alone in its category.
6c. Reach the developer (Support tab). A publisher may declare links in their manifest — homepage, support, privacy, contact, repository, each optional. Whichever they set appear on a Support tab with the destination host shown beside each one. Only http:/https: URLs are ever rendered or opened: they are validated at publish time by manifestSchema and re-validated at render, because registry rows written before the field existed never met that validator. The tab exists only when at least one link survives that check.
6d. Play the preview. A plugin whose listing carries a promotional film shows a Play the preview button in the top card of its page, beside Install. Clicking opens the film from Omniscio Shares: in the system browser, or in the in-app Shares viewer when the link is one of your own shares. Nothing plays on the page and the film is never embedded. The button appears only for the store's own canonical link, https://shares.omniscio.com/s/<id> with an id of lowercase letters, digits and hyphens (up to 80); a missing, malformed or off-site link shows no button, and a bad value never stops the page from loading. The tooltip shows the host it opens.
Install. From either the card or the detail view, click the blue Install button. Omniscio downloads the package and reads the manifest that actually arrived, then either installs it or opens a consent dialog (
PluginConsentDialog) when the package would grant something you have not agreed to. The dialog lists every permission the plugin declares, and if the package declares one the Marketplace listing did not show it opens with an amber warning saying the listing showed less and marks that row Not listed — the listing is served text and the package is the truth, so a package can never widen what you grant from a listing that showed less. It also — when the plugin ships a background process — says so in plain words underneath: it runs on your computer with direct access to your files, the network and other processes, which the permission list cannot limit. It says the same about agent sessions: a package declaringsessionToolsshows "Can start AI agent sessions on this computer with full tool access to your projects, so it can read and change your files and run commands in them. Each session uses paid AI time." That is the third power the permission list cannot express, and it is disclosed for the same reason as the background process — the flag is not a permission, so no row above it would say so. When the plugin declares one of the newest powers (Tasks, the Vault, Calendar, Inbox, People, session control or Team Chat) that is switched off on this computer, the dialog adds one note: "Some of what this plugin does isn't turned on yet on this computer, so those parts won't work until it is." The install still goes ahead; the note only says what will not work yet. There is no separate switch to tick: approving the screen is the grant. A plugin that declares no permissions and ships no such process installs straight away with no screen, so the common case stays a single click. The button swaps to a spinner; on success a toast confirms (Installed <plugin name>). The plugin's files land in<userData>/plugins/<plugin-id>/, the sidebar surfaces any new virtual projects the plugin declared, and any IPC bridges come online. The plugin is also added toenabledPluginsin settings.The decision is made in the main process, from the downloaded package — not by the Marketplace screen. The registry row carries the permissions the publisher declared and, for a listing published since these powers were recorded, the powers the manifest itself declares (
hasBackend,sessionTools, and the programs it may run —allowedCommandsandpinnedPrograms— plus the websites it uploads to,uploadHosts, named on the card and the plugin page). A row PUBLISHED EARLIER carries none of them and nopowersKnownflag, so the two surfaces say its powers are unknown rather than claiming it asks for nothing;firebase/marketplace/scripts/backfill-plugin-powers.mjsrecords them for plugins already published by re-reading each one's own package, and only the package's own manifest can always answer it — that distinction is the whole point of the screen, so the row's flags are what the disclosure surfaces can say, never what decides.Uninstall. On the detail view, click the Uninstall button (red, with trash icon). Same spinner/toast pattern; the plugin's directory is deleted recursively and the virtual project is soft-deleted from the sidebar. Uninstalling also deletes everything the plugin saved for the account you are signed in with — its records, its settings and its stored passwords, all in one transaction. Plugin data is kept per Omniscio account, so if someone else signs in on the same computer they start with an empty plugin space of their own, and uninstalling never removes their data. Reinstalling brings the plugin back but not the data, and the confirm dialog says so before you commit. A backup left beside the plugin by an interrupted update is removed with the install as well, so the deletion cannot leave a copy of what you asked to delete behind. This is the only path that deletes it: merely disabling a plugin keeps everything (disable is reversible), and so does the automatic check that removes a plugin pulled from the registry — a plugin revoked that way keeps its rows until you uninstall it yourself. That automatic check only ever removes one plugin at a time: if a catalog fetch comes back empty, or would drop more than one of your installed plugins at once, it removes nothing and logs the reason, because a truncated or degraded reply is far more likely than several publishers leaving simultaneously — and the cost of guessing wrong in the other direction is your whole plugin set being uninstalled unattended. A few plugins are exempt outright, either because their data has no second home or because it was migrated out of an Omniscio table and can't be restored by reinstalling; see plugin-data-purge-contract.md.
Update. In-place reinstall — click Install again on a row showing the Update chip and Omniscio atomically swaps in the newer files. Local plugin data is untouched; only the bundle files are replaced.
What turning a plugin off does to its sessions
Turning a plugin off hides its sidebar entry, and the sessions inside it are filed away with it (idle ones go to the archive, a session waiting on you is stopped first). Turning the plugin back on brings those sessions back as ended sessions you can reopen. Only sessions filed away by that hide come back; anything you archived yourself stays archived. Uninstalling works the same way, so a later reinstall also brings them back. Scheduled jobs the plugin owned are removed when it is turned off and are not restored. A reload (from the dev watcher or POST /plugins/:id/reload) is not a turn-off: it leaves the sidebar entry, every session and every schedule alone. A plugin that was reloaded or turned off before this fix gets its filed-away sessions back the next time it is turned on or reloaded.
Workspace-only plugins
A plugin can be limited to one workspace. Its manifest names the workspace (plugin.requiresOrganization), and Omniscio then shows it in Settings → Plugins and lets you turn it on (in Marketplace → Installed) only while that workspace is your active one. Anyone else never sees it, and turning it on from the CLI (POST /plugins/:id/enable) is refused with a plain "only available to members of its workspace" message. Switch to the right workspace and it appears.
This hides the plugin; it does not protect data. The plugin's code ships in every install, so a workspace-only plugin must keep its data behind its own server-side lock — the first one, the JLS SOP Assistant, keeps its library behind database rules that refuse anyone outside the workspace.
Third-party plugin backends (security gate)
Some plugins ship a backend that runs with full system access (file system, network, child processes). Omniscio cannot verify a third-party (marketplace) plugin's backend, so it starts only while your own approval of that plugin is current — the version you approved, the permissions it declares, and the fact that it ships a worker. Approving the install or enable screen is what grants it, and a later version that changes any of those asks you again rather than starting on the old answer. Built-in plugins ship with Omniscio and are always allowed.
There used to be a global Settings → Plugins → Allow unverified plugin backends switch beside this. It is gone: it could overrule a plugin you had refused, and it could not answer for one you had never been asked about, while the plugin's own record decided the same question. Nothing to configure — approve the plugin and its backend runs; a plugin whose backend you withhold (or whose approval has fallen behind) shows Needs your permission on its card, with a Re-approve button.
Turning a plugin on always says what it is asking for — including the background process and the agent sessions. One dialog asks for your consent, on every surface that can turn a plugin on (the Marketplace grid, Marketplace → Installed, and a plugin's detail card), and when the plugin ships a backend it says so outright: "Runs a background process with full access to your files, network and programs." That line matters most for a plugin that requests no ordinary permissions, because a backend alone is enough to need your consent — so before this, the one prompt whose entire content was a full-access background process was also the one prompt that never mentioned it. A manifest declaring sessionTools gets its own line in the same dialog, worded once and shared with the install screen and with the approval card an agent raises, so the three surfaces cannot describe the same power three different ways. Declining says why nothing happened and grants nothing; only the confirm itself approves.
An update to a running plugin takes effect immediately — its background half is restarted as part of the update. A plugin's background half is a separate program that loaded its code when it started, so swapping the files underneath it changes nothing about what it is executing. Applying the update therefore stops that program and starts a fresh one from the new files, and the update is not finished until it has. Before this, an update replaced the files but left the old program running: the plugin kept behaving as the previous version for the rest of the session while the version number, the files on disk and their checksums all reported the new one — a mismatch nothing surfaced. If the restart itself fails you are told so ("… its background service didn't restart"), the plugin stays switched on, and the next launch retries it. A floating overlay window and a popped-out panel are refreshed by the same update, so they cannot keep showing the previous version's screen either.
A background plugin stays approved across its updates — and tells you exactly which one if it doesn't. When you apply an update to a plugin whose background half is running, Omniscio records your permission for the new version (whichever way you approved it, you were shown the newly-requested permissions first — see the next section), so the restart above does not stop to re-ask, and the next launch cannot strand the plugin on a stale permission record either. In the rare case a background plugin still needs re-approval — at startup, or when its files are reloaded while the app is running (a developer reload, or an agent swapping in a new build) — Omniscio raises an inbox notice that names the affected plugin ("GitHub needs your permission again"; for two, "GitHub and Calendar need…"; for more, "GitHub and 2 others…") with a Re-approve button. Re-approve opens that plugin's permission screen directly: it lists what the plugin wants, and Grant & Enable records your permission and starts it. The notice clears itself once you have granted; if two plugins were waiting, it updates to name the one still left. It stays one notice no matter how many plugins are affected, and never silently leaves a plugin's background half dead and looping. A new version still asks again even when it requests the same permissions as before.
That same "Needs your permission" callout + Re-approve now appears everywhere you might meet the dead plugin, not just Settings: on its Marketplace card and its Marketplace detail page (so browsing to a misbehaving plugin offers Re-approve instead of only Uninstall). You don't have to go looking for it either: the moment a plugin starts needing re-approval, a pop-up names the plugin ("GitHub needs your permission again") wherever you are in the app, once per plugin version. It fires again the moment you open that plugin — when its panel would otherwise just sit there loading, because the UI opens but its background half is dead. Both pop-ups carry a Re-approve button that opens the plugin's permission screen directly. They never stack, and stay silent for a healthy plugin and on mobile (where a plugin backend can't run at all). All four surfaces (Settings, the Marketplace card + detail, and the toast) reuse ONE shared callout component and the existing translated strings — so they can never drift, and the recovery is reachable from wherever you are.
A new permission stays off until you approve it — even if the plugin's files changed underneath you. A plugin can only use the permissions you actually approved. If its folder is replaced and reloaded with a version that asks for more (for example Text to Speech), the permissions you already approved keep working, and the new ones stay switched off until you approve them. The plugin shows the same "Needs your permission" callout and Re-approve button, including plugins that have no background half. When an agent asks to turn a plugin on, the approval card carries the exact list it was raised for, and the confirm dialog shows that list, not an older copy. If the plugin changes again before you click Approve, the approval is refused and you're asked to request it again, so an approval can only ever cover what you were shown. Built-in plugins and plugins you load from your own folder in Developer Mode are not affected.
When a plugin's panel never finishes opening
A plugin's panel never sits on its loading spinner, or on a dead frame, for good. Three things end at the same "This plugin couldn't load" card with a Try again button:
- The page failed to load (the plugin's server refused the connection, the entry file is missing).
- The page never answered. A plugin server that accepts the connection and then goes silent reports neither success nor failure, so the panel gives it 30 seconds (
PLUGIN_GUEST_LOAD_DEADLINE_MSin PluginWebviewHost.tsx) to reach its firstdom-ready. It is a backstop for "never", not a speed limit: the page comes from the app's own loopback plugin server, so a healthy open is quick and a slow cold open on a busy computer still finishes well inside it. The deadline covers the FIRST load only: a page that loaded and is later reloaded in place keeps what it had. - The page's process died after it opened (
render-process-gone). A process that left on purpose (clean-exit) is not a crash and is ignored, the same way ShareViewerWebview.tsx reads it.
A frame inside the panel failing to load is not the panel failing. A plugin that embeds a third-party player (Courses' YouTube and Vimeo blocks) reports that frame's network failure to the host as a load failure for the page, and the host ignores it: only a failure of the panel's own page ever shows the card, so no blocked embed can take the whole panel away. The guest is told which address failed so the block can offer its own fallback instead.
Try again mounts a fresh panel, and everything the host listens for (the first dom-ready, a failure, the deadline, a crash) is attached to that new panel too, which is why both of those listeners re-run when the error clears. Before this, a retried page that loaded fine stayed under the spinner, and a second failure showed no card at all. A retry reopens from the HTTP cache (the page address carries the installed version), so a page that was merely slow costs one click. On a phone the panel is an embedded frame rather than a desktop webview and none of this applies there. Locked by plugin-webview-host-guest-liveness.test.tsx.
Opening a plugin on your phone
On a paired phone, a plugin opens its own screen only when it is on the phone list (Foundry, GitHub, Smrzz, Newsletter, Forms and Calendar Scheduler) and its code ships inside the app. A plugin can also rule itself out: Decks declares itself desktop-only, so it shows "This plugin is only available on the desktop app" too. Every plugin off the list shows that same notice.
- Plugins installed from the store stay on the desktop for now. The phone shows a plugin inside the app's own page, so plugin code there would carry the app's full access. Only code that ships with the app is trusted with that, so a plugin you installed from the store, loaded in Developer Mode, or previewed shows "This plugin cannot be opened on your phone yet. Open it on your desktop." Today the listed plugins install from the store, so on most computers they show this notice.
- Opening store plugins on the phone is planned behind a separate change that walls each plugin screen off from the app.
- The phone can only do what the desktop plugin could. Every action still passes the same permission checks, and actions that need the desktop (a file picker, a disk export) say so. The plugin's toolbar buttons and session-menu items stay desktop-only.
How it works and what it guards against: mobile-plugin-ui-bridge.md and mobile-plugin-serving-contract.md.
When an agent asks to install a plugin (the approval card)
An agent can request a plugin install over the CLI control server (POST /plugins/install). It cannot install anything on its own — the request becomes an approval card in your inbox, and nothing is downloaded until you approve it.
The card tells you what approving actually grants. It names the plugin, the exact version being installed, and the permissions that version is asking for. If you already have the plugin, the card reads as an update — Update plugin "Foo" from v1.4.0 to v2.1.0 — and lists only the permissions the new version wants that you have not already granted, the same "requests new" comparison the in-app Updates modal shows. An update that asks for nothing new says exactly that, so a card with no permission line never leaves you guessing whether it was checked. Every requested permission is listed; the card never abbreviates the list, because the order they appear in is chosen by the plugin's author and a shortened list could hide the one that matters.
This matters because asking to install a plugin you already have is how an update gets applied. Approving the card is what grants the new version's permissions, so the card has to say what they are.
Clicking Approve shows you what the plugin will be able to do, the same way the Marketplace does. Approving an agent's install request IS the consent — nothing prompts you a second time afterwards — so the confirm that opens lists each capability in plain words ("Storage — read and write plugin data, files, and database records"), flags elevated ones, and calls out separately that the plugin runs its own background program with access the permission list cannot limit. It is an amber caution, not a red destructive warning, because installing a plugin deletes nothing; it says so outright, and Enter defaults to Cancel so a stray keypress cannot grant anything. Turning a plugin on or off reads the same way. Uninstalling keeps the red warning, because it really does delete the plugin's files and everything it saved. If the capability list genuinely cannot be loaded, the confirm shows the card's own description instead of an empty list, so a failed lookup never reads as "this plugin asks for nothing".
System is one of the flagged ones. That permission reads and replaces everything on your clipboard at any time, opens files inside folders you grant, and runs the helper programs the plugin's manifest declares, and after install nothing asks you again each time. So the System row carries the same warning icon and "Elevated" tag as the microphone and email permissions, rather than sitting among the ordinary ones.
If Omniscio can't describe the install, it won't ask you to approve it. A plugin id the marketplace doesn't carry, a marketplace it can't reach, or a listing it can't make sense of all refuse the request outright rather than raising a vague card. You will never be asked to approve an install described only as "runs third-party plugin code".
What you approve is what installs. The version named on the card is locked in. If the marketplace publishes a newer version while the card is sitting in your inbox, approving it does not quietly install that newer one — the install is refused and you are told to request it again, so you can see what the new version is asking for. A repair or reinstall of the same version is unaffected.
The card also says when the plugin runs a background program or uses agent sessions. Those two powers are not permissions, so no row of the permission list can express them; the card reads them from the listing's own declaration. A listing that declares agent sessions gets the same sentence the install and enable screens use, and approving it covers that power — so an agent can install such a plugin for you. A listing that declares it runs a background program says so; a listing that says it does not drops that line. A listing published before this information was recorded says so with a Powers not listed chip rather than staying silent, and there the card keeps the safer default: it still tells you a background program may be involved, and it will not claim your approval covers agent sessions — so a plugin that truly uses them is refused and you are sent to the Marketplace, where the downloaded package itself is read.
Installing from the Marketplace yourself is unchanged: you see the permissions on the detail page and in the consent dialog before you click, so there is no gap for the version to move in.
Turning a plugin back on after its files changed
- Turning a plugin on re-reads its manifest from disk first, so the plugin card, the plugin list and the worker all agree on one version.
- If the new version asks for a permission you have not approved, Omniscio shows the consent prompt again instead of starting it.
- If the manifest can no longer be read, the plugin stays off and Omniscio tells you to reinstall it from the Marketplace.
Related
- Plugin Marketplace — part 2 — what a plugin may read and watch, ratings and reviews, and the developer side
- Plugin Marketplace — part 3 — keeping installed plugins current, version compatibility, and package signing
- plugin-cli-discovery.md — discovering and driving installed plugins from any session via CLI
- repoguard.md — first plugin shipped through the marketplace
- prdstack.md — second plugin shipped through the marketplace
- calendar-scheduler.md — the free Calendly-style booking plugin: event types, availability, a public booking link and Google Calendar bookings
- newsletter-builder.md — the free newsletter plugin: real-news issues on a schedule, an in-app reader, email to readers and AI sessions opened from a story
Last verified 2026-10-12