--- name: create-update-hermes-plugin description: > Create, update, scaffold, or validate plugins for Hermes Agent (NousResearch/hermes-agent) — general plugins (tools, lifecycle hooks, slash commands, `hermes ` CLI subcommands, bundled skills, message injection) and specialized plugins (model provider, memory provider, context engine, gateway platform, image-gen, video-gen). Covers `plugin.yaml` manifests, the `register(ctx)` wiring contract, handler rules, discovery/opt-in semantics, and validation with `hermes plugins`, `HERMES_PLUGINS_DEBUG=1`, and `hermes doctor`. Use when building a Hermes plugin end-to-end, adding a tool or hook, injecting turn context, adding slash/CLI commands, building a provider backend, or debugging why a plugin is not discovered or not enabled. license: MIT compatibility: claude-code, codex, chatgpt, hermes, opencode, copilot, antigravity allowed-tools: bash, read, write, edit metadata: audience: developers workflow: plugin-development --- # Hermes Agent plugin development ## 1. Pick the extension surface first | You want to add… | Build | |---|---| | Tool, lifecycle hook, `/slash` command, `hermes ` subcommand, bundled skill, message injection | **General plugin** — `plugin.yaml` + `register(ctx)` (this skill) | | A built-in tool shipped in the repo (`tools/`, `toolsets.py`) | Repo patch — `references/builtin-tools-and-runtime.md` | | A reusable procedure (instructions + shell + existing tools) | **Skill**, not a plugin | | Inference backend (OpenAI-compatible, Codex, Anthropic-Messages, Bedrock) | `plugins/model-providers//` + `register_provider(ProviderProfile(...))` | | Gateway channel (Discord, Telegram, IRC, Teams…) | `plugins/platforms//` + `ctx.register_platform(...)` | | Memory backend (Honcho, Mem0, Supermemory…) | `plugins/memory//` — subclass `MemoryProvider` | | Context-compression strategy | `plugins/context_engine//` — subclass `ContextEngine` | | Image / video generation backend | `plugins/image_gen//` or `plugins/video_gen//` — `kind: backend` | | External tools | MCP server under `mcp_servers:` in `config.yaml` | | Gateway lifecycle reactions, no Python | `~/.hermes/hooks//` (`HOOK.yaml` + `handler.py`) | | Shell command on an agent event | Shell hooks under `hooks:` in `config.yaml` | | TTS/STT backend | Config-driven templates (`tts.providers`, `HERMES_LOCAL_STT_COMMAND`) | ## 2. Anatomy and discovery ``` ~/.hermes/plugins/my-plugin/ ├── plugin.yaml # manifest — declares what the plugin is ├── __init__.py # REQUIRED: def register(ctx) ├── schemas.py # tool schemas the LLM reads ├── tools.py # tool handlers that run ├── data/ # optional shipped read-only assets ├── skills/ # optional bundled skills (one dir per SKILL.md) └── cli.py # optional register_cli(subparser) (memory providers) ``` - Flat `~/.hermes/plugins//` or **one** category level (`platforms/`, `image_gen/`, `video_gen/`, `memory/`, `context_engine/`, `model-providers/`). Deeper trees are ignored. - Both `plugin.yaml` and `__init__.py` with `register(ctx)` are required. - Sources, later wins on name collision: bundled `/plugins/` → user `~/.hermes/plugins/` → project `./.hermes/plugins/` (needs `HERMES_ENABLE_PROJECT_PLUGINS=true`) → pip entry points → Nix. - **Opt-in:** discovery lists plugins, but nothing loads until the name is in `plugins.enabled` (`hermes plugins enable `). Exceptions: bundled platform/backend plugins and memory/context/model providers, which are selected through `config.yaml`. ## 3. Minimal manifest ```yaml name: calculator version: 1.0.0 description: Math calculator — evaluate expressions and convert units author: Your Name provides_tools: [calculate, unit_convert] provides_hooks: [post_tool_call] requires_env: - WEATHER_API_KEY # simple — disabled if missing - name: OTHER_KEY # rich — prompted at install description: "Key for the Other service" url: "https://other.com/keys" secret: true ``` Also documented: `optional_env`, `hooks:` (memory providers), `kind:` (`standalone`, `backend`, `platform`, `model-provider`), `label:`. Do **not** invent `manifest_version`, `api_version`, `capabilities`, or `python_dependencies` — they are not part of the manifest. ## 4. The four handler rules 1. **Signature** `def handler(args: dict, **kwargs) -> str` 2. **Return a JSON string** — `json.dumps(...)`, never a dict or primitive 3. **Never raise** — catch everything, return `json.dumps({"error": str(exc)})` 4. **Accept `**kwargs`** — forward compatibility for runtime context ```python from . import schemas, tools def register(ctx): ctx.register_tool(name="calculate", toolset="calculator", schema=schemas.CALCULATE, handler=tools.calculate) ctx.register_hook("post_tool_call", _log_tool_call) ``` `register()` runs once at startup. If it raises, the plugin is disabled and Hermes continues — so keep it fast and side-effect free (no network, no I/O). ## 5. `ctx` surface (documented) | Call | Purpose | |---|---| | `ctx.register_tool(name, toolset, schema, handler, check_fn=?, override=?)` | Tool the agent can call | | `ctx.register_hook(event, callback)` | Lifecycle subscription | | `ctx.register_command(name, handler, description="")` | `/name` in CLI and gateway | | `ctx.register_cli_command(name, help, setup_fn, handler_fn)` | `hermes ` | | `ctx.dispatch_tool(name, args, *, parent_agent=None)` | Invoke a tool with parent-agent context | | `ctx.register_skill(name, path)` | Bundle a read-only skill (`plugin:skill`) | | `ctx.inject_message(content, role="user")` | Queue/interrupt the conversation (CLI) | | `ctx.llm.complete(...)` / `complete_structured(...)` | One-shot host-owned LLM call | | `ctx.register_platform(...)`, `register_image_gen_provider(...)`, `register_video_gen_provider(...)`, `register_context_engine(...)`, `register_memory_provider(...)` | Specialized surfaces | ## 6. Workflow 1. **Choose the surface** (§1) and the category directory. 2. **Scaffold or hand-write**: ```bash node scripts/scaffold_plugin.ts ~/.hermes/plugins/myplugin \ --name myplugin --tools tool_a,tool_b --hooks post_tool_call,pre_llm_call ``` 3. **Schemas** — say *when* to call the tool; tight JSON Schema with `required`. 4. **Handlers** — four rules; resolve paths from `HERMES_HOME`, never `~/.hermes`. 5. **Wire `register(ctx)`** — register exactly what the manifest declares. 6. **Enable and inspect**: ```bash hermes plugins enable myplugin && hermes plugins list # /plugins in-session ``` 7. **Debug if missing**: `HERMES_PLUGINS_DEBUG=1 hermes plugins list` (or `hermes logs --level WARNING | grep -i plugin`). Check opt-in state, layout depth, missing `__init__.py`, wrong `kind`. 8. **Validate**: `node scripts/validate_plugin_structure.ts `, run `node scripts/validate_plugin_mcp.ts ` if the plugin documents MCP servers, then exercise the happy path with `hermes -z "use my_tool …"`. ### Scripts | Script | Purpose | |---|---| | `scripts/scaffold_plugin.ts` | Create `plugin.yaml`, `schemas.py`, `tools.py`, `__init__.py` | | `scripts/validate_plugin_structure.ts` | Manifest, `register(ctx)`, handler contract, declared vs registered tools/hooks, layout depth | | `scripts/validate_plugin_mcp.ts` | Hermes `mcp_servers` blocks (stdio/HTTP, timeouts, tools policy) | `scripts/scaffold_hermes_plugin.ts` remains as a deprecated alias for the scaffolder (its legacy `validate` subcommand still runs structure checks). ## 7. Critical patterns ### Context injection (`pre_llm_call`) The only hook that feeds text into the turn. Return `{"context": "..."}` (or a plain string); return `None` to stay observer-only. Text is added to the current turn's **user message**, not the system prompt, so provider prefix caching stays warm. ```python def recall(session_id, user_message, is_first_turn, **kwargs): memories = search(user_message) return {"context": "\n".join(memories)} if memories else None def register(ctx): ctx.register_hook("pre_llm_call", recall) ``` ### Slash command vs CLI subcommand `ctx.register_command` → `/name` in chats; handler gets the raw argument string and may be `async`. `ctx.register_cli_command` → `hermes name …`; handler gets an argparse `Namespace`. Built-in command names cannot be overridden. ### Calling tools from a command `ctx.dispatch_tool("terminal", {...})` runs the real approval, redaction, and budget pipeline. Never reach into private CLI state. ### Gating and overrides `check_fn=lambda: ...` hides a tool when a dependency is absent. `override=True` replaces a built-in tool name; without it the shadowing registration is rejected. Declare secrets in `requires_env` and read them via `os.environ`. ## 8. References - `references/manifest-and-structure.md` — manifest fields, discovery order, opt-in states, category layouts, bundled skills, distribution, profile paths. - `references/tools-and-schemas.md` — schemas, handler contract, toolsets, conditional tools, overrides, data/skills, `dispatch_tool`, `inject_message`, `ctx.llm`. - `references/hooks-and-commands.md` — hook signatures/return contracts, slash and CLI commands, async handlers, injection mechanics. - `references/model-providers.md` — plugin vs core path, profile fields/hooks, `api_mode`, auth, runtime precedence, aux/fallback, testing. - `references/platform-adapters.md` — `BasePlatformAdapter` contract, `register_platform` options, env enablement, YAML bridge, cron delivery, auth. - `references/context-engines.md` — ABC contract, engine tools, lifecycle, built-in compressor thresholds/algorithm. - `references/specialized-plugins.md` — memory, image, video, `ctx.llm`, non-Python surfaces. - `references/builtin-tools-and-runtime.md` — core tool path, registry, `check_fn`, dispatch/error wrapping, toolsets, import map. - `references/testing-and-debugging.md` — temp-`HERMES_HOME` harness, discovery debugging, logs, pitfalls, upgrade notes. - `references/upstream-coverage.md` — page-by-page map to upstream `developer-guide/`, verified discrepancies, re-audit procedure. - `references/docs/` — the raw upstream pages behind these digests (23 files, each with a `` header); load one when a digest and upstream disagree, then re-audit with `upstream-coverage.md`. ## 9. Validation checklist - [ ] Flat or exactly one category level under a plugin root. - [ ] `plugin.yaml` parses; `name` and `version` present. - [ ] `provides_tools` / `provides_hooks` match `register(ctx)`. - [ ] `register(ctx)` performs no network or heavy I/O. - [ ] Every handler is `(args: dict, **kwargs)` and returns `json.dumps(...)`. - [ ] Every handler catches exceptions and returns `{"error": ...}`. - [ ] Hook callbacks accept `**kwargs`; only `pre_llm_call`, `pre_tool_call`, `pre_gateway_dispatch`, `transform_*` use returns. - [ ] Secrets live in `requires_env`; paths derive from `HERMES_HOME`. - [ ] Plugin is enabled and clean under `HERMES_PLUGINS_DEBUG=1`.