Hermes Agent
Hermes Agent Bot Mode: what it is and how to use it
Updated 22 November 2026
Bot Mode is a part of the Hermes desktop app that shows your Hermes profiles as a roster of named bots, each with its own chat, avatar and scheduled routines. This page explains what it changes, how to create a bot, how group chats and bot-to-bot messages work, and how to switch it off.
Facts come from the Hermes Agent 0.23.3 documentation, read on 22 November 2026: Bot Mode, Profiles, Hermes Desktop and the CLI commands reference.
What Bot Mode is
The documentation defines Bot Mode as something that 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, discuss things together in group chats, and message each other directly.
- Where it lives. It is built into the Hermes desktop app and is on by default, with nothing extra to install. It appears as a Bots tab next to Sessions in the left sidebar, and a Routines tile docks beside the conversation while the Bots tab is active.
- What it adds. One permanent chat per bot (the Bot Chat), one roster showing every bot with its avatar and latest message, routines kept beside the chat they belong to, and ways for bots to talk to each other.
- What it does not add. The docs say there is no new primitive, no core patches, no background daemons and no extra storage. Bot Mode is a user interface over profiles.
Do you need it? If you only use Hermes from a terminal, the docs say your profiles keep working exactly as before, and a profile you never add to the roster stays a plain profile. Bot Mode is for people who use the desktop app and want several specialists they can open with one click.
Bots, profiles and Telegram bots
A Bot Mode bot is a Hermes profile. A named profile keeps its settings, memory, skills and chat history under ~/.hermes/profiles/<name>/. The default profile uses ~/.hermes/ itself. The Profiles page puts it this way: every bot is a profile, but not every profile is a bot. A profile becomes a bot when Bot Mode stores its roster presentation (title, avatar, section, hidden state) in the profile’s metadata and pins its canonical Bot Chat. For profiles themselves, see Hermes Agent profiles.
| With plain profiles | With Bot Mode |
|---|---|
| A pile of sessions per profile; you pick one or start another | One permanent Bot Chat per bot. /new compacts it instead of forking it |
| Switch profiles to talk to a different specialist | One roster with avatar, latest message and unread state |
| Profiles never talk to each other | Bots message each other and share group chats |
Scheduled jobs live in hermes cron, apart from any chat | Each bot’s routines are scheduled and edited beside its chat |
Is this the same as a Telegram bot? No. The Profiles page lists them as different things. A messaging bot is an account on a platform such as Telegram, Discord or Slack, connected to Hermes through the gateway, and identified by its bot token. A Bot Mode bot is a profile shown in the desktop roster. The two can sit side by side, but one does not create the other. To put a profile on Telegram you still set up a messaging bot, which Hermes Agent on Telegram walks through. The docs also describe a subagent, a child assistant started by delegate_task for one task, as a third, separate idea.
One setting is shared with messaging platforms: the limit on bot-to-bot messages per exchange (covered below) is documented as applying to Bot Mode and messaging platforms alike.
The Bots pane and creating a bot
The roster shows one row per agent profile, with avatar, a preview of the latest message and a timestamp. Clicking a bot opens its Bot Chat, which is created and pinned the moment the bot exists. Right-click gives more: Open recent session, Hide Bot, Move to section, Manage groups, Edit Profile, Duplicate and Delete Profile. Search filters the roster as you type. Delete Profile asks for confirmation and permanently removes the profile. The default profile cannot be deleted.
- Forever-chat. Typing
/newor/resetin a bot’s canonical chat is rerouted to/compact: fresh working context, same conversation. If you archive a Bot Chat, the next click on the bot starts a new conversation. Hermes keeps the old history in its database, but you can no longer open it from the bot or the archive view. - Hiding. Hiding a bot is display-only. @mentions still resolve, group memberships are untouched and routines keep running. An eye toggle in the pane header reveals hidden bots.
- Sections. Folders you make yourself, such as Clients or Team. To create a section, open the pane’s + menu and choose New section. To put a bot in an existing section, drag its row onto the section. Deleting a section never deletes bots; they return to Unassigned.
To create one, hit New Agent. The quick path is three fields, Name, Title and Description, and the bot exists in seconds, introducing itself as the first message of its Bot Chat. If the bot still needs a model, its creation warning stays visible after the dialog closes; choose Configure model to finish setup. The Advanced disclosure adds:
- Clone from an existing profile, or start from a fresh profile, or create it empty without the bundled skills.
- A model and provider pin, so different bots can run on different models. Unset, it inherits from the launch profile.
- A custom
SOUL.mdfor the bot’s persona and standing instructions. - Per-skill, per-toolset and per-MCP-server enablement.
- Copying API keys from the main profile, on by default. Static keys are copied. For Anthropic, OpenAI Codex and xAI, a bot can share the default profile’s existing OAuth login. To give the bot a separate login, run
hermes -p <name> auth add <provider>.
Avatars can be a blob face drawn deterministically from the bot’s name (same name, same face), a geometric face, an uploaded image, an AI-generated portrait when an image backend is configured, or a pixel pet from the petdex gallery (hermes pets explores it). Voices follow the bot’s own profile: its tts.* settings in that profile’s config.yaml are used, so two bots can sound different.
Routines are plain Hermes cron jobs named [bot:<name>] <routine>. A schedule picker builds the schedule, with an Advanced field for the raw schedule string. They also appear in hermes cron list, and runs land in the bot’s own chat history.
Group chats
A group chat is a shared room with 2 to 6 bots. Right-click a local bot and choose Manage groups to add it to one or more rooms. To include a bot from another connection, use New Group Chat. If every bot you pick is on the same other connection, switch to it first or add a bot from the active one. You can give the room a name and an optional picture. Manage members edits the whole roster at once.
- One visible conversation. Public messages and each member’s reply appear in arrival order with the speaker’s name. Reply in thread continues a topic.
- Who answers. Your message can trigger up to three rounds. Mention specific bots to give them the turn. For a new message that names nobody, a gateway-owned room defaults to Everyone. In Room settings you can choose a lead or let Hermes pick who answers. Each selected bot can reply or pass.
- Handing a question to you. Bots pull each other in with
@nameand escalate real judgment calls to you with@user; the group row then shows a needs you badge. - Caps. Hard caps of 10 messages per send and 3 rounds keep rooms from spinning. On a gateway-owned room the cap pauses the discussion with Continue (up to five times) and Stop buttons.
- Stop. Stop cancels queued continuations and holds the members. Mention a held bot to release that bot, or use
@allor@everyoneto release everyone. Turning off Detect stop directives in the group settings disables written stop commands. The Stop button still works. - When a bot goes quiet. Each member keeps a hidden per-room session that grows with every turn. If a member starts answering with empty replies, Compress history in Group settings runs context compression on that session, one member at a time.
On a connection whose gateway runs group chats, a new group chat is run by that gateway, so a discussion keeps going when you close Hermes Desktop and the room catches up from its log when you reopen the app. A “classic” group chat saved by an older version is driven by Desktop and pauses while it is closed; Desktop no longer creates those. Desktop mirrors the room’s name, picture, members and recent messages to each connected gateway. Another Desktop connected to the same gateway can see the room and that recent transcript.
Bot-to-bot messaging
In any chat, type @ and select the bot, then write your request. In a bot’s canonical Bot Chat, the sending bot composes its own message and sends it with message_agent. The teammate sees who sent it. The first acknowledgement means the message was queued, not that it was answered. The sender normally gets the outcome as a notification. If the acknowledgement says reply_delivery: poll, the sender must call process(action="wait", session_id=…) before ending its turn. If the outcome is unknown, do not resend. Renaming a bot gives it a matching tag, so a bot titled Research Buddy answers to @research-buddy.
By default, the loop guard limits how long bots can keep replying to one another. A reply a bot sends back to the bot that messaged it is notify-only by default, and the runtime counts bot-to-bot sends in an exchange; one that never left the sender, such as to an offline machine, does not count. Your next message starts a new exchange. The defaults and both switches are in config.yaml:
gateway:
bot_loop_guard:
max_hops: 4
bot_replies_expect_reply: false
agent:
bot_mode_protocol: truePast max_hops a further message_agent call is refused. Setting bot_replies_expect_reply to true lets bots answer each other’s replies, still capped by max_hops; enabled: false under bot_loop_guard disables all bot-loop protections, including the message limit. agent.bot_mode_protocol is the master switch for teaching the messaging protocol to each canonical Bot Chat. Failed deliveries carry a typed reason such as provider_rate_limit or target_busy, and a failed turn is retried at most once, only when a retry can help; auth, quota and configuration failures are never retried.
Headless installs. The message_agent tool appears only when two further conditions hold: the session is titled exactly Bot Chat, and at least one profile has a ui_meta block with hermes-bots in its profile.yaml. The desktop app sets both when it creates a bot; there is no CLI command that writes the second. On a machine without Desktop, run the following command once for each bot, replacing <bot> with its profile name. Then add the YAML entry shown below to one profile’s profile.yaml. One marked profile is enough for the whole installation. The tool becomes available on the next turn in the bot’s canonical chat:
hermes -p <bot> chat -c "Bot Chat" --create-if-missing# ~/.hermes/profiles/<any-bot>/profile.yaml
ui_meta:
hermes-bots: {}Without them, the docs say bots still message each other fine over a messaging platform; only the agent-side tool is missing.
Bots across machines
If you register several backends under 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 machines, handles are told apart as @name-device. A bot’s chats, memory and routines live on the machine that owns the profile, and clicking a bot on another machine does not move your window there: stay in your chat and @mention it, or seat it in a group chat.
- Create on. With more than one connection, the New Agent dialog gets a Create on picker, and the profile is created on the machine you select. Remotely, clone from that machine’s default profile or choose Fresh profile.
- The Desktop as courier. Messages between machines are relayed by a running Desktop that knows both connections. If it is closed mid-delivery, the sender is told the reply did not arrive.
- No Desktop needed: peers. For always-on machine-to-machine messaging, register the other gateway as a peer. It must run the
api_serverplatform with a strongAPI_SERVER_KEY, and reachability (LAN, Tailscale, VPN) is up to your network.
hermes peer add spark --url http://spark.lan:8377 --key <API_SERVER_KEY>
hermes peer list
hermes peer dm spark/researcher "message"Use hermes peer dm for a short request. It normally waits for the reply. If the connection ends first, or the remote Bot Chat is open in Desktop and its turn is still running after five minutes, the message is already there or queued. Do not resend it. For a long task, use hermes peer run and check it with hermes peer status <peer>[/<agent>] <run_id> or interrupt it with hermes peer stop <peer>[/<agent>] <run_id>, using the same target and the exact run ID. To retry the original request, reuse its --idempotency-key. To unregister this peer, run hermes peer remove spark, which leaves the key entry in ~/.hermes/.env. The peer’s URL goes into bot_peers in config.yaml, and the key is stored as HERMES_PEER_<NAME>_KEY in ~/.hermes/.env. A gateway behind home NAT can reach a public peer but not the reverse, so for a room that spans a NAT boundary the docs suggest putting the room’s authority on the host everyone can reach, or bridging with Tailscale or a VPN.
For a group chat across machines, keep the home and member gateways running. Send text-only messages to remote members. An attachment causes that member’s turn to fail. The member gateway needs the API server, durable run storage, a gateway.room_link_url reachable from the home gateway, and command approvals on; New Group Chat says which computer needs attention and keeps your draft until you choose Retry. After more than a day idle, reopen the room with the member gateway reachable, or use Retry. For a planned transfer of room authority, stop writes on the old gateway, prevent its restart, and verify the replacement has copied the room log through the final entry; keep the old gateway unable to write until it has been demoted. If you cannot, do not promote the replacement.
Turning it off, and the CLI equivalents
Bot Mode is a bundled desktop plugin. Flip its Desktop switch off in Capabilities, Plugins, Bots; the roster, the Routines pane and the composer middleware unregister live, with no restart. The docs say your profiles, sessions and cron jobs are untouched either way, because Bot Mode only renders your data. While Bot Mode is on, open the Bots pane and select the bot to find its canonical chat.
You can work with the same profiles and routines from a terminal.
| In Bot Mode | From a shell |
|---|---|
| Chat with a bot | hermes -p <bot> chat |
| A bot’s files, skills and memory | ~/.hermes/profiles/<bot>/ |
| Routines | hermes cron list |
| Create and inspect profiles | hermes profile create coder, hermes profile list |
| Message a bot on another machine | hermes peer dm spark/researcher "message" |
Desktop normally connects local bots to a shared gateway. A named profile configured with gateway.standalone: true uses its own gateway. Closing Desktop leaves the gateway running. To turn off Bot Mode, use the plugin switch above. Running hermes gateway stop from the default profile stops the shared gateway and takes every profile it serves offline. Bot Screen is a separate feature for headless Linux gateways. With Computer Use enabled and the screen software installed, open the Screen pane, choose Start screen, then Take over, and Hand back when done. On a shared host, other processes running as the gateway user can reach the screen directly, so use separate hosts if bots need isolation. For another way to organise work across agents, see Hermes Agent Kanban.
Bot Mode and ReadyHermes
ReadyHermes runs your own Hermes Agent on our servers, always on, and you use it from a browser workspace or from chat apps such as Telegram, WhatsApp, Discord, WeChat and Lark. Hermes Desktop can connect to a ReadyHermes assistant as a remote gateway: in the workspace, open Channels, then Hermes Desktop, to get a remote URL, username and password. See the Hermes Agent desktop page for that connection.
We have not tested Bot Mode against a ReadyHermes assistant, so we do not promise that it works there. Each ReadyHermes assistant is one Hermes Agent, and you can add extra assistants to an account as separate bots. Telegram on ReadyHermes is a chat app you connect in Channels, which is the messaging bot described above, not Bot Mode. Plans start from US$3.99 a month with US$1 of AI included every month, and there is a one-hour free trial.
Questions
What is Hermes Agent Bot Mode?
It is a feature of the Hermes desktop app, on by default, that turns your Hermes profiles into a roster of named bots. Each bot has its own role, model, memory, skills and avatar, one permanent Bot Chat and its own routines, and bots can share group chats and message each other.
Is Bot Mode the same as a Hermes Telegram bot?
No. A Telegram bot is a messaging bot: an account on a platform, connected to Hermes through the gateway and identified by its bot token. A Bot Mode bot is a profile shown in the desktop roster. Setting one up does not create the other.
Where do I find Bot Mode in Hermes Desktop?
As a Bots tab next to Sessions in the left sidebar. A Routines tile docks beside the conversation while the Bots tab is active. To create a bot, use New Agent in the roster and fill in Name, Title and Description.
How do I turn Bot Mode off?
Flip the Desktop switch off for the Bots plugin under Capabilities, Plugins, Bots. The roster, Routines pane and composer middleware unregister live with no restart. Your profiles, sessions and cron jobs are untouched.
Can I use Bot Mode from the command line?
Bots are profiles, so hermes -p <bot> chat opens the same agent, routines show in hermes cron list, and hermes profile create coder creates a profile named coder, and hermes profile list lists profiles. For a short request to a bot on another machine, use hermes peer dm with the registered peer and the message.