Bot Mode

​

Coming from profiles?

​

The Bots pane

• 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. A row click always opens that Bot Chat (the same conversation the row previews), even when you have other tabs open for the Bot; those tabs stay open beside it. In the tab strip the Bot Chat is captioned with the Bot’s name, so two open Bots are told apart at a glance.
• Right-click a Bot → Open recent session to jump to its most recently active ordinary conversation — a cron run, a delegated job, a side thread — as a tab beside the Bot Chat. The row click itself never changes; a Bot with no other conversation yet just opens its Bot Chat.
• Active now — the roster’s activity filter includes the owner of the focused live turn, Bots that wrote within the last 90 seconds, and Bots with a recent worker heartbeat. A connected gateway alone does not mean a Bot is working.
• 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.

​

Organize bots into sections

• Create one from the pane’s + menu → New section, or right-click a Bot → Move to section → New section… (that files the Bot into it as you create it).
• File a Bot by dragging its row onto a section — the target highlights while you hover, and Esc cancels the drag — or right-click → Move to section and pick one. Remove from section puts it back in Unassigned.
• Rename, reorder, or delete a section from its heading’s right-click menu (or the ⋯ that appears on hover); double-click a heading to rename. Headings fold like the gateway headings do.
• Deleting a section never deletes Bots — they return to Unassigned, and the toast offers Undo. No confirmation is asked.

​

Creating a Bot

• 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 Mibyan knows about works, and different Bots can run on different models side by side. Leave it unset to inherit from the launch profile. Picking a model from the Bot Chat’s composer sticks to that chat (it survives reopening the app) until you change the Bot’s profile model, which takes over again.
• 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.
• Copy API keys from the main profile — on by default. Each Bot gets its own credential store: static API keys are copied in, while single-use OAuth logins (Anthropic, OpenAI Codex, xAI) are not copied — sign the Bot in itself with mibyan -p <name> auth add <provider>. See Every profile owns its credentials.

​

Choosing which machine it lives on (“Create on”)

• 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 pins to the target machine’s backend, so skills, tools, and MCP servers you configure during creation land on the machine the Bot will live on. (Older desktop builds fall back to staged Skills/Tools/MCP checklists for remote targets; both read the target machine’s catalog.)
• Cancelling the dialog discards the draft profile on whichever machine it was created.

​

Avatars

• Blob faces (default) — a deterministic soft-body face drawn from the Bot’s name: same name, same face, forever. While you type a name in New Agent the face follows it live; hit Randomize to re-roll, Lock face to keep the one you like even if the name changes, or pin one of the six silhouettes (round, organic, boxy, nub, cloud, sun) while everything else still comes from the name.
• Geometric faces — the classic 7 shapes × 10 colors. During a focused live turn, the owning Bot leans and looks upward with three animated dots, then eases back to idle when the turn ends. Ownership includes the connection, so same-named Bots on different gateways do not borrow the pose. Background workers keep their existing working animation; photos, blob faces and sigils keep their own rendering.
• 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 mibyan pets in a terminal to explore the gallery.

​

Voices

​

Routines

​

Groups and group chats

• New Group Chat lets you set an optional room picture alongside the name — upload one from your device or generate one (when an image backend is configured), using the same pipeline as Bot avatars. The picture appears in the roster row (in place of the default group glyph) and leads the title in the room header.
• The room header’s gear button opens Group settings, where you can rename the group or set, replace, or remove its picture any time. A rename carries everything with it — the room log, each member’s room session, memberships, and the picture — so no history is lost. Renaming to a name that’s already taken is rejected rather than silently suffixed.
• Group settings also lists every member with a Compress history button. Each member keeps a hidden per-room session that grows with every turn; when it gets large enough the member starts answering with empty replies (The model returned no response after processing tool results). Compress history runs the same context compression as /compress against that hidden session — it is not reachable from the sidebar or the room composer — and reports how many messages were folded. Compress one member at a time; the room log itself is untouched.

