Plugins

Plugins add capabilities to omp as one managed unit. A plugin may contain extension code, skills, slash commands, hooks, custom tools, agents, rules, prompts, or MCP/LSP/DAP configuration. Use one when you want to install and manage a collection of related behavior together.

Start by seeing what is already installed. Before adding anything, inspect its publisher and source:

omp plugin list
omp plugin install --dry-run '@scope/[email protected]'
omp plugin install '@scope/[email protected]'
omp plugin list

--dry-run previews npm, Git, and local-path installs without installing the target. It does not apply to marketplace installs; evaluate those at project scope instead. A successful install prints the resolved name and version. Start a new omp session to load all of the plugin's behavior, or follow Reload an active session.

Plugins are trusted code, not a sandbox. Project scope limits where a marketplace plugin is discovered; it does not limit what that plugin can read, write, execute, or send over the network.

Choose an install sourceCopy Anchor Link

omp plugin install accepts these source forms:

Git shorthands also support gitlab:, bitbucket:, codeberg:, sourcehut:, and srht:. Full HTTPS, SSH, git://, and git+… URLs are accepted. Quote sources containing #, [ or ] so your shell does not interpret them.

The shorter omp install <source> command is a convenience wrapper around omp plugin install and omp plugin link. The omp plugin … form is used throughout this page because it exposes the complete management surface.

For a local plugin under development, these are equivalent:

omp plugin install ./my-plugin
omp plugin link ./my-plugin

Source edits remain visible through the symlink, but an already running omp session still needs a reload or restart before every changed capability is active.

Install from a marketplaceCopy Anchor Link

A marketplace is a catalog of plugins, not a plugin itself. Add a catalog, inspect its entries, then install an entry by its full name@marketplace ID:

omp plugin marketplace add anthropics/claude-plugins-official
omp plugin marketplace list
omp plugin discover claude-plugins-official
omp plugin install --scope project plugin-name@claude-plugins-official
omp plugin list

Supported catalog sources include:

• GitHub shorthand such as owner/repo
• HTTP(S), SSH, or Git repository URLs
• a direct HTTP(S) URL ending in .json
• local directories such as ./catalog, ~/catalog, or /absolute/catalog

Git and local catalogs use .omp-plugin/marketplace.json, falling back to the Claude Code-compatible .claude-plugin/marketplace.json. See Marketplaces for catalog browsing, source formats, and publishing.

User and project scopeCopy Anchor Link

Scope applies only to marketplace installs:

• --scope user is the default and makes the plugin available across projects.
• --scope project records it in the nearest project .omp/plugins/installed_plugins.json and makes it available in that project.
• npm, Git, and linked local plugins use the user plugin directory; passing --scope for them is ignored with a warning.

An enabled project install shadows an enabled user install with the same name@marketplace ID. A disabled project install does not hide the enabled user install. If the same plugin is installed in both scopes, pass --scope user or --scope project when upgrading, disabling, enabling, or uninstalling that copy.

Project scope is useful for keeping a project's dependency set separate. It is not a security boundary: the plugin still runs with the same OS permissions as omp.

Inspect, disable, and enableCopy Anchor Link

List before changing state so you use the installed package name or full marketplace ID:

omp plugin list
omp plugin list --json

The human-readable list separates npm/link plugins from marketplace plugins. It shows versions, enabled state and optional features for npm/link plugins; marketplace rows include scope and whether a project copy shadows a user copy. Inside a session, /plugins or /plugins list provides a shorter view.

Disable a plugin when you want to stop loading it without deleting its files or settings:

# npm, Git, or linked plugin; state is user-wide
omp plugin disable @scope/plugin
omp plugin enable @scope/plugin

# marketplace plugin
omp plugin disable --scope project plugin-name@marketplace-name
omp plugin enable --scope project plugin-name@marketplace-name

Inside an interactive session, /plugins disable and /plugins enable manage marketplace plugins:

/plugins disable --scope project plugin-name@marketplace-name
/plugins enable --scope project plugin-name@marketplace-name

Run /reload-plugins afterward, or restart omp. Disabling reduces future loading; it cannot undo actions code already performed in the current process.

