From bf53915331b7a928bd147cbca9cdf624760c7c4d Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Mon, 17 Aug 2026 14:17:21 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20Bot=20Mode=20guide=20=E2=80=94=20Create?= =?UTF-8?q?-on=20picker,=20cross-machine=20mentions=20+=20group=20chats?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Community asks (Discord, Aug 17): unclear what happens across cloud vs desktop, whether every bot replies in group chats, and how to persist connections to multiple gateways. Extends the Bot Mode user-guide page (landed on main today) with the new cross-connection features: - "Create on" picker: creating an agent on another registered machine, with the remote-target caveats (clone source, staged capability checklists, draft discard). - Group chats: explicit "not every bot replies" explanation of the round-robin/pass model, and rooms spanning machines with device badges. - @mentions across machines via the Connections registry (no gateway switch). - Bots-across-machines section: persistent SSH inventory, last-known rows, and the stay-in-your-chat interaction model; cloud+desktop recipe. - desktop.md Bot Mode section links to the full guide; multi-connection page's Bot Mode reference points at the docs page instead of the old standalone repo. --- website/docs/user-guide/bot-mode.md | 19 ++++++++++++++++++- website/docs/user-guide/desktop.md | 4 ++++ .../user-guide/multi-connection-desktop.md | 4 ++-- 3 files changed, 24 insertions(+), 3 deletions(-) diff --git a/website/docs/user-guide/bot-mode.md b/website/docs/user-guide/bot-mode.md index 173dbc4ce4..4c81f86d2a 100644 --- a/website/docs/user-guide/bot-mode.md +++ b/website/docs/user-guide/bot-mode.md @@ -39,6 +39,18 @@ An **Advanced** disclosure opens the full capabilities surface: - **Per-skill, per-toolset, and per-MCP-server enablement** — tick exactly the capabilities this specialist needs. - **Shared keys** — by default the new Bot shares one OAuth/token pool with the main profile, so credential refreshes cannot invalidate each other. (Older gateways copy credentials instead — still functional, just forked.) +### Choosing which machine it lives on ("Create on") + +With more than one connection registered in [Settings → Connections](./multi-connection-desktop.md), the New Agent dialog grows a **Create on** picker. Pick a device and the profile is created on **that** machine's backend — your window never switches gateways. The new Bot then appears in the roster as a Connections Bot (with an `@name-device` handle when the name exists on several machines), and chatting with it routes to its own machine. + +With a single connection (the common case) the picker is hidden and the Bot is created on the machine you're connected to — exactly the old behavior. + +Remote-creation notes: + +- **Clone source** is a profile of the *target* machine (its `default`) — a remote box doesn't have your local profiles to clone. +- The live Capabilities tab binds to your active gateway, so a remote-target draft uses the staged Skills/Tools/MCP checklists instead; both read the target machine's catalog. +- Cancelling the dialog discards the draft profile on whichever machine it was created. + **Edit Profile** (right-click a Bot) reopens the same surface on the live profile any time: avatar, title, description, model pin, skills, toolsets, MCP servers, and the full SOUL.md. **Duplicate** (right-click) makes a full clone of a Bot — config, skills, SOUL.md, memory, and its look. **Delete Profile** permanently removes one, behind the same destructive confirmation the desktop's profile menu uses; the default profile cannot be deleted. @@ -70,12 +82,15 @@ Right-click a Bot → **Move to group** to organize the roster into labeled sect - Bots pull each other in with `@name`, and escalate real judgment calls to you with `@user` — the group header shows a **needs you** badge when that happens. - Hard caps (10 messages per send, 3 rounds) keep rooms from spinning. - Each member keeps its own persistent `Group: ` session, so room context survives like any other conversation. +- **Not every Bot replies to every message.** Speaking is each member's own choice — a Bot replies only when it has something new to add and passes otherwise, and @-mentioning specific members scopes the round to them. Expect the members you addressed (or whoever has something to say) to speak, and the rest to stay quiet. +- **Rooms can span machines.** The New Group Chat picker seats Bots from any registered connection; each member's turns run on its own machine, in its own `Group: ` session there. Cross-machine members carry a device badge (`dixie · Mac Mini`) in the room and in other members' transcripts, and the disambiguated `@name-device` handle works in room mentions — so same-named agents on two machines never blur together. ## Bot-to-bot messaging Bots message each other with attribution, and you can hand work off from any chat: - **@mentions** — type `@researcher have a look at this` in any chat and the active Bot hands the message off, waits for the reply, and reports back. Mention names are validated against the live roster, so an email address or an unknown `@` passes through untouched. +- **@mentions across machines** — mentioning a Bot that lives on another registered connection (use its `@name-device` handle when names collide) delivers over the Connections registry in the background: the active Bot stays on this device, the desktop routes the message to the recipient's machine, and the reply is relayed back attributed to that agent. Your window's gateway never switches. - **Direct messages** — a Bot reaches a teammate's Bot Chat through the standard CLI: `hermes -p chat --in ~ -c "Bot Chat" --create-if-missing -Q -q "Message from 🤖 (@): ..."`. The receiving Bot sees the message the next time it runs and knows how to reply, because the messaging protocol is part of its Bot Chat system prompt. The backend teaches each Bot's canonical Bot Chat session the messaging protocol automatically at prompt-build time — including when a teammate opens it headlessly from the CLI. Only the canonical Bot Chat gets the protocol section; your regular sessions and your SOUL.md stay untouched. This is controlled by `agent.bot_mode_protocol` in `config.yaml` (default: on): @@ -91,7 +106,9 @@ Bot-to-bot delivery is per-invocation: the receiving Bot picks the message up wh ## Bots across machines -When you register several backends in **Settings → Connections** — the local runtime, remote gateways, SSH hosts, Hermes Cloud instances — the roster shows the Bots from **every** connected source. When the same profile name exists on several sources, handles disambiguate as `@name-device` (for example `@research-homelab`). Opening a Bot dials its own source: its chats, sessions, memory, and routines live on the machine that owns the profile. +When you register several backends in **Settings → Connections** — the local runtime, remote gateways, SSH hosts, Hermes Cloud instances — the roster shows the Bots from **every** connected source, persistently: SSH sources are inventoried without spawning anything on the remote box, and machines that are momentarily unreachable keep their last-known rows instead of vanishing. When the same profile name exists on several sources, handles disambiguate as `@name-device` (for example `@research-homelab`). A Bot's chats, sessions, memory, and routines live on the machine that owns the profile. + +Clicking a Connections Bot does **not** hop your window onto that machine — stay in your chat and `@mention` it, seat it in a group chat, or create new agents on it directly with the **Create on** picker. Cloud and local agents share one roster this way: register your Hermes Cloud instance and your desktop (say, over Tailscale or SSH) and their Bots can message each other and sit in the same rooms, with each agent's work running on its own machine. See [Connecting Desktop to Many Hermes Instances](./multi-connection-desktop.md) for the full multi-connection guide. diff --git a/website/docs/user-guide/desktop.md b/website/docs/user-guide/desktop.md index d18ab7cb11..1ec1c9f253 100644 --- a/website/docs/user-guide/desktop.md +++ b/website/docs/user-guide/desktop.md @@ -185,6 +185,10 @@ sessions stay untouched. Don't want it? Flip it off in **Settings → Plugins → Bots** — the roster, routines pane, and composer middleware unregister live, no restart needed. +Full guide — creating agents (including the multi-machine **Create on** +picker), the roster across connections, bot-to-bot mentions, and how group +chats decide who replies: [Bot Mode: A Roster of Agents](./bot-mode.md). + ### Keyboard & navigation - **Command palette** — press **Cmd+K** or **Cmd+P** (Ctrl+K / Ctrl+P on Windows/Linux) to jump to actions and navigate the app from the keyboard: open any page or settings section, jump to a session by title or id, switch model/theme/color mode, spawn a terminal, restart the gateway, update Hermes, and more. diff --git a/website/docs/user-guide/multi-connection-desktop.md b/website/docs/user-guide/multi-connection-desktop.md index 8ecab447b0..628b9d094a 100644 --- a/website/docs/user-guide/multi-connection-desktop.md +++ b/website/docs/user-guide/multi-connection-desktop.md @@ -116,8 +116,8 @@ machine keep working. If a migrated name collided, it was suffixed ## Agents across sources Every [profile](./profiles.md) on every registered connection is an *agent*. -The union roster is what multi-source surfaces (and plugins like -[Bot Mode](https://github.com/NousResearch/Hermes-Bot-Mode)) render: +The union roster is what multi-source surfaces (and the built-in +[Bot Mode](./bot-mode.md) roster) render: - When the same profile name exists on several sources, handles disambiguate as **`@name-device`** — `research` on your Homelab renders as