Плагины

У Hermes есть система плагинов для добавления пользовательских инструментов, хуков и интеграций без изменения основного кода.

Если вы хотите создать собственный инструмент для себя, своей команды или одного проекта, плагины — это правильный путь. Страница Добавление инструментов предназначена для встроенных основных инструментов Hermes, которые находятся в tools/ и toolsets.py.

→ Создать плагин Hermes — пошаговое руководство с полным рабочим примером.

Краткий обзор

Перетащите каталог в ~/.hermes/plugins/ с plugin.yaml и кодом Python:

~/.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)

Запустите Hermes — ваши инструменты появятся рядом со встроенными. Модель может позвонить им немедленно.

Минимальный рабочий пример

Вот полный плагин, который добавляет инструмент hello_world и регистрирует каждый вызов инструмента через хук.

~/.hermes/plugins/hello-world/plugin.yaml

name: hello-world
version: "1.0"
description: A minimal example plugin

~/.hermes/plugins/hello-world/__init__.py

"""Minimal Hermes plugin — registers a tool and a hook."""

import json


def register(ctx):
    # --- Tool: hello_world ---
    schema = {
        "name": "hello_world",
        "description": "Returns a friendly greeting for the given name.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Name to greet",
                }
            },
            "required": ["name"],
        },
    }

    def handle_hello(params, **kwargs):
        del kwargs
        name = params.get("name", "World")
        return json.dumps({"success": True, "greeting": f"Hello, {name}!"})

    ctx.register_tool(
        name="hello_world",
        toolset="hello_world",
        schema=schema,
        handler=handle_hello,
        description="Return a friendly greeting for the given name.",
    )

    # --- Hook: log every tool call ---
    def on_tool_call(tool_name, params, result):
        print(f"[hello-world] tool called: {tool_name}")

    ctx.register_hook("post_tool_call", on_tool_call)

Drop both files into ~/.hermes/plugins/hello-world/, restart Hermes, and the model can immediately call hello_world. The hook prints a log line after every tool invocation.

Project-local plugins under ./.hermes/plugins/ are disabled by default. Enable them only for trusted repositories by setting HERMES_ENABLE_PROJECT_PLUGINS=true before starting Hermes.

What plugins can do

Every ctx.* API below is available inside a plugin's register(ctx) function.

Plugin discovery

Later sources override earlier ones on name collision, so a user plugin with the same name as a bundled plugin replaces it.

Plugin sub-categories

Within each source, Hermes also recognizes sub-category directories that route plugins to specialized discovery systems:

User plugins at ~/.hermes/plugins/model-providers/<name>/ and ~/.hermes/plugins/memory/<name>/ override bundled plugins of the same name — last-writer-wins in register_provider() / register_memory_provider(). Drop a directory in, and it replaces the built-in without any repo edits.

Plugins are opt-in (with a few exceptions)

General plugins and user-installed backends are disabled by default — discovery finds them (so they show up in hermes plugins and /plugins), but nothing with hooks or tools loads until you add the plugin's name to plugins.enabled in ~/.hermes/config.yaml. This stops third-party code from running without your explicit consent.

plugins:
  enabled:
    - my-tool-plugin
    - disk-cleanup
  disabled:       # optional deny-list — always wins if a name appears in both
    - noisy-plugin

Три способа перевернуть состояние:

hermes plugins                    # interactive toggle (space to check/uncheck)
hermes plugins enable <name>      # add to allow-list
hermes plugins disable <name>     # remove from allow-list + add to disabled

After hermes plugins install owner/repo, you're asked Enable 'name' now? [y/N] — defaults to no. Skip the prompt for scripted installs with --enable or --no-enable.

What the allow-list does NOT gate

Several categories of plugin bypass plugins.enabled — they're part of Hermes' built-in surface and would break basic functionality if gated off by default:

In short: bundled "always-works" infrastructure loads automatically; third-party general plugins are opt-in. The plugins.enabled allow-list is the gate specifically for arbitrary code a user drops into ~/.hermes/plugins/.

Migration for existing users

When you upgrade to a version of Hermes that has opt-in plugins (config schema v21+), any user plugins already installed under ~/.hermes/plugins/ that weren't already in plugins.disabled are automatically grandfathered into plugins.enabled. Your existing setup keeps working. Bundled standalone plugins are NOT grandfathered — even existing users have to opt in explicitly. (Bundled platform/backend plugins never needed grandfathering because they were never gated.)

Available hooks

Plugins can register callbacks for these lifecycle events. See the Event Hooks page for full details, callback signatures, and examples.

Plugin types

Hermes has four kinds of plugins:

Memory providers and context engines are provider plugins — only one of each type can be active at a time. Model providers are also plugins, but many load simultaneously; the user picks one at a time via --provider or config.yaml. General plugins can be enabled in any combination.

Pluggable interfaces — where to go for each

The table above shows 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:

NixOS declarative plugins

В NixOS плагины можно установить декларативно через опции модуля — hermes plugins install не требуется. Подробнее в руководстве по установке Nix.

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" ];
};

Декларативные плагины имеют символическую ссылку с префиксом nix-managed- — они сосуществуют с плагинами, установленными вручную, и автоматически очищаются при удалении из конфигурации Nix.

Управление плагинами

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

Интерактивный интерфейс

Запуск плагинов Hermes без аргументов открывает составной интерактивный экран:

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

• Раздел «Общие плагины» — флажки, переключаются ПРОБЕЛОМ. Установлено = в plugins.enabled, снято = в plugins.disabled (явно отключено).
• Раздел «Плагины поставщика» — показывает текущий выбор. Нажмите ВВОД, чтобы перейти к средству выбора радио, в котором вы выбираете одного активного провайдера.
• Плагины в комплекте отображаются в одном списке с тегом [bundled].

Выбор плагинов провайдера сохраняется в config.yaml:

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

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

Включено, отключено или нет

Плагины занимают одно из трёх состояний:

По умолчанию для вновь установленного или включенного плагина установлено значение «не включено». «Список плагинов Hermes» показывает все три различных состояния, поэтому вы можете отличить то, что было явно отключено, а что просто ожидает включения.

В работающем сеансе /plugins показывает, какие плагины загружены в данный момент.

Внедрение сообщений

Плагины могут вставлять сообщения в активный диалог, используя ctx.inject_message():

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

Подпись: ctx.inject_message(content: str, role: str = "user") -> bool

Как это работает:

• Если агент бездействует (ожидает ввода пользователя), сообщение ставится в очередь в качестве следующего ввода и начинает новый ход.
• Если агент находится в середине хода (активно работает), сообщение прерывает текущую операцию — так же, как если бы пользователь вводил новое сообщение и нажимал Enter.
• Для ролей, отличных от "пользователей", контент имеет префикс [role] (например, [system]...).
• Возвращает True, если сообщение было успешно поставлено в очередь, и False, если ссылка CLI недоступна (например, в режиме шлюза).

Это позволяет плагинам, таким как средства просмотра удаленного управления, мосты обмена сообщениями или приемники веб-перехватчиков, передавать сообщения в разговор из внешних источников.

См. полное руководство для получения информации о контрактах обработчиков, формате схемы, поведении перехватчиков, обработке ошибок и распространенных ошибках.