Chatrooms

Chatrooms let multiple SwarmClaw agents collaborate inside one shared room thread.

Chatrooms vs Structured Sessions

Chatrooms are the persistent, free-form collaboration surface.

Structured Sessions are different:

  • temporary and bounded instead of persistent
  • launched from a chatroom, direct chat, task, schedule, or the Sessions page
  • driven by a reusable template and run model
  • able to create a hidden temporary live room you can watch while the run is active

If you need an open-ended room, use a chatroom. If you need a bounded run with clear outputs and completion, launch a Structured Session.

Core Capabilities

  • room membership (agentIds)
  • mention routing (@agentName, @all)
  • room execution controls (chatMode and autoAddress)
  • streamed agent replies in-room
  • reply threading and attachment-aware context
  • routing rules
  • message reactions and pinning
  • health-aware participation filtering
  • /breakout to launch a bounded Structured Session from the room

CLI-only worker runtimes cannot join chatrooms; they remain available for direct chats and delegation.

/breakout

Chatrooms support a built-in /breakout slash command for quickly spinning up a focused Structured Session from the current room.

  • type /breakout
  • or type /breakout <topic>
  • SwarmClaw opens a breakout sheet instead of posting the slash command as a room message
  • the room's current agents are auto-added as session participants
  • recent room context is copied into the kickoff field

Use /breakout when the room conversation needs a bounded run with a clear goal and outputs, but you do not want to replace the persistent room itself.

Routing Rules

Chatrooms support priority-based routing rules to direct messages to specific agents:

  • keyword match
  • capability or intent match

Rules are evaluated before autoAddress fallback. If no rule matches, mention-based or auto-address behavior applies.

Agent Muting

Individual chatroom members can be muted temporarily:

  • set mutedUntil on a member to suppress responses until that timestamp
  • muted agents are skipped during user-initiated chats and connector-routed messages

API

Room CRUD

  • GET /api/chatrooms
  • POST /api/chatrooms
  • GET /api/chatrooms/:id
  • PUT /api/chatrooms/:id
  • DELETE /api/chatrooms/:id

Collaboration

  • POST /api/chatrooms/:id/chat
  • POST /api/chatrooms/:id/members
  • DELETE /api/chatrooms/:id/members
  • POST /api/chatrooms/:id/reactions
  • POST /api/chatrooms/:id/pins
  • POST /api/chatrooms/:id/moderate

Refusal Policy

When a delegated agent declines work, the chatroom's onRefusal policy decides what happens:

  • reroute (default) — re-run routing skipping the refusing agent, pick another room member
  • escalate — bubble to the chatroom's escalationTargetAgentId, falling back to reroute if not set
  • human — surface a human_loop approval

Configure with:

POST /api/chatrooms/refusal-policy
Content-Type: application/json

{ "chatroomId": "<id>", "policy": "escalate", "escalationTargetAgentId": "<agentId>" }

Simulate a decision (useful for tests):

PUT /api/chatrooms/refusal-policy
{ "chatroomId": "<id>", "refusingAgentId": "<id>", "taskOrTopic": "...", "reason": "..." }

CLI:

swarmclaw chatroom-policy set --json '{"chatroomId":"...","policy":"escalate","escalationTargetAgentId":"..."}'
swarmclaw chatroom-policy simulate --json '{"chatroomId":"...","refusingAgentId":"...","reason":"out of scope"}'

CLI Examples

swarmclaw chatrooms list
swarmclaw chatrooms create --data '{"name":"Ops Room","agentIds":["agent-1","agent-2"],"chatMode":"parallel","autoAddress":true}'
swarmclaw chatrooms chat <chatroomId> --data '{"text":"@all status update?"}'
swarmclaw chatrooms add-member <chatroomId> --data '{"agentId":"agent-3"}'
swarmclaw chatrooms react <chatroomId> --data '{"messageId":"<messageId>","emoji":"👍"}'