[PRD] OpenHands CLI Plugin Support

[jpshackelford]

Problem Statement

Background

The OpenHands SDK now has basic plugin support (as of commits 89cfc32 and 0fc053a), enabling conversations to be started with plugins that bundle skills, hooks, MCP configurations, and commands. However, there is currently no way for CLI users to:

1. Discover and install plugins from marketplaces
2. Manage registered marketplaces for plugin discovery
3. Invoke plugin commands using slash command syntax
4. Share plugin configurations across teams via project settings

The parent PRD (OpenHands Plugins #12085) establishes the vision for a plugin ecosystem. This PRD focuses specifically on CLI support for that ecosystem.

Pain Points

• No marketplace registration: Users must provide full plugin source URLs every time they want to use a plugin
• No persistent plugin configuration: Plugin preferences are not saved between sessions
• No command invocation: Plugin commands cannot be invoked via slash command syntax in the CLI
• No team sharing: No mechanism to define recommended plugins at the project level

Desired Future State

• CLI users can register marketplaces and install plugins with simple commands
• Plugin commands are invocable via /plugin-name:command syntax
• Project-level plugin configurations enable team-wide plugin sharing
• Feature parity with Claude Code's plugin system where appropriate

Goals

In Scope

• CLI commands for marketplace management (oh plugin marketplace add/list/remove/update)
• CLI commands for plugin management (oh plugin install/uninstall/enable/disable)
• Plugin command invocation via slash commands
• User-scope plugin/marketplace storage
• Project-scope plugin configuration (.openhands/settings.json)
• Integration with existing SDK plugin loading infrastructure

Out of Scope

• GUI/TUI for plugin management (future enhancement)
• Plugin development tooling (oh plugin create, scaffolding)
• Plugin security scanning/verification (enterprise feature)
• Public OpenHands plugin marketplace (covered by #12085)

Personas

• CLI Power Users: Developers who prefer terminal-based workflows and want to extend OpenHands with plugins
• Team Leads: Engineers who want to standardize plugin usage across their team via project configuration
• Plugin Consumers: Users who want to discover and use pre-built plugins without understanding the underlying infrastructure

Architecture Decision

SDK vs CLI Responsibility

The SDK is intentionally stateless at the user/global level:

SDK Provides	CLI Provides
Marketplace.load(path) - parse marketplace manifests	Marketplace registration storage
PluginSource model for specifying plugins	oh plugin marketplace add/list/remove commands
Plugin fetch, load, merge utilities	Resolution of marketplace:plugin → PluginSource
Per-conversation plugin state	User preferences (~/.openhands/)

This keeps the SDK portable across CLI, Cloud, and embedded use cases.

Storage Locations

Scope	Location	Purpose
User	~/.openhands/marketplaces.json	Registered marketplaces
User	~/.openhands/plugins.json	Installed/enabled plugins
Project	.openhands/settings.json	Team plugin configuration
Local	.openhands/settings.local.json	Personal overrides (not committed)

Use Cases

UC1: Register a Marketplace

oh plugin marketplace add company/internal-plugins
oh plugin marketplace add https://gitlab.com/team/plugins.git
oh plugin marketplace list

UC2: Install and Use a Plugin

oh plugin install code-formatter@company-plugins
oh run
> /code-formatter:format src/

UC3: Team Plugin Configuration

// .openhands/settings.json
{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": { "source": "github", "repo": "myorg/oh-plugins" }
    }
  },
  "enabledPlugins": {
    "linter@team-tools": true
  }
}

UC4: Development/Testing

oh run --plugin ./my-local-plugin

Sub-Issues

• M1: Plugin Loading & Command Invocation - [M1] Plugin Loading and Command Invocation #409
• M2: Marketplace Management - [M2] Marketplace Management #411
• M2: Plugin Management - [M2] Plugin Management #413

Future Work (M3/M4)

The following milestones are planned for future phases:

• M3: Project Scope Configuration - .openhands/settings.json support for team-wide plugin sharing
• M3: Auto-Update Support - Automatic marketplace and plugin updates with version pinning
• M4: Enterprise Managed Restrictions - Allowlist controls via strictKnownMarketplaces for compliance

Sequencing

M1: Plugin Loading & Invocation
    ↓
M2: Marketplace & Plugin Management (parallel work)
    ↓
M3: Project Scope & Auto-Update
    ↓
M4: Enterprise Features

M1 delivers immediate value: users can load and use plugins from explicit sources without any marketplace infrastructure.

M2 adds convenience: users can register marketplaces and install plugins persistently.

M3 enables teams: project-level configuration and auto-updates for consistent team tooling.

M4 supports enterprise: managed restrictions for compliance and security requirements.

References

• Full PRD Details (Gist)
• OpenHands Plugins PRD #12085
• SDK Plugin Support #1651
• Claude Code Plugin Documentation
• Claude Code Marketplace Documentation

[jpelletier1]

@jpshackelford Small thing - might be worth clarifying that oh is short for the existing openhands CLI :-)

Otherwise I think this is a good ticket since it covers CLI commands, and TUI-based slash commands for plugins.

[enyst]

Status update: SDK PR OpenHands/software-agent-sdk#2031 adds installed plugin management utilities (install/uninstall/list/get/load/update) for Claude-style plugins under ~/.openhands/plugins/installed/ with .installed.json metadata. This gives the CLI a backend for /plugin install/list/uninstall.

There is still no enable/disable state in the SDK; enablement remains a CLI-owned config that must be passed into Conversation/AgentContext. Marketplace resolution/search remains CLI-side. AgentSkills management gap tracked in OpenHands/software-agent-sdk#2301.