• One visible conversation. Public messages and each member’s reply stay readable in arrival order, with the speaker’s name and timestamp. Starting another topic does not collapse earlier replies. Reply in thread continues that topic without reordering the room; Activity is a secondary status view, not a replacement for messages. Private Bot Chats remain separate.
• 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.
• Teammates can hand off to the primary Bot with @mibyan, including in older saved rooms; Bots on other gateways keep their device-qualified tags (for example, @default-vera).
• 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. Pending questions and command approvals also light that badge; resolving the last prompt clears only prompt attention, not an independent mention. A command approval in the room answers on the click itself — once, session, always or deny sends at once, with no second button to find. Prompts follow a renamed room, while disbanding retires them even if a member’s in-flight poll arrives later.
• Hard caps (10 messages per send, 3 rounds) keep rooms from spinning.
• Each member keeps its own persistent room 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 keep running when you close the Desktop. When every member of a room lives on the same gateway, that gateway owns turn scheduling through a durable driver: closing Mibyan Desktop (or losing its connection) does not stop a room mid-discussion, and the Desktop simply catches up from the room’s log when it reconnects. groups.capabilities on the gateway reports driver: true when this applies. More than one room worker may share a home — the messaging gateway (mibyan gateway run) and the Desktop’s own backend (mibyan serve) both run one — and whichever holds the room’s driver lease runs the next turn; a member’s room session is held only for the duration of its turn, so the lease can move between workers without a turn being refused. Room state lives in the install’s root shared-state.db; installs that created rooms before that file existed (when rooms were still kept in the root state.db) get those rooms copied across once, on the first open after updating, so pre-existing Group Chats stay reachable. Rooms whose members span several machines are different: each member’s turns run on its own gateway, and the cross-connection courier described under Bot-to-bot messaging still applies to them.
• Mentions read as identities. In the transcript a routed @bot mention, the human handoff @user, and the broadcasts @everyone / @all render as inline references (accent text, not pills); unknown @words and e-mail addresses stay plain. Hover a Bot’s message and use Reply to @handle to seed @handle into the composer, so your next send goes to that Bot only (when a same-named Bot from a Connection shares the room, the tag is device-qualified, e.g. @reviewer-mini / @reviewer-local) — Reply in thread still continues the whole thread. If a reply box for a different thread is open, Reply to seeds the main composer instead and so starts a fresh thread; use Reply in thread to continue that thread.
• Rooms can span machines. New Group Chat is available as soon as two Bots are selectable across all your registered connections — one Bot on this device plus one on another gateway is enough. The picker seats Bots from any registered connection; each member’s turns run on its own machine, in its own room 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. A member’s turn that outlives this Desktop — you quit or it crashed mid-turn — finishes on the member’s own machine: the room posts that reply the next time it is driven, and does not re-drive the member while it is still working.
• Rooms show the same identity as the roster. Transcript rows, the “X is thinking…” line and Activity rows resolve each member’s title and avatar by its owning connection and profile — re-titling a Bot or changing its picture updates every room it sits in, remote members keep their own titles, and two same-named Bots on different connections never borrow each other’s avatar. When two members would still read identically, Activity appends the connection label (Reviewer · Mac Mini).
• Plugins can watch members work. The durable room log records turn.started and turn.settled; what a member does in between (tools, approvals, streamed text) is projected to plugins through the on_room_member_activity hook with room, member and turn coordinates, so community clients can build tool cards and live member status on top of Group Chat without reading Mibyan internals.
• What a member says outside the room still reaches it. Each member’s room session is an ordinary Mibyan session (titled Group: <room> · <thread>), so you can resume it from the CLI, a routine can post into it, or the Bot’s own tools can write to it. When you open the room, and again each time the room drives that member, whatever those writers added since the room last looked — your questions and the member’s answers — is posted into the room log under that member’s name, once, in the thread the session belongs to; a window restart does not repeat it. The room’s own turn prompts and their replies are never duplicated this way, and neither are the agent’s housekeeping rows (context compaction notes, routine deliveries, delegation results) or the member’s reactions to them. The room starts watching a session the first time it sees it: what was already in that session by then is not replayed, so a room restored on a second Desktop does not re-post its members’ history.

​

Bot-to-bot messaging