Some npm/link plugins declare optional features. Inspect and change those independently of the whole-plugin enabled state:

omp plugin features @scope/plugin
omp plugin features @scope/plugin --enable search,web
omp plugin features @scope/plugin --disable web
omp plugin features @scope/plugin --set search

At install time, quote the feature selector:

omp plugin install '@scope/plugin[search,web]'
omp plugin install '@scope/plugin[*]'
omp plugin install '@scope/plugin[]'

No brackets uses the plugin's defaults; [*] enables every declared feature and [] enables none of the optional features.

Update pluginsCopy Anchor Link

Update behavior depends on the source.

Marketplace pluginsCopy Anchor Link

Refreshing a marketplace updates only its catalog. Upgrade is the separate step that replaces installed plugin code:

omp plugin marketplace update marketplace-name
omp plugin upgrade --scope project plugin-name@marketplace-name

Omit the marketplace name to refresh all catalogs. Omit the plugin ID from omp plugin upgrade to upgrade all installed marketplace plugins:

omp plugin marketplace update
omp plugin upgrade

When one marketplace plugin exists in both scopes, omitting --scope upgrades both copies. Bulk upgrade may partially succeed if one entry fails, so read every result and run omp plugin list afterward.

npm and Git pluginsCopy Anchor Link

There is no generic omp plugin update command for npm or Git installs. Reinstall the version or ref you intend to run:

omp plugin install '@scope/[email protected]'
omp plugin install 'github:org/repo#v1.5.0'

For a linked local plugin, update its source directory yourself; the symlink does not need reinstalling. Pin npm versions and Git tags or commits when reproducibility matters.

Remove a pluginCopy Anchor Link

Preview removal, then uninstall by the name shown in omp plugin list:

omp plugin uninstall --dry-run @scope/plugin
omp plugin uninstall @scope/plugin

For a marketplace plugin, use its full ID and specify the copy when necessary:

omp plugin uninstall --dry-run --scope project plugin-name@marketplace-name
omp plugin uninstall --scope project plugin-name@marketplace-name

Uninstalling removes that plugin registration and installed files for the selected scope. Removing a marketplace catalog is different: it removes the catalog and its cache but does not uninstall plugins already installed from it.

omp plugin marketplace remove marketplace-name

Restart omp after removing executable plugin behavior, or reload the active session as described below.

Reload an active sessionCopy Anchor Link

Shell commands change plugin state on disk; they do not rebuild an omp process that is already running. Interactive marketplace changes also require an explicit refresh.

Run:

/reload-plugins

This refreshes plugin discovery, skills, slash commands, agent definitions, capability caches, and MCP connections in the active session. Restart omp for newly installed or changed extension modules, hooks, or executable custom tools, because those initialized runtime components are not fully rebuilt in place. When in doubt, restart.

Check health and settingsCopy Anchor Link

If a plugin is installed but missing from omp plugin list, fails to load, or points at a deleted local path, run the non-mutating health check first:

omp plugin doctor

After reading its findings, omp plugin doctor --fix can attempt repairs. Use --json when another program needs to consume the result.

Plugins may declare typed settings. Inspect the declared keys before setting one:

omp plugin config list @scope/plugin
omp plugin config get @scope/plugin apiKey
omp plugin config set @scope/plugin apiKey value
omp plugin config delete @scope/plugin apiKey
omp plugin config validate

Add -l or --local to config list, get, set, or delete to use the current project's setting overrides. A manifest marking a setting as secret masks its display; it does not turn an untrusted plugin into trusted code.

Trust checklistCopy Anchor Link

Plugins, extensions, and marketplacesCopy Anchor Link

A plugin does not have to contain an extension module; it may contain only declarative surfaces such as skills or MCP configuration. Conversely, you can load an extension directly without installing it as a managed plugin. See Authoring extensions for that runtime API.

Command referenceCopy Anchor Link

Use --scope user|project only with marketplace install, enable, disable, upgrade, and uninstall operations. /marketplace help shows the equivalent in-session marketplace commands.

For plugin authorsCopy Anchor Link

{
  "name": "@acme/omp-review",
  "version": "1.0.0",
  "omp": {
    "extensions": ["./src/index.ts"]
  }
}