rtk-hermes — плагин Hermes для сокращения расхода токенов на shell-команды

Кодинг-агент выполняет множество терминальных команд, а затем отправляет их результаты в контекстное окно LLM. Даже обычный git status, поиск по файлам или запуск тестов могут вернуть заметно больше текста, чем нужно для следующего шага рассуждения. Проект rtk-hermes добавляет в Hermes Agent небольшой плагин, который перехватывает команду до запуска, передает ее в RTK и заменяет исходный вызов более компактным эквивалентом. По оценке автора, такой подход позволяет сократить расход токенов на 60–90%.

Как устроен плагин

rtk-hermes не содержит собственных правил для shell-команд. Вся логика преобразования находится в проекте RTK. Плагин использует hook pre_tool_call, перехватывающий вызов встроенного инструмента Hermes terminal, и выполняет следующий цикл:

1. Агент вызывает terminal с исходной командой.
2. Плагин запускает rtk rewrite с этой командой.
3. RTK возвращает сокращенный эквивалент.
4. Плагин заменяет значение args["command"] на новую команду.
5. Hermes выполняет ее, а RTK фильтрует вывод до того, как тот попадет в контекст модели.

Например, обычный вызов может выглядеть так:

Agent calls terminal(command="cargo test --nocapture")
  -> rtk-hermes receives Hermes' pre_tool_call hook
  -> plugin calls: rtk rewrite "cargo test --nocapture"
  -> RTK returns: rtk cargo test --nocapture
  -> plugin mutates args["command"] in place
  -> Hermes executes the rewritten command
  -> RTK-filtered output reaches the model

Такой дизайн позволяет получать новые правила RTK без выпуска новой версии плагина. При этом набор инструментов Hermes не меняется: это важно для стабильности prompt caching и не требует подключать MCP-сервер.

Установка RTK

Сначала нужен сам бинарный файл RTK. Для macOS его можно установить через Homebrew:

brew install rtk

README также предлагает альтернативный установщик:

curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

После установки стоит проверить доступность бинарного файла и правила преобразования:

rtk --version
rtk rewrite "git status"

Установка плагина

Пакет rtk-hermes нужно поставить именно в то Python-окружение, из которого запускается Hermes. Установка в системный Python, conda или произвольный virtualenv не сделает плагин видимым для агента.

Для стандартной установки Hermes из исходников используется его встроенное окружение:

HERMES_PY="$HOME/.hermes/hermes-agent/venv/bin/python"
"$HERMES_PY" -m pip install --upgrade rtk-hermes

Если hermes запускается через symlink и стандартного пути нет, интерпретатор можно найти по реальному расположению команды:

HERMES_BIN="$(command -v hermes)"
HERMES_REAL="$(python3 -c 'import os, sys; print(os.path.realpath(sys.argv[1]))' "$HERMES_BIN")"
HERMES_PY="$(dirname "$HERMES_REAL")/python"
"$HERMES_PY" -m pip install --upgrade rtk-hermes

В некоторых окружениях Hermes отсутствует pip. Тогда пакет устанавливается через uv с явным указанием нужного интерпретатора:

curl -LsSf https://astral.sh/uv/install.sh | sh
~/.local/bin/uv pip install --python "$HOME/.hermes/hermes-agent/venv/bin/python" --upgrade rtk-hermes

Ошибка This environment is externally managed на Debian и Ubuntu означает, что команда обращается к системному pip. Проект рекомендует не применять --break-system-packages, а указать Python-окружение Hermes явно.

При необходимости можно установить закрепленный wheel непосредственно из релиза GitHub:

HERMES_PY="$HOME/.hermes/hermes-agent/venv/bin/python"
"$HERMES_PY" -m pip install \
  "https://github.com/ogallotti/rtk-hermes/releases/download/v1.2.3/rtk_hermes-1.2.3-py3-none-any.whl"

Активация в Hermes

