orca/docs/reference/plugin-manifest.md

Orca plugin manifest reference

The orca-plugin.json file at the root of an Orca plugin (manifest format 2).

Add "$schema": "https://raw.githubusercontent.com/stablyai/orca/main/docs/schemas/plugins/orca-plugin.v2.schema.json" to orca-plugin.json for completion and inline errors in your editor. Since is the first Orca release that reads the field; raise engines.orca when you use a newer one.

Fields

Field	Type	Required	Since	Description
$schema	string	no	1.4.245	JSON Schema URL for editor completion. Ignored by Orca.
manifestVersion	2	yes	1.4.245	Manifest format. Use 2 for new plugins.
execution	"data" | "declarative" | "sandboxed-ui" | "trusted-worker"	yes	1.4.245	Most authority the plugin needs, least first: data (themes, syntaxes, translations), declarative (commands, shortcuts, recipes), sandboxed-ui (panels), trusted-worker (main and events). Contributions beyond it fail validation. Example: "data"
id	string	yes	1.4.160	Plugin id, kebab-case. The install identity is <publisher>.<id>. The reserved names constructor and prototype are refused. Example: "gleam-syntax"
publisher	string	yes	1.4.160	Publisher slug, kebab-case. Must be the GitHub or GitLab user or organization that owns the repository (acme for github.com/acme/gleam-syntax), or the official and community catalogs reject the listing. The reserved names constructor and prototype are refused. The publishers stablyai, official, anthropic, openai, github and any starting orca (any case), and ids starting orca-, install only from Orca's official catalog. Example: "acme"
name	string	yes	1.4.160	Display name. Example: "Gleam"
version	string	yes	1.4.160	Plugin version, semver. Example: "1.2.0"
description	string	no	1.4.160	One or two sentences shown in the plugin list.
author	object	no	1.4.160	Who maintains the plugin.
author.name	string	yes	1.4.160	Author or organization name. Example: "Acme"
author.url	string	no	1.4.160	Author homepage. Example: "https://example.com"
repository	string	no	1.4.160	Source repository URL. Example: "https://github.com/acme/orca-gleam-syntax"
license	string	no	1.4.245	SPDX license expression. Example: "MIT"
homepage	string	no	1.4.245	Project homepage, https only. Example: "https://example.com/gleam"
icon	string	no	1.4.160	Square image shown beside the plugin name. PNG, WEBP, static, at least 128×128, square, at most 256 KB. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "assets/icon.png"
engines	object	yes	1.4.160	Host versions this plugin supports. Older hosts refuse to load it.
engines.orca	string	yes	1.4.160	Oldest Orca release this plugin runs on, as >=x.y.z. Raise it to the newest "Since" of any field you use; a format 2 manifest needs at least >=1.4.245, because older Orca cannot read format 2. Example: ">=1.4.245"
main	string	no	1.4.160	Node entry run in an out-of-process plugin worker. Requires the trusted-worker execution profile, and is required by it, by contributes.events and by any command without an action. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "dist/main.mjs"
contributes	object	no	1.4.160	What the plugin adds to Orca. Every point defaults to empty.
contributes.panels	PanelContribution[]	no	1.4.160	Sidebar panels. At most 64.
contributes.commands	CommandContribution[]	no	1.4.160	Command palette entries. At most 256.
contributes.events	EventContribution[]	no	1.4.160	Events delivered to the plugin worker. At most 3.
contributes.languagePacks	LanguagePackContribution[]	no	1.4.160	Interface translations. At most 16.
contributes.keybindings	KeybindingContribution[]	no	1.4.160	Keyboard shortcuts for contributed commands. At most 256.
contributes.vmRecipes	VmRecipeContribution[]	no	1.4.160	Virtual machine environment recipes. At most 64.
contributes.themes	ThemeContribution[]	no	1.4.245	App color themes. At most 64.
contributes.terminalThemes	ThemeContribution[]	no	1.4.245	Terminal ANSI palettes. At most 64.
contributes.iconThemes	ThemeContribution[]	no	1.4.245	File icon themes. At most 32.
contributes.syntaxes	SyntaxContribution[]	no	1.4.245	Syntax highlighting for editor languages. At most 16.
contributes.customEditors	CustomEditorContribution[]	no	1.4.245	Editors that open files of given types in the editor tab. At most 16.
contributes.newFiles	NewFileContribution[]	no	1.4.245	Untitled files the user can create from the + menu and the command palette. At most 16.
contributes.agentHarnesses	any[]	no	1.4.245	Reserved for coding-agent harness definitions; must be empty until their format is defined.
contributes.skills	any[]	no	1.4.245	Reserved for agent skills; must be empty until their format is defined.
contributes.mcpServers	any[]	no	1.4.245	Reserved for MCP server definitions; must be empty until their format is defined.
contributes.hooks	any[]	no	1.4.245	Reserved for agent hooks; must be empty until their format is defined.
contributes.taskSources	any[]	no	1.4.245	Reserved for task sources; must be empty until their format is defined.
contributes.connections	any[]	no	1.4.245	Reserved for account connections; must be empty until their format is defined.
contributes.settings	any[]	no	1.4.245	Reserved for plugin settings; must be empty until their format is defined.
contributes.statusBarItems	any[]	no	1.4.245	Reserved for status bar items; must be empty until their format is defined.
contributes.sidebarCards	any[]	no	1.4.245	Reserved for sidebar cards; must be empty until their format is defined.
capabilities	Capability[]	no	1.4.160	Host APIs the plugin asks the user to grant. At most 32.
cover	object	no	1.4.245	Wide image at the top of the plugin page.
cover.path	string	yes	1.4.245	Cover image shown on the plugin page, 16:10 recommended (1600×1000). PNG, JPEG, WEBP, static, at least 800×500, at most 1024 KB. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "images/cover.png"
cover.alt	string	yes	1.4.245	What the image shows, for screen readers. Required. Example: "The Dusk theme on a terminal"
screenshots	Screenshot[]	no	1.4.245	Screenshots for the plugin page, at most 6. All images together may be at most 8 MB.
pluginApi	1	no	1.4.160	Major version of the plugin host API this plugin targets. Optional (defaults to 1), and refused on data and declarative plugins, which never call it.

