feat(cli): add --plugin flag for loading plugins

[timon0305]

Issue: #409

Summary

• Add -p/--plugin CLI flag for loading plugins from local paths or GitHub URLs
• Plugins provide skills, hooks, and MCP configurations merged into the agent
• Supports multiple plugins via repeated --plugin flags

Changes

• argparsers/main_parser.py - Add -p/--plugin argument
• locations.py - Add PLUGINS_CACHE_DIR constant
• setup.py - Add load_plugins(), merge_plugins_into_agent()
• tui/core/conversation_runner.py - Add plugin_sources parameter
• tui/textual_app.py - Thread plugin_sources through app
• entrypoint.py - Pass args.plugins to textual_main

Test plan

• uv run pytest - All 1144 tests pass
• Verified openhands --help shows -p/--plugin flag
• Manual test with local plugin (requires plugin fixture)

Test Results

uv run pytest
================= 1144 passed, 3 warnings in 109.46s (0:01:49) =================

CLI Help Output

$ openhands --help
usage: openhands [-h] [--version] [-t TASK] [-f FILE] [-p PATH_OR_URL] [--resume [RESUME]] [--last]
                 [--headless] [--json] [--always-approve | --llm-approve] [--exit-without-confirmation]
                 [--override-with-envs]
                 {acp,serve,web,mcp,cloud,login,logout,view} ...

OpenHands CLI - Terminal User Interface for OpenHands AI Agent

positional arguments:
  {acp,serve,web,mcp,cloud,login,logout,view}
                        Additional commands
    acp                 Start OpenHands as an Agent Client Protocol (ACP) agent (e.g., Toad CLI, Zed IDE)
    serve               Launch the OpenHands GUI server using Docker (web interface)
    web                 Launch the OpenHands CLI as a web application (browser interface)
    mcp                 Manage Model Context Protocol (MCP) server configurations
    cloud               Create a new conversation in OpenHands Cloud
    login               Authenticate with OpenHands Cloud using OAuth 2.0 Device Flow
    logout              Log out from OpenHands Cloud
    view                View the trajectory of an existing conversation

options:
  -h, --help            show this help message and exit
  --version, -v         Show the version number and exit
  -t TASK, --task TASK  Initial task text to seed the conversation with
  -f FILE, --file FILE  Path to a file whose contents will seed the initial conversation
  -p PATH_OR_URL, --plugin PATH_OR_URL
                        Load a plugin from a local path or GitHub URL. Can be specified multiple times to
                        load multiple plugins. Example: --plugin ./my-plugin or --plugin
                        github:owner/repo
  --resume [RESUME]     Conversation ID to resume. If no ID provided, shows list of recent conversations
  --last                Resume the most recent conversation (use with --resume)
  --headless            Run in headless mode (no UI output, auto-approve actions). Requires --task or
                        --file.
  --json                Enable JSON output mode for headless operation. Streams JSONL event outputs to
                        terminal. Must be used with --headless.
  --always-approve      Auto-approve all actions without asking for confirmation
  --llm-approve         Enable LLM-based security analyzer (only confirm LLM-predicted high-risk actions)
  --exit-without-confirmation
                        Exit the application without showing confirmation dialog
  --override-with-envs  Override LLM settings with environment variables (LLM_API_KEY, LLM_BASE_URL,
                        LLM_MODEL). By default, environment variables are ignored.

            By default, OpenHands runs in textual UI mode (terminal interface)
            with 'always-ask' confirmation mode, where all agent actions
            require user confirmation.

            Use 'serve' subcommand to launch the GUI server instead.

            Examples:
                openhands                           # Start textual UI mode
                openhands --headless                # Start textual UI in headless mode
                openhands --headless --json -t "Fix bug"  # Headless with JSON output
                openhands --resume conversation-id  # Resume conversation
                openhands --always-approve          # Auto-approve all actions
                openhands --llm-approve             # LLM-based approval mode
                openhands --plugin ./my-plugin      # Load a local plugin
                openhands --plugin github:org/repo  # Load plugin from GitHub
                openhands cloud -t "Fix bug"        # Create cloud conversation
                openhands serve                     # Launch GUI server
                openhands serve --gpu               # Launch with GPU support
                openhands web                       # Launch CLI as web app
                openhands web --port 8080           # Launch web app on custom port
                openhands acp                       # Agent-Client Protocol
                                                      server (e.g., Toad CLI, Zed IDE)
                openhands login                     # Authenticate with OpenHands Cloud
                openhands logout                    # Log out from OpenHands Cloud

[jpshackelford]

@timon0305 Thanks for the contribution!

[enyst]

Status update: SDK PR OpenHands/software-agent-sdk#2031 adds installed plugin management utilities (install/uninstall/list/get/load/update) under ~/.openhands/plugins/installed/ with .installed.json metadata. That provides the SDK backend for plugin install/list/uninstall flows here.

The SDK still has no enable/disable state; CLI should keep that state and pass enabled plugins into Conversation/AgentContext. AgentSkills management is tracked in OpenHands/software-agent-sdk#2301.