Wiki · Features in depth
Plugins
A plugin is third-party code inside the agent — which is why it never starts by itself. What it can do, how to allow it and how it differs from an MCP server.
What a plugin is
An ordinary folder in ~/.hermes/plugins/ with a manifest and some Python:
After startup the plugin's tools appear next to the built-in ones and the model can call them right
away. The smallest working plugin is two files — plugin.yaml and __init__.py
with a register(ctx) function.
What a plugin can do
| Capability | Example use |
|---|---|
| Add tools | Your company's API as a tool the model can call |
| Hook into events | Log every tool call, warn before a command runs |
| Add slash commands | /my-command in chat and in the gateway |
| Add CLI commands | hermes my-plugin something |
| Bundle skills | The plugin ships its own skills as plugin:skill |
| Add a messaging platform | A new chat network beside Telegram and Discord |
| Image, video, terminal or memory backend | A different image model or memory store |
| Approval transport | Dangerous-step confirmations delivered somewhere other than chat |
Permission: nothing runs on its own
A plugin shows up in the listing once it is on disk, but its tools and hooks do not load until you
add its name to plugins.enabled in config.yaml:
Watch the exception: gateway hooks in ~/.hermes/hooks/<name>/
are not plugins and are not gated by the allow-list — they run simply by being placed there. Whoever
puts files there gets them executed on every start.
Catalog: install by name
Human-reviewed plugins live in a catalog. Installing by name checks out exactly the commit someone reviewed (a pinned SHA), not a branch tip:
| Catalog field | What it means |
|---|---|
tier | official (maintained by NousResearch) or community |
sha | The exact 40-hex commit that was reviewed |
capabilities | Which tools, hooks and environment variables it declares |
requires_hermes | Minimum Hermes version the plugin needs |
Bundled plugins that ship with Hermes (for example disk-cleanup, security-guidance, google_meet, hermes-achievements) are opt-in as well — enabled the same way as any other. The reason is simple: an update must not silently hand you tools you never asked for.
Timeouts worth knowing
| Setting | Default | Purpose |
|---|---|---|
clone_timeout_seconds | 300 s | How long a git fetch of a plugin may take |
load_timeout_seconds | 10 s | Load limit per plugin; slower ones are skipped with a reason |
hook_callback_timeout | 30 s | Limit for Python hooks; a timed-out pre-tool hook blocks the tool |
Plugin or MCP server?
| Plugin | MCP server | |
|---|---|---|
| Runs | Inside the agent process | A separate process the agent connects to |
| Can touch the agent | Yes — hooks, approvals, memory, platforms | No — it offers tools only |
| Best for | Changing agent behaviour, wiring internal parts | Third-party services and APIs with their own lifecycle |
| Risk | Higher — code shares the process | Lower — isolated process with its own rights |
Our rule of thumb: MCP for external services, a plugin for changing the agent. External tools (search, browser, docs) run as MCP servers because they can be restarted and limited separately.
Things to watch
| Situation | What to do |
|---|---|
A plugin goes quiet after hermes update | Check /plugins and the startup log — it may have hit load_timeout_seconds or a version change |
A project ships its own ./.hermes/plugins/ | Project plugins are off; enable them only for trusted repos with HERMES_ENABLE_PROJECT_PLUGINS=true |
| A plugin blocks something | A pre_tool_call hook can deny a tool — look in the plugin, not in permissions |
| You want to try a plugin safely | Create a new profile and enable it there; production stays untouched (see the profiles page) |