PanelContribution

A sidebar panel. Requires the sandboxed-ui execution profile or higher.

Field	Type	Required	Since	Description
id	string	yes	1.4.160	Panel id, unique among this plugin's panels. The reserved names constructor and prototype are refused. Example: "dashboard"
title	string	yes	1.4.160	Title shown on the panel tab and its tooltip. Example: "Dashboard"
icon	"activity" | "bar-chart-3" | "bell" | "blocks" | "book" | "bot" | "bug" | "calendar" | "cloud" | "code" | "database" | "file-text" | "flag" | "folder" | "gauge" | "globe" | "hammer" | "layers" | "lightbulb" | "package" | "plug" | "puzzle" | "rocket" | "star" | "terminal" | "wrench" | "zap"	no	1.4.160	Icon shown in the right-sidebar activity bar. Defaults to plug. Example: "database"
entry	string	yes	1.4.160	HTML file, relative to the plugin root, rendered inside a sandboxed panel frame. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "dist/panel.html"

CommandContribution

A command palette entry. Requires the declarative execution profile or higher.

Field	Type	Required	Since	Description
id	string	yes	1.4.160	Command id, unique among this plugin's commands. Dotted namespaces are allowed. Example: "jupyter.restartKernel"
title	string	yes	1.4.160	Title shown in the command palette. Example: "Restart kernel"
when	"global" | "workspace"	no	1.4.160	Where the command is available. workspace hides it when no workspace is active. Defaults to global.
action	"worktree.history.back" | "worktree.history.forward" | "sidebar.left.toggle" | "sidebar.sleepingWorkspaces.toggle" | "floatingWorkspace.maximize" | "tab.rename" | "workspace.rename" | "workspace.openBoard" | "view.tasks" | "sidebar.right.toggle" | "sidebar.explorer.toggle" | "sidebar.search.toggle" | "sidebar.sourceControl.toggle" | "sidebar.checks.toggle" | "sidebar.ports.toggle"	no	1.4.160	Built-in Orca action this command runs. A command with an action is declarative and never starts the plugin worker; one without needs main. Example: "view.tasks"

EventContribution

An event subscription. Requires main, the trusted-worker execution profile and the capability of the event's domain: workspace:read for workspace events, agent:read for agent events.

Field	Type	Required	Since	Description
on	"workspace.created" | "workspace.removed" | "agent.status.changed"	yes	1.4.160	Event delivered to the plugin worker.

LanguagePackContribution

An interface translation.

Field	Type	Required	Since	Description
locale	string	yes	1.4.160	BCP 47 locale the pack translates Orca into. Each locale appears once, ignoring case. Example: "pt-BR"
path	string	yes	1.4.160	JSON file of translated interface strings. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "locales/pt-BR.json"
displayName	string	no	1.4.245	Native-language name for the Settings picker. Omitted packs show {locale} — {pluginKey}. Example: "Português (Brasil)"

KeybindingContribution

A keyboard shortcut for a command.

Field	Type	Required	Since	Description
command	string	yes	1.4.160	Id of a command this plugin contributes in contributes.commands. Example: "jupyter.restartKernel"
key	string	yes	1.4.160	Key chord Orca recognizes, such as Mod+Shift+K. Mod is Cmd on macOS and Ctrl elsewhere. Each chord may be bound once on every platform. Example: "Mod+Shift+K"
when	"global" | "workspace"	no	1.4.160	Where the shortcut is active; must match its command's when.

VmRecipeContribution

A virtual machine environment recipe.

Field	Type	Required	Since	Description
path	string	yes	1.4.160	JSON environment recipe file, listed once. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "recipes/ubuntu.json"

ThemeContribution

A titled theme file.

Field	Type	Required	Since	Description
id	string	yes	1.4.245	Theme id, unique within its family in this plugin. The reserved names constructor and prototype are refused. Example: "dusk"
title	string	yes	1.4.245	Name shown in the theme picker. Example: "Dusk"
path	string	yes	1.4.245	JSON theme file, at most 16 KiB. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "themes/dusk.json"

SyntaxContribution

Syntax highlighting for one language.

Field	Type	Required	Since	Description
id	string	yes	1.4.245	Language id, unique among this plugin's syntaxes. The reserved names constructor and prototype are refused. Example: "gleam"
title	string	yes	1.4.245	Language name shown in the editor. Example: "Gleam"
scopeName	string	yes	1.4.245	The grammar's root TextMate scope, unique among this plugin's syntaxes. Example: "source.gleam"
path	string	yes	1.4.245	TextMate grammar JSON file. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "syntaxes/gleam.tmLanguage.json"
configuration	string	no	1.4.245	Language configuration JSON file: comments, brackets and auto-closing pairs. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "syntaxes/language-configuration.json"
extensions	string[]	no	1.4.245	File-name suffixes, with the dot, this language opens, ignoring case. A longer suffix such as .excalidraw.json wins over a shorter one, and a file named only the suffix never matches. At most 32. Example: [".gleam"]
filenames	string[]	no	1.4.245	Exact file names this language opens, ignoring case; a name beats any extension. Names must be portable: no path separators, ., .. or characters Windows forbids. At most 32. Example: ["gleam.toml"]

CustomEditorContribution

An editor for the listed files, shown in the editor tab beside Source. It must list at least one extension or file name. Requires the sandboxed-ui execution profile or higher.

Field	Type	Required	Since	Description
id	string	yes	1.4.245	Editor id, unique among this plugin's custom editors. The reserved names constructor and prototype are refused. Example: "excalidraw"
title	string	yes	1.4.245	Name shown in the editor's view toggle beside Source, and on the tab of a file it opens. Example: "Excalidraw"
icon	string	no	1.4.245	Square image shown on the tab of a file this editor opens. Defaults to the plugin icon. PNG, WEBP, static, at least 128×128, square, at most 256 KB. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "images/editor-icon.png"
extensions	string[]	no	1.4.245	File-name suffixes, with the dot, this editor opens, ignoring case. A longer suffix such as .excalidraw.json wins over a shorter one, and a file named only the suffix never matches. At most 32. Example: [".excalidraw",".excalidraw.json"]
filenames	string[]	no	1.4.245	Exact file names this editor opens, ignoring case; a name beats any extension. Names must be portable: no path separators, ., .. or characters Windows forbids. At most 32. Example: []
entry	string	yes	1.4.245	HTML file rendered inside a sandboxed editor frame, like a panel. It receives the open document and posts edits back; it never gets a file path or file system. It is trusted code: install editors you trust. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "editor/index.html"
priority	"default" | "option"	no	1.4.245	default (the default) opens matching files in this editor; option only offers it in the view toggle, so files open in Source. Files Orca opens itself (such as .json, .ts, .md, .csv, .yaml, lockfiles and .env files) always behave as option. Example: "default"
contentKind	"text" | "bytes"	no	1.4.245	text (the default) sends the file as text and accepts full-text edits. bytes sends the file's raw bytes, for binary formats such as spreadsheets, and accepts full-byte edits. Example: "bytes"

NewFileContribution

A kind of untitled file the user can create from the tab bar + menu or the command palette, in the active workspace.

