Skip to content

aspiers/ai-config / .agents/skills/managing-orca-plugins

managing-orca-plugins

Verified

Audits, installs, pins, approves, updates and removes third-party Orca plugins (orca-plugin.json, the Orca plugin catalog, Git URL installs and development folders), including trusted-worker plugins that reach Orca's runtime socket. Use before installing, enabling, approving or updating any Orca plugin, when asked whether an Orca plugin is safe, and when reviewing Orca plugin updates. For writing an Orca plugin, use Orca's own orca-plugin-authoring guide instead.

FileKindSize
SKILL.mdskill md6.2 KB
---
name: managing-orca-plugins
description: >-
  Audits, installs, pins, approves, updates and removes third-party Orca
  plugins (orca-plugin.json, the Orca plugin catalog, Git URL installs and
  development folders), including trusted-worker plugins that reach Orca's
  runtime socket. Use before installing, enabling, approving or updating any
  Orca plugin, when asked whether an Orca plugin is safe, and when reviewing
  Orca plugin updates. For writing an Orca plugin, use Orca's own
  orca-plugin-authoring guide instead.
---

# Managing Orca plugins

Load `auditing-third-party-plugins` first: it owns the principles, the audit
procedure and the verdicts. This skill adds Orca's execution model, its
approval and update behaviour, and how to install a plugin so that it stays
on the audited code. Use `orca-cli-local` alongside it for general Orca CLI
rules.

Facts below were checked against Orca 1.4.251's CLI and the `stablyai/orca`
docs on 2026-11-07. Orca's plugin system moves quickly: re-check
`orca plugin --help` and the docs named here before relying on a detail.

## Execution profiles and effective authority

The manifest's `execution` field caps what a plugin may contribute:

- `data`: themes, syntaxes, translations. No code; installs without review.
- `declarative`: commands that run built-in Orca actions, shortcuts, VM
  recipes.
- `sandboxed-ui`: panels and custom editors in an isolated frame that can
  call only the host methods offered to panels. Orca's manifest docs still
  call panel and editor entries "trusted code".
- `trusted-worker`: a `main` Node module that Orca's approval prompt
  describes as running "in a separate Node.js process on the Orca host, with
  your user account's access to that machine". Events, hooks and worker
  commands need it.

For a `trusted-worker`, the declared capabilities only limit the plugin host
API. The worker can still read files and open sockets as the user. In
particular it can read `orca-runtime.json` in Orca's data folder, take the
runtime socket and auth token the `orca` CLI uses, and call the runtime
directly. How far Orca scopes that token was not checked; until it is,
treat effective authority as "whatever the `orca` CLI can do, plus the
user's files and network". Report the gap between that and the approval
prompt.

Watch for contributions that act without the user: `contributes.events`,
`contributes.hooks`, commands with `replaces` (they take over a built-in
action's shortcut and menu entry), and `statusBarItems`, which keep a
worker running for as long as the plugin is enabled.

## Auditing

- Fetch the source into an empty directory as the shared procedure
  describes, and run Orca's static tools on it: `orca plugin validate <dir>`
  and `orca plugin inspect <dir> --json`. `inspect` prints the grants the
  approval prompt will show and the content hash Orca will compute.
- `orca plugin test` and `orca plugin check` run plugin code unsandboxed.
  They fall under the execution freeze.
- Images in a manifest are data, but check that they are what their
  extension says.
- Add to the first-pass search: `orca-runtime`, `authToken`, `ui.set`,
  `terminal`, `agent`, and any runtime method name, since each is a write to
  Orca outside the host API.

## Approval

Anything that runs code needs an approval fingerprint (`ap1-…`). Orca's CLI
says the fingerprint is bound to the plugin, version, files and access, and
that a different set needs a new one. `dev load`, `enable` and the
documented `install` and `update` commands fail with `approval_required`
until re-run with `--approve <fingerprint>`.

Approving grants the access to that exact content. Ask the user before
passing `--approve`, unless they already approved this plugin, version and
access in so many words.

## Updates that skip approval

These are the silent update paths principle 6 of the shared skill asks
about:

- **Same-access updates keep approval.** The docs say an update from the
  same repository that asks for no new access keeps its approval, so new
  code under an unchanged manifest runs without a prompt.
- **Development folders rerun edits.** Orca reloads a development folder
  when its files change, and approved code edits run without asking again.
  Any `git pull` or checkout in that folder is an unreviewed update.
- **Git installs follow their ref.** The docs say a Git install pins the
  exact commit, but `plugin update` moves a version-tag install to the
  newest version tag and a branch install to its newest commit; only a
  commit pin stays.
- **Catalog installs follow their catalog.** The docs say a catalog decides
  which repositories Orca installs and auto-updates from. When Orca applies
  catalog updates without the user acting was not checked.

`orca plugin list --json` shows each plugin's `source` (`resolvedCommit`,
`contentHash`), `consentFingerprint`, `needsReconsent`, and for a
development folder `devChangeCount`. Compare them with the audited identity
after installing and before trusting a plugin again.

## Installing on the audited code

- **Orca 1.4.251 CLI:** it has no `plugin install` or `plugin update`. Clone
  the audited commit, detach `HEAD` at it, keep the checkout somewhere no
  update tool pulls, and run `orca plugin dev load <dir>`. The plugin loads
  as `local.<id>`, labelled `Dev · unverified`. Its updates are only what
  someone does to that checkout, so review any change there first.
- **Newer Orca or the GUI:** the docs describe
  `orca plugin install <owner/repo|git-url>` with `#<ref>` on a Git URL, and
  Settings → Plugins → Add plugin → From a Git URL. Give the full commit SHA
  as the ref so updates cannot move it. Avoid version tags, branches and
  catalog installs for unsandboxed plugins.

Record the source URL, commit, content hash and verdict where the next
audit will find it.

## Removing

`orca plugin dev unload <dir>` removes a development folder;
`orca plugin disable <key>` stops a plugin without removing it. The docs say
uninstalling never needs approval. Plugin storage and settings may outlive
removal: check before telling the user it is gone.

## Sources

- `docs/reference/plugin-authoring.md`, `plugin-manifest.md` and
  `plugin-catalog.md` in <https://github.com/stablyai/orca>
- `skill-guides/orca-cli/references/plugins.md` in the same repository
- `orca plugin <command> --help` in the installed Orca
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall