hermes-bus-plugin 0.3.1

Hermes bus integration plugin — auto-start, auto-register, message injection, bus tools

hermes-bus-plugin

English | 中文

Hermes Agent plugin for message bus integration — lifecycle management, external message injection, bus tools.

A thin integration layer between Hermes Agent and the hermes-bus / hermes-notify packages.

Install

# Via Hermes plugin manager
hermes plugins install hermes-bus-plugin

# Or copy to ~/.hermes/hermes-agent/plugins/
cp -r hermes-bus-plugin ~/.hermes/hermes-agent/plugins/
hermes plugins enable hermes-bus-plugin

Session Naming

Each CLI window registers a unique bus endpoint on startup. The default endpoint is hermes-bus (first session), with hermes-bus-2, hermes-bus-3, etc. for additional sessions. To give your session a stable name that survives reconnection:

/title my-agent-name

The plugin uses the title set by /title as the bus endpoint name.

Action	When	Description
Start bus daemon	Plugin load	Ensures hermes-bus is running
Register listener	Plugin load	Opens a bus endpoint for incoming messages
Print notifications	On bus message	Messages matching notify.yaml rules with print: true are printed to terminal immediately
Inject context	pre_llm_call	Queued bus messages (matching rules with context: true) are injected into LLM context

Provided Tools

bus_send — send a message through the bus to any endpoint:

bus_send(target="notifier", type="progress", text="50% done")

bus_status — check bus health and connected endpoints:

bus_status()

bus_info — show current session's bus connection details:

bus_info()

Route Rules

Messages arriving at the bus are matched against ~/.hermes/bus-rules.yaml rules. Each rule can trigger three independent actions — all, some, or none:

Field	Behavior	Default
print	Print to terminal immediately	false
print_format	Template for terminal output (see below)	[{from}] {text}
context	Inject into LLM context on next agent call	false
command	Execute shell command (audio, script, etc.)	none

The three actions are independent — print: true and context: true and a command will all fire for the same message.

Print Format

print_format supports ANSI colors and placeholders:

Placeholder	Description	Example
{from}	Sender endpoint name	银锭
{text}	Message body text	任务完成
{type}	Message type	task_done
{ts}	Unix timestamp (raw)	1744986323
{ts:%Y-%m-%d %H:%M:%S}	strftime formatted	2026-05-18 17:45:23
{color:cyan}	Foreground color	black/red/green/yellow/blue/magenta/cyan/white
{color:bold_green}	Bold color variant	bold_red, bold_green, ...
{bold}	Bold text
{reset}	Reset all styles

Example rule with all three actions:

callbacks:
  - match_type: task_done
    print: true
    print_format: "{color:bold_green}✔ {from}{reset}  {color:cyan}[{ts:%H:%M:%S}]{reset}  {text}"
    context: true
    command: "afplay ~/sounds/done.mp3"

Requirements

• hermes-bus (pip)
• hermes-notify (pip)

Both are auto-detected — the plugin degrades gracefully if they're missing.

Architecture

External process ──→ hermes-bus ──→ hermes-bus-plugin ──→ LLM context
                        (socket)        (pre_llm_call hook)
                        
Hermes session ──→ bus_send tool ──→ hermes-bus ──→ target endpoint