hermes-plugin-development

Hermes Plugin Development

Use when: creating, debugging, or integrating Hermes Agent plugins, including Python backend plugins (tools, hooks, routers, middleware) and JavaScript Hermes Desktop runtime plugins.

Core patterns

• Choose the extension surface first:
• Backend plugins live under ~/.hermes/plugins/<name>/ and add tools, hooks, commands, providers, or middleware.
• Desktop runtime plugins live under $HERMES_HOME/desktop-plugins/<name>/plugin.js and add native UI contributions through @hermes/plugin-sdk. For model-picker specifics, including a Desktop-local /switch command plus backend command-inventory bridge, use references/desktop-model-picker-plugin.md.
• Resolve the requested interaction surface before building anything. “TUI,” “terminal,” “over SSH,” or “from Windows over SSH” means the prompt_toolkit CLI, not Hermes Desktop. Never substitute a Desktop popover or a backend text-response command.
• Backend plugin slash handlers return text; they cannot open a prompt_toolkit modal. For a TUI command that opens an existing picker, prefer a central command alias or an update-safe quick_commands alias. If the user requires an explicit Session/Global step, aliasing to bare /model is insufficient because the standard picker follows its persistence default; extend the TUI picker state with a scope stage and verify that scope reaches the final switch call. For live verification, use a fresh CLI under tmux, synchronize on the visible composer, capture each modal stage, then repeat through the user's real SSH path; do not mistake raw PTY repaint fragments for a product failure. See references/tui-model-picker-slash-command.md.
• Desktop-only slash-like UI commands may use a two-surface integration: composer middleware opens/cancels locally, while an enabled Python backend plugin registers inventory/autocomplete and a non-Desktop fallback. Middleware receives a { text, attachments } draft object—never test it with raw strings. This pattern does not satisfy TUI/SSH requests.
• Backend plugins use:
• __init__.py: Python code + hook implementations
• plugin.yaml: metadata + hook declarations
• Optional config.yaml: per-profile settings (e.g., router_model, floor_toolsets)