Files

Teknium 97990e7ad5 feat: first-class plugin architecture (#1555 )

Plugin system for extending Hermes with custom tools, hooks, and
integrations — no source code changes required.

Core system (hermes_cli/plugins.py):
  - Plugin discovery from ~/.hermes/plugins/, .hermes/plugins/, and
    pip entry_points (hermes_agent.plugins group)
  - PluginContext with register_tool() and register_hook()
  - 6 lifecycle hooks: pre/post tool_call, pre/post llm_call,
    on_session_start/end
  - Namespace package handling for relative imports in plugins
  - Graceful error isolation — broken plugins never crash the agent

Integration (model_tools.py):
  - Plugin discovery runs after built-in + MCP tools
  - Plugin tools bypass toolset filter via get_plugin_tool_names()
  - Pre/post tool call hooks fire in handle_function_call()

CLI:
  - /plugins command shows loaded plugins, tool counts, status
  - Added to COMMANDS dict for autocomplete

Docs:
  - Getting started guide (build-a-hermes-plugin.md) — full tutorial
    building a calculator plugin step by step
  - Reference page (features/plugins.md) — quick overview + tables
  - Covers: file structure, schemas, handlers, hooks, data files,
    bundled skills, env var gating, pip distribution, common mistakes

Tests: 16 tests covering discovery, loading, hooks, tool visibility.

2026-03-16 07:17:36 -07:00

2.1 KiB

Raw Blame History

sidebar_position

sidebar_position
20

Plugins

Hermes has a plugin system for adding custom tools, hooks, and integrations without modifying core code.

→ Build a Hermes Plugin — step-by-step guide with a complete working example.

Quick overview

Drop a directory into ~/.hermes/plugins/ with a plugin.yaml and Python code:

~/.hermes/plugins/my-plugin/
├── plugin.yaml      # manifest
├── __init__.py      # register() — wires schemas to handlers
├── schemas.py       # tool schemas (what the LLM sees)
└── tools.py         # tool handlers (what runs when called)

Start Hermes — your tools appear alongside built-in tools. The model can call them immediately.

What plugins can do

Capability	How
Add tools	`ctx.register_tool(name, schema, handler)`
Add hooks	`ctx.register_hook("post_tool_call", callback)`
Ship data files	`Path(__file__).parent / "data" / "file.yaml"`
Bundle skills	Copy `skill.md` to `~/.hermes/skills/` at load time
Gate on env vars	`requires_env: [API_KEY]` in plugin.yaml
Distribute via pip	`[project.entry-points."hermes_agent.plugins"]`

Plugin discovery

Source	Path	Use case
User	`~/.hermes/plugins/`	Personal plugins
Project	`.hermes/plugins/`	Project-specific plugins
pip	`hermes_agent.plugins` entry_points	Distributed packages

Available hooks

Hook	Fires when
`pre_tool_call`	Before any tool executes
`post_tool_call`	After any tool returns
`pre_llm_call`	Before LLM API request
`post_llm_call`	After LLM API response
`on_session_start`	Session begins
`on_session_end`	Session ends

Managing plugins

/plugins              # list loaded plugins in a session
hermes config set display.show_cost true  # show cost in status bar

See the full guide for handler contracts, schema format, hook behavior, error handling, and common mistakes.

2.1 KiB Raw Blame History