Hermes Agent Plugins: Custom Tools, Hooks and Integrations

Available hooks

Plugins can register callbacks for the following lifecycle events. The Event Hooks page provides complete details, callback signatures, and usage examples.

Plugin types​

Hermes defines four categories of plugins, each serving a distinct role:

Memory providers and context engines fall under the category of provider plugins — only one instance of each type may be active at any given time. Model providers are also considered plugins, but multiple can be loaded simultaneously; the user selects which one to use at runtime via the --provider flag or by setting it in config.yaml. General plugins, on the other hand, can be enabled in any combination without restriction.

Pluggable interfaces — where to go for each​

The preceding table outlines the four plugin categories, but within "General plugins" the PluginContext exposes several distinct extension points — and Hermes also accepts extensions outside the Python plugin system (config-driven backends, shell-hooked commands, external servers, etc.). Use this table to find the right doc for what you want to build:

Not every extension point requires writing a Python plugin. Several surfaces are intentionally designed around config-driven shell commands (TTS, STT, shell hooks) so that any existing CLI tool can serve as a plugin without needing Python code. Others rely on external servers (MCP) that the agent connects to and automatically registers tools from. And some use drop-in directories (gateway hooks) with their own manifest format. Choose the right surface for the integration style that fits your use case; the authoring guides in the table above each cover placeholders, discovery, and examples.

NixOS declarative plugins​

When running NixOS, you can install plugins declaratively through the module options, eliminating the need to run hermes plugins install. For complete instructions, refer to the Nix Setup guide.

services.hermes-agent = {
  # Directory plugin (source tree with plugin.yaml)
  extraPlugins = [ (pkgs.fetchFromGitHub { ... }) ];
  # Entry-point plugin (pip package)
  extraPythonPackages = [ (pkgs.python312Packages.buildPythonPackage { ... }) ];
  # Enable in config
  settings.plugins.enabled = [ "my-plugin" ];
};

Plugins installed declaratively are symlinked with a nix-managed- prefix, allowing them to coexist alongside any manually installed plugins. When you remove a plugin from your Nix configuration, its symlink is automatically cleaned up without any additional steps.

Managing plugins​

hermes plugins                               # unified interactive UI
hermes plugins list                          # table: enabled / disabled / not enabled
hermes plugins install user/repo             # install from Git, then prompt Enable? [y/N]
hermes plugins install user/repo --enable    # install AND enable (no prompt)
hermes plugins install user/repo --no-enable # install but leave disabled (no prompt)
hermes plugins update my-plugin              # pull latest
hermes plugins remove my-plugin              # uninstall
hermes plugins enable my-plugin              # add to allow-list
hermes plugins disable my-plugin             # remove from allow-list + add to disabled

Interactive UI​

When you run hermes plugins without any arguments, it launches a combined interactive screen:

Plugins
  ↑↓ navigate  SPACE toggle  ENTER configure/confirm  ESC done

  General Plugins
 → [✓] my-tool-plugin — Custom search tool
   [ ] webhook-notifier — Event hooks
   [ ] disk-cleanup — Auto-cleanup of ephemeral files [bundled]

  Provider Plugins
     Memory Provider          ▸ honcho
     Context Engine           ▸ compressor

• General Plugins section — displayed as checkboxes that you toggle using the SPACE key. A checked box means the plugin appears in plugins.enabled, while an unchecked box means it is placed in plugins.disabled (explicitly turned off).
• Provider Plugins section — shows the currently selected provider. Press ENTER to open a radio-button picker where you can select a single active provider.
• Bundled plugins appear in the same list alongside others, marked with a [bundled] tag.

Your provider plugin selections are saved into config.yaml:

memory:
  provider: "honcho"      # empty string = built-in only

context:
  engine: "compressor"    # default built-in compressor

Enabled vs. disabled vs. neither​

Every plugin exists in one of three possible states:

The default state for a newly installed plugin or a bundled plugin is not enabled. Running hermes plugins list displays all three distinct states, so you can clearly see which plugins have been explicitly disabled versus those that are simply waiting to be enabled.

During an active session, you can use /plugins to see which plugins are currently loaded.

Injecting Messages​

Plugins have the ability to insert messages into the currently active conversation by calling ctx.inject_message():

ctx.inject_message("New data arrived from the webhook", role="user")

Signature: ctx.inject_message(content: str, role: str = "user") -> bool

The behavior depends on the agent's current state:

• When the agent is idle (awaiting user input), the injected message is placed into the queue as the next input, which triggers a new turn.
• When the agent is mid-turn (actively processing), the message interrupts the ongoing operation — this behaves identically to a user typing a new message and pressing Enter.
• For roles other than "user", the content is automatically prefixed with [role] (for example, [system] ...).
• The method returns True if the message was successfully queued, and False when no CLI reference is available (such as in gateway mode).

This capability is particularly useful for plugins such as remote control viewers, messaging bridges, or webhook receivers that need to feed messages into the conversation from external sources.

Note that inject_message is only functional in CLI mode. In gateway mode, there is no CLI reference available, so the method will always return False.

For comprehensive details on handler contracts, schema format, hook behavior, error handling, and common mistakes, refer to the full guide.