hermes-ircx-plugin

Connect your Hermes Agent to IRC - channels and DMs - with a full, modern IRCv3 stack.
_{A feature superset of the stdlib irc example Hermes ships with, and then some. 💬}

📖 Deep-dive docs: Configuration · Interactive Behaviours · Authentication & SASL · Troubleshooting - see docs/ (also mirrored to the Wiki).

🛰️ Why IRCX?

Hermes ships only a minimal stdlib irc example. IRCX is a more complete alternative - built on the spec-compliant irctokens + ircstates IRCv3 libraries - that turns your agent into a real channel citizen: it authenticates properly, remembers conversations across disconnects, can manage its own channels on request, and can even chime into the conversation on its own.

Platform name: ircx - coexists with the bundled irc example, so you can run both side-by-side and switch when ready.

✦ Features

🎭 Interactive agent behaviours

▶ Install

1 · Dependencies (into the env your Hermes gateway runs from):

<hermes-venv>/bin/python -m pip install irctokens ircstates

2 · Drop in the plugin - either works:

cp -r plugins/platforms/ircx ~/.hermes/plugins/ircx            # as a user plugin
# or, inside a hermes-agent checkout:
cp -r plugins/platforms/ircx <hermes-agent>/plugins/platforms/ircx

3 · Configure (env in ~/.hermes/.env, or config.yaml → gateway.platforms.ircx.extra):

IRCX_SERVER=irc.libera.chat
IRCX_CHANNEL=#yourchannel
IRCX_NICKNAME=hermes-bot
IRCX_SASL_MECHANISM=PLAIN
IRCX_SASL_USERNAME=hermes
IRCX_SASL_PASSWORD=••••••••
IRCX_ALLOWED_USERS=youraccount       # verified accounts allowed to command the bot

Restart the gateway and you're live. Every IRCX_* var falls back to the legacy IRC_* name, so existing example-plugin setups work unchanged.

# Observe mode - occasionally chime in on unaddressed chatter
IRCX_OBSERVE_MODE=true
IRCX_SPONTANEOUS_PROBABILITY=0.15      # 0..1
IRCX_SPONTANEOUS_COOLDOWN=90           # seconds between spontaneous posts/channel

# Runtime channel agency (agent can join/part/say on request)
IRCX_ALLOW_AGENT_JOIN=true
IRCX_JOINABLE_CHANNELS=#ops,#help      # allowlist; empty = any

# Downtime context persistence
IRCX_LOG_DIR=~/.hermes/logs/ircx       # log + replay channel tail on (re)join
IRCX_CHATHISTORY_LIMIT=50              # IRCv3 draft/chathistory backfill size

See plugins/platforms/ircx/plugin.yaml for every option, and the plugin README for the full behaviour reference.

💬 Chat commands

Drive the bot from a PM or in-channel (authorised users only). Two prefixes:

.agent <command> - agent/gateway controls, bridged to Hermes' slash commands:

.agent model <name>      .agent reasoning high
.agent reset             .agent whoami
.agent help              .agent status

.ircx <command> - live configuration of this IRC adapter, persisted to ircx.env:

.ircx list                       # every non-secret setting + current value
.ircx get observe_mode
.ircx set observe_mode true      # hot keys apply instantly
.ircx set blocked_channels #foo,#bar
.ircx set port 6697              # connection keys: saved, then...
.ircx restart                    # ...apply with a restart

Hot keys apply live; connection keys (server, port, nickname, channel, networks, sasl_*...) need .ircx restart. Secrets (passwords) stay in .env, show as ***, and can't be set from chat. Both prefixes are configurable (IRCX_COMMAND_PREFIX / IRCX_ADMIN_PREFIX).

Point IRCX_CONFIG_FILE at a dedicated ircx.env to keep the adapter's many options out of your main .env; .ircx set writes there.

🧩 Optional: per-channel tool scoping

groups.<chan>.tools / tools_by_sender (toolset-level scoping) is enforced via a tiny, generic, backward-compatible core hook - documented in CORE_PATCH.md. Without the patch the plugin still works; the scope is simply ignored. It's a clean candidate to upstream into Hermes.

🧪 Tests

tests/ run against the Hermes test harness - from inside a hermes-agent checkout with the plugin installed at plugins/platforms/ircx/:

cp tests/test_ircx_*.py <hermes-agent>/tests/gateway/
cd <hermes-agent>
./venv/bin/python -m pytest tests/gateway/test_ircx_adapter.py tests/gateway/test_ircx_features.py -q

91 network-free tests cover config, message splitting, the CAP/SASL state machine (incl. SCRAM-256/512 vs a reference server), mention gating, the verified-account authorization matrix, CTCP, observe-mode, the agency tools, and chathistory/logging. The full connect → CAP → registration → JOIN path has been validated live on Libera.Chat and Rizon.

📦 Status

Well-tested and live-validated, but it hasn't had a long real-world soak yet. Issues and PRs very welcome! 🙌

_{Not affiliated with or endorsed by Nous Research.}

 ·  Built with the Hermes Agent platform-adapter SDK  ·  Report a bug

_{If IRCX is useful to you, consider leaving a ⭐ - it helps others find it.}