hermes-rtk-optimizer

Hermes-native RTK optimizer plugin.

It does two things:

• rewrites Hermes terminal commands through rtk rewrite
• compacts noisy tool output before it goes back into model context

This is a pip-installable Hermes plugin. It does not patch Hermes core.

Features

• pre_tool_call rewrite for terminal
• transform_terminal_output compaction for foreground terminal output
• transform_tool_result compaction for read_file, search_files, and process
• fail-open behavior when RTK is missing or compaction fails
• lightweight session metrics
• slash command: /rtkopt
• rewrite mode or suggestion-only mode

Install in Hermes

1. Install RTK first

This plugin calls the rtk command, so install RTK before installing the Hermes plugin:

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

Verify RTK is available:

rtk --version

If rtk is not found, restart your shell or add the RTK install directory to PATH.

2. Install the Hermes plugin

This package is not on PyPI yet. Install it from GitHub with Hermes' own Python environment, not your system Python:

$HOME/.hermes/hermes-agent/venv/bin/python -m pip install git+https://github.com/ch0udry/hermes-rtk-optimizer.git

Alternative: clone and install locally if you want to edit the plugin or contribute changes:

git clone https://github.com/ch0udry/hermes-rtk-optimizer.git
cd hermes-rtk-optimizer
$HOME/.hermes/hermes-agent/venv/bin/python -m pip install -e .

3. Enable the plugin

Edit ~/.hermes/config.yaml and add hermes-rtk-optimizer under plugins.enabled:

plugins:
  enabled:
    - hermes-rtk-optimizer

If you already have other enabled plugins, keep them and add hermes-rtk-optimizer as another item.

Restart Hermes or start a fresh hermes chat process.

Verify

Quick check:

$HOME/.hermes/hermes-agent/venv/bin/python - <<'PY'
from hermes_cli.plugins import get_plugin_manager
pm = get_plugin_manager()
pm.discover_and_load(force=True)
print([p for p in pm.list_plugins() if p['name'] == 'hermes-rtk-optimizer'])
PY

Command rewrite check:

$HOME/.hermes/hermes-agent/venv/bin/python - <<'PY'
from hermes_cli.plugins import get_plugin_manager
pm = get_plugin_manager()
pm.discover_and_load(force=True)
args = {'command': 'git status --short'}
pm.invoke_hook('pre_tool_call', tool_name='terminal', args=args, task_id='t', session_id='s', tool_call_id='c')
print(args['command'])
PY

Slash command

Inside Hermes:

• /rtkopt
• /rtkopt show
• /rtkopt verify
• /rtkopt stats
• /rtkopt reset-stats
• /rtkopt config-path

Config

Config file path:

~/.hermes/plugin-data/hermes-rtk-optimizer/config.json

Example:

{
  "enabled": true,
  "mode": "rewrite",
  "guard_when_rtk_missing": true,
  "show_rewrite_notifications": true,
  "rtk_timeout_ms": 3000,
  "output_compaction": {
    "enabled": true,
    "strip_ansi": true,
    "aggregate_test_output": true,
    "filter_build_output": true,
    "compact_git_output": true,
    "aggregate_linter_output": true,
    "group_search_output": true,
    "source_code_filtering_enabled": true,
    "source_code_filtering": "minimal",
    "preserve_exact_reads_under_lines": 80,
    "smart_truncate_max_lines": 220,
    "truncate_max_chars": 12000,
    "track_savings": true
  }
}

Design

• RTK remains the source of truth for rewrite policy.
• Hermes hooks are the integration layer.
• Non-terminal tool compaction preserves JSON shape.
• Read output stays exact for explicit ranged reads and short results.

Development

python -m pytest

License

MIT