Bot-to-Bot Messaging and @Mentions

The @mention Handoff

In any chat session -- not just group chats -- you can involve another bot by @mentioning it. Type @researcher have a look at this in a conversation with any active bot, and that bot will hand off the message to the researcher bot, wait for a reply, and report back to you.

Mention names validate against the live roster before dispatch. If you mistype a name or mention a bot that does not exist, the system catches it rather than sending a message into the void.

This is the lightweight alternative to a group chat. When you want one bot to consult another on a specific question without setting up a full group session, @mentions handle it directly in the current conversation.

How the Messaging Protocol Works

For bot-to-bot messaging to work, each bot needs to know about its teammates -- who they are and how to reach them. Bot Mode handles this automatically through a configuration key called agent.bot_mode_protocol in config.yaml. It defaults to true and does not need to be set manually.

When this is enabled, the backend injects the bot-to-bot messaging protocol into each bot's canonical Bot Chat session at prompt-build time. Every bot learns the roster, learns how to address teammates, and learns the mechanics of sending and receiving messages -- including what to do when it receives a headless message from the CLI.

This injection is automatic. You do not configure the messaging protocol per bot; it is applied system-wide based on the live roster at the time each session is built.

Cross-Machine @Mentions

When bot names collide across registered machines, each bot receives a disambiguated handle in the format @name-device. For example, if both your laptop and your home server have a bot named "researcher", they become @researcher-laptop and @researcher-homelab (or whatever the machine identifiers are in your Connections registry).

Cross-machine @mentions route through the Connections registry without switching your window gateway. The bot is addressed on its home machine, and the reply comes back through the same routing.

The CLI Direct Message Pattern

For scripted or programmatic bot-to-bot messages -- for example, from within a routine or an external script -- the CLI pattern for sending a direct message to a bot's canonical chat is:

hermes -p <receiving-bot> chat --in ~ -c "Bot Chat" --create-if-missing -Q -q "<message content>"

The -Q flag runs headlessly (no interactive TTY required). The -q flag passes the message as a single-shot prompt. The --in ~ and -c "Bot Chat" flags target the canonical Bot Chat session specifically rather than creating a new one. The --create-if-missing flag ensures the session exists before sending.

Because bot_mode_protocol is injected at prompt-build time, the receiving bot already understands the message format and context when it next runs.

Per-Invocation Delivery

Bot-to-bot message delivery is per-invocation: the receiving bot picks up the message when it next runs. There is no push notification system or background daemon polling for incoming messages.

For time-sensitive coordination, the recommended approach is to give the receiving bot a short-interval routine that checks its canonical chat regularly. This is more reliable than expecting instant delivery and fits the async-first design of the system.