• @mentions — type @researcher have a look at this in any chat and the composer’s @ autocomplete helps you pick the right Bot; on send, the mention is resolved against the live roster and the active Bot is told exactly who you mean (profile, friendly name, and device for cross-connection Bots). The Bot then composes its own message and sends it with message_agent — your text is never forwarded verbatim, and the reply comes back attributed to that agent. An email address or an unknown @ passes through untouched. Bots on other connected machines are reachable the same way: the Desktop relays the message over that connection’s own socket (see Bots across machines below).
• Renamed Bots keep their tags in sync — give a Bot a friendly name (the pencil in its chat header, or mibyan profile rename) and it becomes taggable by that name: a Bot titled Research Buddy answers to @research-buddy (and @researchbuddy), in regular chats and in group rooms alike. The composer’s @ autocomplete offers the renamed tag and also matches when you type the old profile name, which keeps resolving too. This includes the primary Bot: rename it Maia and group-turn prompts introduce it as @maia, its inter-agent messages sign as Message from 🤖 Maia (@mibyan), and teammates can message_agent(target="maia") it — @mibyan stays a working alias.
• Remote Bots complete under their titles, from any chat. The @ autocomplete lists Bots on your other connected machines as soon as the Desktop is connected — you do not have to open the Bots pane first — and a remote default appears under its Bot Mode title (@cos-bot for a remote default titled CoS Bot, not a second @mibyan). When two Bots would tag alike, the picker inserts the connection-qualified form (@cos-bot@<connection>), which resolves to exactly that machine’s Bot. A relayed message signed Message from 🤖 mibyan (@mibyan@<connection>) still renders as an agent notice, not as your own text.
• Direct messages — every Bot Chat carries the message_agent tool: a Bot messages a teammate by calling message_agent(target="researcher", message="…"). The target is the teammate’s profile name, its friendly name (mibyan profile rename or the Bot Mode title — Scribe, Dr. Foo) or the @-tag the Desktop inserts for it (@scribe, @dr-foo, @drfoo); @mibyan always means the primary Bot. A profile name is matched first, so it can never be hijacked by another Bot’s friendly name, and a friendly name shared by two Bots is refused with the roster instead of guessing. The tool validates the target against the live roster, prefixes the sender’s Message from 🤖 <friendly name> (@<handle>): attribution automatically, and delivers into the teammate’s canonical Bot Chat. Delivery is fire-and-forget: the sender gets a dispatch acknowledgement (status: queued plus a delivery_id — and a process_id for the background delivery process — means the message was handed to that process, not that it was delivered), finishes its turn, and that process’s completion notification carries the outcome — the reply, or the delivery failure. On surfaces that cannot receive completion notifications (an api_server session, one-shot runners) the acknowledgement instead carries reply_delivery: poll: the sender retrieves the outcome with process(action="wait", session_id=…) before ending its turn, and the outcome is also saved into the sender’s session transcript as a delivery row when the process exits, so the reply is never silently lost. The notification carries the reply whole up to the message size limit (16,000 characters); a longer one arrives as its tail and says how much was cut (process(action="log", session_id=…) has the rest). The message travels as a real parameter (nothing shell-interpreted — quotes, $(...), and backticks arrive verbatim), and the Bot composes its own message rather than forwarding your words. The teammate roster — names and roles from each profile’s title/description — is part of every Bot Chat’s system prompt, so Bots know who does what before choosing a recipient. The tool exists only in canonical Bot Chat sessions on Bot-Mode-managed installs; regular chats, group-room member sessions, and CLI sessions never see it.

• Staying silent — a Bot that has nothing to add may end a turn with one of the intentional silence tokens ([SILENT], NO_REPLY, …). The Bot Chat keeps that turn in its transcript but renders nothing, and a teammate that messaged it gets an empty reply instead of the token. Failed turns and prose that merely mentions a token are shown as-is.

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

​

What actually makes a chat a Bot Chat

1. The session is titled exactly Bot Chat. That exact title is the canonical chat’s identity (it is what the desktop plugin’s createCanonicalChat uses and what mibyan -p <bot> chat -c "Bot Chat" resumes); any other title, or an untitled scratch session, gets neither the section nor the tool.
2. At least one profile on the install carries a ui_meta: { mibyan-bots: … } block in its profile.yaml. This is the “Bot-Mode-managed” marker the desktop plugin writes for every Bot it owns; the gate scans every profile, so one marked profile marks the whole install. There is no CLI command that writes it.

# the canonical forever-chat, created once per Bot (later runs resume it)
mibyan -p <bot> chat -c "Bot Chat" --create-if-missing

# ~/.mibyan/profiles/<any-bot>/profile.yaml — an empty block is enough to mark the install
ui_meta:
  mibyan-bots: {}

​

Failed turns retry safely

​

When a delivery fails: typed reasons

​

Messaging across connected machines (the Desktop relay)

