--- title: Plugin CLI Discovery (using plugins from any session) --- # Plugin CLI Discovery ## What it is A way for any Claude Code session running inside Omniscio to **discover** which marketplace plugins the user has installed and, when the plugin supports it, **drive** them programmatically via CLI endpoints. This closes the gap where a session might not recognize a plugin by name (e.g. "use smrzz to summarize this video") and incorrectly tell the user the tool does not exist. Plugins are first-class extensions of Omniscio installed via the [Plugin Marketplace](plugin-marketplace.md). Each plugin adds capabilities to Omniscio: content summarization, GitHub workflows, calendar scheduling, newsletter building, repo scanning, and more. The marketplace is open, so new plugins can appear at any time. ## Where to find it This is an agent-facing surface, not a screen you click — there is no panel for plugin discovery, and nothing in the app is named after it. The user-facing counterpart is each plugin's own sidebar panel, which opens from wherever that plugin sits in the app and is where you drive a plugin by hand. Plugins themselves are browsed, installed and removed from the Plugin Marketplace. ## How it behaves ### When to use this **Any time the user mentions a tool, service, or integration by name and you do not recognize it**, check whether it is an installed Omniscio plugin before saying you cannot find it. The user may reference a plugin by its short name (e.g. "smrzz", "repoguard", "prdstack") without explaining what it is, because they installed it and expect you to know. ### How to discover installed plugins Call the Omniscio CLI endpoint: ``` GET http://127.0.0.1:19519/plugins Authorization: Bearer $AMC_CLI_TOKEN X-AMC-Source-Session-Id: ``` Response: ```json { "ok": true, "data": { "plugins": [ { "id": "smrzz", "name": "Smrzz", "version": "1.2.0", "enabled": true, "hasSidebar": true, "requiresConsent": true } ] } } ``` Each entry tells you the plugin's `id` (used in CLI paths), display `name`, `version`, whether it is `enabled`, whether it has a `hasSidebar` panel, and whether it `requiresConsent` (has declared permissions). This endpoint is always available (not feature-gated) and requires only your session's own `$AMC_CLI_TOKEN` bearer auth — no install-wide key file is needed. ### How to interact with a plugin #### Via the plugin's sidebar panel (user-driven) Every plugin with `hasSidebar: true` has its own panel in the Omniscio sidebar. The user can open it and interact with the plugin's UI directly. If you discover a plugin is installed but cannot drive it programmatically, tell the user they can use it from its sidebar panel. #### Via CLI endpoints (agent-driven, when available) Plugins that declare CLI endpoints can be driven programmatically: ``` GET/POST/PUT/PATCH/DELETE http://127.0.0.1:19519/plugins//cli/ Authorization: Bearer $AMC_CLI_TOKEN X-AMC-Source-Session-Id: ``` For example, to check connection status of the smrzz plugin: ``` GET http://127.0.0.1:19519/plugins/smrzz/cli/status ``` `` is a multi-segment route — a plugin may register nested actions, and you call them with slashes as usual. For example, to summarize a URL via the smrzz plugin's nested `summarize/url` action: ``` GET http://127.0.0.1:19519/plugins/smrzz/cli/summarize/url?url=https://example.com ``` **Note:** The CLI forwarder ships always-on (landed 2026-08-06) — no Lab flag gates it. An unknown plugin id returns 404; a plugin that is not enabled, or whose worker is not running, returns 409. If a plugin cannot be driven programmatically, guide the user to the plugin's sidebar panel instead. #### Approval-gated actions — ask first by default Plugin actions ask the user first by default. A call reaches the plugin without the user only when the plugin declared that exact method + path as a read (a `GET`) or marked it `safe` in its manifest. Everything else — posting a comment, creating a PR or issue, editing, deleting, publishing, or any action the plugin never declared — waits for approval, no matter which key you called with. One more case asks too: if the plugin flagged any action on a path as needing confirmation, every call to that path asks, reads included, because the plugin receives calls by path, not by method. When an action needs approval, the response is HTTP 202 with `{ "approvalRequired": true }`. This means the action has been queued and the user will see an approval card in their Omniscio inbox — never claim the action ran; re-check with a read afterwards to see what actually happened. The action executes only after the user approves it there. A path the plugin has no handler registered for answers 404, whether or not it would have needed approval. **Always allow one action.** On the approval card, the user can choose "Always allow this action for \" (a confirm step, with a stronger warning when the plugin itself marked the action as needing confirmation every time). From then on that one action of that one plugin runs straight away and its result goes back to the AI — nothing else about the plugin is affected, and there is never an "Everywhere" option for plugin actions. Grants are listed and removable at **Settings → CLI Control → Always-allowed actions**, where a grant shows "Not active" if the plugin is removed or no longer offers that action. Only a person can give this answer — never an AI. #### For plugin authors: the `safe` mark A manifest endpoint may mark itself `"safe": true` so it runs without asking. `safe` means the action only reads (including asking Omniscio's AI to summarize or explain), makes a small local change that is easy to undo, or starts or finishes a sign-in the person approves themselves in the provider's own consent screen. It never acts outside Omniscio in the user's name, deletes or overwrites content, publishes, or changes settings or credentials in any other way. An endpoint cannot be marked both `safe` and `requiresConfirmation`. ### Known plugins (as of 2026-07) These are the "Our Four" AI-native plugins that are available in the marketplace. This list is not exhaustive; always use `GET /plugins` for the current truth, and see **[What ships with Omniscio](plugin-marketplace.md#what-ships-with-omniscio)** for the eight plugins that come built in with the app. | Plugin | ID | What it does | | ---------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Smrzz** | `smrzz` | AI-powered content summarization (web pages, videos, podcasts) via smrzz.com. 18 CLI endpoints: connection management, summarize URLs, browse/search/export a library of past summaries. Long-running summarization returns a job ID to poll. | | **GitHub Integration** | `github-integration` | GitHub workflows: issues, PRs, code search, releases. | | **Calendar Scheduler** | `calendar-scheduler` | Calendar scheduling and event management. | | **Newsletter Builder** | `newsletter-builder` | Newsletter creation and management. | ## For agents - CLI routes (GET /plugins, CLI forwarder) -- [src/main/services/cli/cli-server-plugins-routes.ts](/src/main/services/cli/cli-server-plugins-routes.ts) - Plugin context provider (for plugin-surface sessions) -- [src/main/services/session-context/plugin-provider.ts](/src/main/services/session-context/plugin-provider.ts) - Omniscio awareness prompt (teaches all sessions about plugins) -- [src/main/process/spawn-system-prompts.ts](/src/main/process/spawn-system-prompts.ts) ## Related Browsing, installing and uninstalling the plugins this page discovers is [plugin-marketplace.md](plugin-marketplace.md), and the in-plugin session experience — sessions started from within a plugin's own surface — is [plugin-ai-native-sessions.md](plugin-ai-native-sessions.md). For the read-only card that tells a person which of a plugin's actions its AI can take, see [plugin-capability-card.md](plugin-capability-card.md), and for the wider set of capabilities a plugin's own screen may call, see [plugin-bridge-capabilities.md](plugin-bridge-capabilities.md).