В Hermes начиная с версии 0.11 pip-плагины нужно включать явно. Откройте ~/.hermes/config.yaml и добавьте плагин в список:

plugins:
  enabled:
    - rtk-rewrite

После изменения перезапустите Hermes или начните новую сессию. Текущая версия CLI может не видеть pip-only entry point, поэтому команда hermes plugins enable rtk-rewrite способна сообщить, что плагин не установлен, даже если пакет уже находится в нужном окружении. Прямое редактирование plugins.enabled — более надежный способ активации.

Какие команды преобразуются

Плагин работает со всеми командами, которые поддерживает rtk rewrite. В README перечислены типичные группы:

• Git: статус, журнал коммитов и diff;
• просмотр файлов: ls, find, grep;
• запуск тестов: pytest, cargo test;
• менеджеры пакетов и сборочные инструменты;
• Docker и Kubernetes.

Актуальный список правил находится в документации RTK: https://github.com/rtk-ai/rtk#commands.

Настройки поведения

Плагин не добавляет новые инструменты Hermes и не запускает MCP-сервер. Поведение настраивается переменными окружения:

Пример настройки:

export RTK_HERMES_MODE=suggest
export RTK_HERMES_TIMEOUT_MS=500
export RTK_HERMES_PREVIEW_MARKER=false
export RTK_HERMES_BACKENDS=local
hermes

По умолчанию разрешен только локальный backend. Если Hermes работает через SSH, Docker или удаленную песочницу, RTK должен быть установлен внутри соответствующей среды. Только после этого можно расширить список:

export RTK_HERMES_BACKENDS=local,ssh

Значение all подходит, когда бинарный файл доступен во всех настроенных backend.

Коды завершения RTK

Плагин интерпретирует результат rtk rewrite по коду возврата:

Код 3 встречается и для корректных преобразований вроде git status в rtk git status, поэтому плагин считает успешными и код 0, и код 3.

Отказоустойчивость

Основной принцип — fail open: отсутствие RTK не должно останавливать работу агента. Исходная команда выполняется без изменений, если RTK не найден, текущий backend выключен, вызов превысил таймаут, процесс завершился аварийно, эквивалента не найдено или появился неожиданный код возврата. В последнем случае плагин записывает предупреждение.

Плагин намеренно не применяет post-processing к read_file, search_files, process и другим инструментам. RTK сокращает вывод только терминальных команд, а не изменяет структурированные результаты остальных инструментов и не скрывает потенциально важные данные для отладки.

Slash-команды и метрики

Если установленная версия Hermes поддерживает slash-команды плагинов, пакет регистрирует:

/rtk status
/rtk stats
/rtk reset-stats
/rtk config

Команды возвращают JSON. Счетчики хранятся только в памяти текущего процесса. Сами команды в метрики не записываются, чтобы случайно не сохранить секреты или приватные аргументы shell.

Проверка и устранение проблем

Если Hermes не видит плагин, сначала проверьте пакет тем же интерпретатором, которым запускается агент:

HERMES_PY="$HOME/.hermes/hermes-agent/venv/bin/python"
"$HERMES_PY" -m pip show rtk-hermes

Если тест преобразования проходит, но команды не меняются, последовательно проверьте rtk --version, результат rtk rewrite "git status", наличие rtk-rewrite в plugins.enabled, перезапуск Hermes, режим RTK_HERMES_MODE и backend в RTK_HERMES_BACKENDS.

Итог

rtk-hermes решает узкую, но часто возникающую задачу: агент по-прежнему выполняет обычные terminal-команды, а плагин заранее заменяет их на RTK-эквиваленты с более компактным выводом. Проект не пытается менять систему инструментов агента, скрывать результаты после выполнения или становиться еще одним MCP-сервером. Он добавляет тонкий слой переписывания, сохраняет исходное поведение при любых сбоях и позволяет включать его только там, где RTK действительно установлен. Текущая версия README — v1.2.3, лицензия — MIT.