• Rosters propagate on their own. While the Desktop runs, it periodically tells each connected gateway which agents live on the other connections. Every Bot Chat’s teammate roster then lists them (“Teammates on OTHER connected machines”), with names, roles, and which machine they’re on — and the roster refreshes when agents appear, disappear, or get renamed (capability epoch).
• message_agent reaches them directly. A Bot on your laptop messages the cloud agent with message_agent(target="moxie", …) exactly like a local teammate. If the same handle exists on several machines, disambiguate with target="moxie@<connection>" (the tool’s error tells the Bot the exact forms). Each teammate is listed by the machine’s name from Settings → Connections, so a Bot reads @moxie on Homelab rather than a bare connection id. Delivery rides the Desktop: the sending gateway queues the message, the Desktop relays it to the target connection’s own gateway, the target Bot runs a turn in its canonical Bot Chat — as that chat’s next turn when it is open in a Desktop — and the reply comes back to the sender as the same background completion notification local DMs use (the process that waits for it is a Mibyan entrypoint, so it starts under approvals.single_query_mode: deny — the default for a Bot’s one-shot reply turn — too; an open chat that has not answered within the live-delivery budget reports the message queued there instead; do not resend). Messages to different Bots are delivered side by side, so one Bot’s long turn never delays another Bot’s mail (or ages it past bot_mode.envelope_ttl_seconds); messages to the same Bot are delivered in order, one turn at a time.
• The Desktop is the courier. Cross-connection delivery works while a Desktop that knows both connections is running (it holds the sockets and the credentials — gateways never see each other’s auth). If the Desktop is closed mid-delivery, the sender’s Bot is told the reply didn’t arrive rather than left hanging; a message the Desktop picked up but never handed to the target (it disconnected in between) is offered to the next drain again — once, and only after the Desktop’s own delivery deadline (~26 minutes) has passed with no reply, so a slow-but-live turn is never delivered twice. The sender keeps waiting long enough for that second delivery to finish (~52 minutes in all); if it still gets no reply, the sender is told so with reason delivery_timeout. While a re-offered message waits for a drain, bot_mode.envelope_ttl_seconds applies to it exactly as to a freshly queued one, and the first reply recorded for a message is the one that stands. For always-on machine-to-machine messaging with no Desktop in the loop, register a peer (mibyan peer, below) — the two routes coexist.
• A remote default goes by its title. Every machine’s default is @mibyan, so a remote one is offered — and reachable — under its Bot Mode title instead (a remote default titled CoS Bot is @cos-bot; with no title, mibyan@<connection>), and a DM it sends arrives signed with that same reply-safe form rather than a bare @mibyan that would point back at your own default.
• The 10-minute cap bounds the target’s turn, not its handoffs. A relayed message gives the target Bot 10 minutes to finish its turn. When that turn messages a teammate itself, the delivery process stays alive afterwards — bounded by terminal.oneshot_completion_wait_seconds — so the teammate’s reply can land in its Bot Chat (and, when it arrives in time, becomes the answer relayed back). That wait is never counted against the cap: a turn that finished is reported to the sender with its answer, not as delivery_timeout, and its handoff is left to complete.

​

Bot-initiated DMs across machines (mibyan peer)

mibyan peer add spark --url http://spark.lan:8377 --key <API_SERVER_KEY>
mibyan peer list
mibyan peer dm spark < ~/.mibyan/cache/scratch/dm.txt        # message body from a file (nothing shell-interpreted)
mibyan peer dm spark/researcher < ~/.mibyan/cache/scratch/dm.txt   # named profile on a multiplexed peer
mibyan peer run spark --idempotency-key ticket-123 < ~/.mibyan/cache/scratch/long-task.txt
mibyan peer status spark run_abc123
mibyan peer stop spark run_abc123

​

Transferring hosted room authority

1. Check replica coverage. On the replacement gateway, inspect groups.replica_state with {"room_id":"ROOM_ID"} and compare last_seq with latest_seq. Require a complete replica before planned takeover; promotion itself does not check this coverage. groups.replicate reports caught_up after ingesting pages returned by groups.log; peer registration alone does not prove the replacement has the room history. Caught-up status describes the last replicated page, not proof the old writer has stopped or that no newer events exist. For a planned move, quiesce writers, replicate through the final cursor, then maintain the fence. For disaster recovery, account for any history that never reached the replica.
2. Promote only while the old writer is fenced. On the replacement:
   {"jsonrpc":"2.0","id":1,"method":"groups.promote","params":{"room_id":"ROOM_ID","confirm":true,"reason":"planned-handover"}}
   
   room_id and confirm: true are required; reason is optional and defaults to authority-unreachable. Confirmation is your assertion that the previous authority cannot commit, not a request to fence it automatically. Without confirmation the call returns error 4118. A successful result reports authority_gateway_id and authority_epoch (the replicated epoch plus one).
3. Demote the old authority before returning it to service. Keep its normal room writers fenced while applying this RPC through a controlled recovery connection on the old gateway. Replace the example gateway ID and epoch with the exact values returned by the successful promotion:
   {"jsonrpc":"2.0","id":2,"method":"groups.demote","params":{"room_id":"ROOM_ID","observed_gateway_id":"NEW_GATEWAY_ID","observed_epoch":2}}
   
   All three parameters are required. Do not guess a future epoch: demotion requires evidence of a newer authority, not an invented value. It records authority.lost and adopts the observed lineage; repeating the same lineage is idempotent. If the old host is unavailable, keep it fenced and perform this step before restoring its normal writers.
4. Verify and reconnect. Read groups.state on both gateways and compare room.authority_gateway_id and room.authority_epoch with the promotion result. Old-authority sends must be refused; direct clients to the replacement. Demotion fences writes; it does not merge histories or automatically turn the old authoritative store into a synchronized replica.

​

Bots across machines

​

Warm Bot Backends (how many bots run at once)

​

Turning it off

​

CLI parity