Bot Mode

Bot Mode turns your Hermes profiles into a roster of named Bots. Each Bot has its own role, model, memory, skills, and avatar; Bots run recurring routines, deliberate together in group chats, and message each other directly. Build a specialist Bot once and it is there forever, one click away.

Bot Mode ships built into the desktop app and is on by default — no install needed. It appears as a Bots tab next to Sessions in the left sidebar, with a Routines tile docked beside the conversation while the Bots tab is active.

:::tip A Bot is a profile There is no new primitive to learn: a Bot is a Hermes profile — isolated config, memory, skills, credentials, and chat history under ~/.hermes/profiles/<name>/. Bot Mode is a UI over that primitive, so everything you do in it is visible from the CLI too: hermes -p <bot> chat opens the same agent, and Bot routines appear in hermes cron list. No core patches, no background daemons, no extra storage. :::

The Bots pane

The roster shows one row per agent profile: avatar, latest-message preview, and timestamp.

• Click a Bot to land in its chat — every Bot has a canonical, persistent Bot Chat conversation that is created (and pinned) the moment the Bot is born.
• Sessions (from a Bot's context menu) browses and filters that profile's 200 most recent stored conversations, without changing the primary click-to-chat flow.
• Active now — a presence strip above the roster shows every Bot currently working: the gateway-busy profile plus any Bot that wrote within the last 90 seconds. Each chip opens that Bot's chat. The strip never reorders the roster and disappears when the fleet is idle.
• Search filters the roster as you type.
• Hide a Bot — right-click a row → Hide Bot to take a Bot you don't use out of the roster and the Active-now strip. Hiding is display-only: @mentions still resolve, group-chat memberships are untouched, and routines keep running. Once at least one Bot is hidden, an eye toggle appears in the pane header — click it to reveal hidden Bots dimmed in place, then right-click → Unhide Bot to bring one back. Hidden Bots never toast, but they accumulate unread activity silently and the eye badges a dot so you know something happened. Hidden state is saved in the Bot's profile metadata, so it follows the Bot to every desktop connected to that backend.

:::note The canonical Bot Chat is a forever-chat Typing /new (or /reset) inside a Bot's canonical chat would fork the relationship into a scratch session — the one thing Bot Mode promises never happens. The composer reroutes it to /compact instead: fresh working context, same conversation. Regular sessions on the same profile keep full /new freedom. :::

Creating a Bot

Hit New Agent in the roster. The quick path is three fields — Name, Title, Description — and the Bot exists in seconds, introducing itself as the first message of its new Bot Chat.

An Advanced disclosure opens the full capabilities surface:

• Clone from an existing profile — start from another Bot's config, skills, SOUL, and memory, or pick Fresh profile for a clean start.
• Create empty — skip the bundled skills entirely for a minimal profile.
• Model & provider pin — give the Bot its own model. Any provider/model pair Hermes knows about works, and different Bots can run on different models side by side. Leave it unset to inherit from the launch profile.
• Custom SOUL.md — the Bot's persona and standing instructions.
• 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, 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.

Avatars

Every Bot gets a face:

• Geometric faces — 7 shapes × 10 colors, with blinking eyes that scan while the Bot works.
• An uploaded image — any picture you like.
• An AI-generated portrait — when an image backend is configured, generated in place (this rides the standard image.generate RPC and works over both local and remote gateways).
• A pixel pet — a companion from the petdex gallery that bounces beside the avatar while the Bot is busy. Run hermes pets in a terminal to explore the gallery.

A Bot's look, title, and description are stored in the profile's metadata on the backend, so the same Bot appears the same way on every desktop connected to that backend.

Routines

The Routines pane attaches recurring tasks to the Bot that does them — "summarize my inbox every morning" lives next to the Bot responsible for it. The pane docks beside the chat only while the Bots tab is active and steps aside when you switch back to Sessions (older desktop builds keep it always visible). A structured schedule picker builds the schedule (frequency first, then only the detail that matters), with an Advanced field exposing the raw Hermes schedule string.

Routines are plain Hermes cron jobs namespaced [bot:<name>] <routine> — they also show up in hermes cron list and the core Cron page. Runs land in the Bot's own chat history, so the result is right where you would talk to that Bot anyway.

Groups and group chats

Right-click a local Bot → Manage groups to add or remove it from any number of group chats. Pick existing groups independently or create one inline. Local membership is stored in the Bot's backend-synced profile metadata, so it follows that profile across desktops; older profiles with one legacy group continue to work. Connections Bots join through the New Group Chat picker and remain source-qualified in that room's local Desktop state.

Groups are standalone rows in the same activity-ordered roster as Bot DMs. A Bot keeps one DM row even when it belongs to several groups, while every group gets its own room row with member count, latest-message preview, timestamp, and needs-you state.

Open chat on any group row (2–6 Bots) opens a shared room where the whole group coordinates:

• Your message triggers up to three serial rounds of member turns. @-mentioned Bots respond (everyone responds when nobody is mentioned); each Bot replies briefly or passes, and the room settles when a full round stays silent.
• Bots pull each other in with @name, and escalate real judgment calls to you with @user — the group row 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: <name> 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: <name> 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 <bot> chat --in ~ -c "Bot Chat" --create-if-missing -Q -q "Message from 🤖 <sender> (@<sender>): ...". 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):

agent:
  bot_mode_protocol: true   # inject the bot-to-bot messaging protocol into canonical Bot Chats

:::note Bot-to-bot delivery is per-invocation: the receiving Bot picks the message up when it next runs. Live interrupt of a Bot mid-conversation is future work. :::

Bot-initiated DMs across machines (hermes peer)

Bots on one machine can message Bots on another machine's gateway without any desktop in the loop. Register the other gateway as a peer (its API server URL + API_SERVER_KEY):

hermes peer add spark --url http://spark.lan:8377 --key <API_SERVER_KEY>
hermes peer list
hermes peer dm spark "Message from 🤖 dixie (@dixie): disk status?"
hermes peer dm spark/researcher "..."   # named profile on a multiplexed peer

hermes peer dm delivers into the remote agent's canonical Bot Chat over the peer's existing API server, runs one agent turn there, and prints the reply on stdout — the exact cross-machine twin of the local hermes -p <bot> chat command.

Once a peer is registered, the messaging protocol taught to every Bot Chat (agent.bot_mode_protocol) automatically includes the peer roster and the hermes peer dm pattern — so your bots learn on their own that teammates exist on other machines and how to reach them. Registering or removing a peer refreshes each Bot Chat's protocol on its next message (capability epoch).

Requirements: the peer machine runs the api_server gateway platform with a strong API_SERVER_KEY; reachability is your network's business (LAN, Tailscale, VPN). The key is a credential and lives in ~/.hermes/.env as HERMES_PEER_<NAME>_KEY; peer names/URLs live in config.yaml under bot_peers.

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, 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 for the full multi-connection guide.

Turning it off

Bot Mode is a bundled desktop plugin. Flip it off in Settings → Plugins → Bots — the roster, the Routines pane, and the composer middleware unregister live, no restart needed. Your profiles, sessions, and cron jobs are untouched either way; Bot Mode never owns your data, it only renders it.

There is also a preference to hide the canonical Bot Chats from the regular sidebar session list, so they only appear inside the Bots pane. (This uses the core hidden-session flag; on older gateways the chats simply stay visible.)

CLI parity

Because Bots are profiles, everything has a terminal equivalent:

See Profiles for the underlying primitive and Profile Commands for the full CLI reference.