Field	Type	Required	Since	Description
id	string	yes	1.4.245	New-file id, unique among this plugin's new files. The reserved names constructor and prototype are refused. Example: "drawing"
title	string	yes	1.4.245	Menu item shown in the tab bar + menu and the command palette. Example: "New Excalidraw drawing"
extension	string	yes	1.4.245	Suffix, with the dot, of the untitled file it creates. The file opens in whatever editor takes that suffix, such as a custom editor from this plugin. Example: ".excalidraw"
template	string	no	1.4.245	UTF-8 file copied into the new file, at most 256 KB. Without one the file starts empty. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "templates/empty.excalidraw"
icon	string	no	1.4.245	Square image shown beside the menu item. Defaults to the plugin icon. PNG, WEBP, static, at least 128×128, square, at most 256 KB. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "images/editor-icon.png"

Capability

A host API the plugin may call once the user consents.

Field	Type	Required	Since	Description
kind	"workspace:read" | "agent:read" | "terminal:send" | "notifications:show" | "storage:own" | "secrets:own" | "settings:own"	yes	1.4.160	Capability granted on user consent.

Screenshot

One screenshot of the plugin in use.

Field	Type	Required	Since	Description
path	string	yes	1.4.245	Screenshot, 16:10 recommended (up to 2560×1600). PNG, JPEG, WEBP, static, at least 1280×800, at most 1536 KB. Relative to the plugin root; .. segments and Windows device names such as CON are refused. Example: "images/editor.png"
alt	string	yes	1.4.245	What the image shows, for screen readers. Required. Example: "The Dusk theme on a terminal"
caption	string	no	1.4.245	Short caption under the screenshot. Example: "Gleam in the editor"
theme	"light" | "dark"	no	1.4.245	Show this screenshot only with a light or dark Orca theme.

Versions and compatibility

• What runs is strict. Orca refuses a manifest with any key it does not know, at every level, so an older Orca never silently ignores something a plugin relies on.
• engines.orca is the only version gate. It must be at least the newest Since of every field and every value (capability, event, built-in action) the manifest uses. pnpm validate:plugin and catalog CI enforce it, so an older Orca can always say "requires Orca >=X (this is Y)" instead of listing unknown fields.
• pluginApi is optional. It names the major version of the host API (reference), which only grows within major 1; Orca refuses a major it does not implement. Only sandboxed-ui and trusted-worker plugins call that API, so data and declarative plugins must leave it out.
• terminal:send needs trusted-worker. Panels get no host method that types into a terminal, so Orca refuses the capability on any other profile instead of asking the user to grant something the plugin can never use.
• New fields, contribution points and values are additive. They arrive with a Since version; nothing else changes. manifestVersion rises only if an existing field changes meaning.
• Deprecation. A field to be removed is marked deprecated here and keeps working for at least one release; it is removed only together with a higher engines.orca requirement, and its name is never reused.
• Reserved contribution points. contributes.agentHarnesses, skills, mcpServers, hooks, taskSources, connections, settings, statusBarItems and sidebarCards are held for planned features and must stay empty until their format is defined. Each will arrive as an additive point with its own Since, without a new manifest format. skills, mcpServers and hooks keep the meaning agent-plugin formats such as Claude Code's give them; agents stays unclaimed because those formats use it for subagent files.

Planned contribution points

Each reserved point is planned as declared data that Orca renders and enforces, never arbitrary plugin UI. The intended shapes, which may still change:

• taskSources: Issue and task providers such as Asana, Linear or Jira, declared as data that a worker fills with tasks.
• connections: Account providers with a host-run sign-in, so a plugin never handles credentials itself.
• agentHarnesses: New coding-agent harnesses described as data: how to launch them and read their status.
• statusBarItems: Declarative status bar widgets (label, icon, tooltip) whose values a worker updates.
• sidebarCards: Declarative left-sidebar cards with fixed layouts whose values a worker updates.
• mcpServers: MCP server definitions that Orca offers to the agents it launches.
• skills: Agent skills shipped as files that Orca installs for the agents it launches.
• hooks: Agent lifecycle hooks, such as before and after a tool call, for the agents Orca launches.
• settings: Typed plugin settings that Orca renders in its own settings UI.

Legacy format 1

Orca still loads "manifestVersion": 1 manifests (read since 1.4.160), but new plugins should use format 2. Format 1 differs in three ways:

• It has no execution field. Orca derives the least profile that can run what the manifest declares.
• Unknown top-level keys are ignored instead of rejected.
• The published JSON Schema does not describe it, so editors offer no completion for it.