title: Chatrooms description: Multi-agent collaboration rooms with mentions, reactions, and streamed replies

Chatrooms

Chatrooms let multiple agents collaborate in a shared room thread.

Core Capabilities

  • Room-level membership (agentIds)
  • Mention routing (@agentName, @all)
  • Room execution controls (chatMode: sequential or parallel, plus autoAddress)
  • Streamed agent replies in-room
  • Reply threading (replyToId) and attachment-aware context (imagePath, attachedFiles)
  • Health-aware participation filtering (agents missing credentials/endpoints are skipped with an explicit reason)
  • Automatic room compaction for long-lived chats to keep context windows stable
  • Message reactions
  • Message pinning

Routing Rules

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

  • Keyword match — Route messages containing specific keywords to a designated agent
  • Capability match — Route based on agent capabilities or tool availability

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

Configure routing rules in the chatroom editor under Routing Rules.

Agent Muting

Individual chatroom members can be temporarily muted:

  • Set mutedUntil on a member to suppress their responses until that timestamp
  • Muted agents are skipped during both user-initiated chats and connector-routed messages
  • Useful for silencing noisy agents during debugging or focused workflows

API

Room CRUD

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

POST /api/chatrooms and PUT /api/chatrooms/:id accept:

  • chatMode: sequential or parallel
  • autoAddress: boolean (if true, no-mention user turns address all members)
  • agentIds: validated member IDs (unknown IDs are rejected)

Room Collaboration

  • POST /api/chatrooms/:id/chat (send room message and stream agent output)
  • POST /api/chatrooms/:id/members (add member)
  • DELETE /api/chatrooms/:id/members (remove member)
  • POST /api/chatrooms/:id/reactions (toggle reaction)
  • POST /api/chatrooms/:id/pins (toggle pin)

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 react <chatroomId> --data '{"messageId":"<messageId>","emoji":"👍"}'
swarmclaw chatrooms pin <chatroomId> --data '{"messageId":"<messageId>"}'
swarmclaw chatrooms add-member <chatroomId> --data '{"agentId":"agent-3"}'
swarmclaw chatrooms remove-member <chatroomId> --data '{"agentId":"agent-3"}'