Skip to main content

​
Overview

Group Chat enables multiple AI agents to collaborate on tasks through orchestrated conversations. A moderator manages turn-taking and ensures productive dialogue.
Group Chat brings together multiple agents with different capabilities to solve complex problems through conversation.

​
Creating a Group Chat

1

Open Group Chat Panel

Click the Group Chat button or press the keyboard shortcut
2

Select Participants

Choose 2 or more agents from your available sessions:
  • Agents must be in “ready” state
  • Can include agents with different providers (Claude, Codex, etc.)
  • Each agent brings unique capabilities
3

Name Your Group

Provide a descriptive name for the conversation
4

Start Chatting

Send messages and watch agents collaborate

​
Architecture

​
Participants

Each participant in a group chat is an active agent: 
interface GroupChatParticipant {
  sessionId: string          // Agent session ID
  role: 'participant'        // All participants have equal role
  joinedAt: number          // Timestamp
}

​
Moderator

The moderator orchestrates conversation flow:
  • Turn Management - Decides which agent speaks next
  • Context Awareness - Provides conversation history to each agent
  • Termination - Ends conversation when task is complete
// Moderator selection logic
const moderator = new GroupChatModerator({
  participants,
  maxTurns: 20,              // Prevent infinite loops
  temperature: 0.7           // Response creativity
})

​
Message Flow

1

User Sends Message

Message added to conversation history
2

Moderator Selects Speaker

Analyzes conversation and chooses next agent
3

Agent Responds

Selected agent receives full context and replies
4

Repeat

Process continues until task completion or max turns

​
Group Chat State

type GroupChatState = 
  | 'idle'           // Waiting for input
  | 'moderating'     // Moderator selecting next speaker
  | 'speaking'       // Agent is responding
  | 'error'         // Error occurred

​
State Indicators

⚪ Ready for user input

​
Features

​
Participant Colors

Each participant gets a consistent color for visual distinction: 
participantColors: Record<string, string>

// Example assignments
{
  "agent-1": "#3B82F6",  // Blue
  "agent-2": "#10B981",  // Green  
  "agent-3": "#F59E0B"   // Orange
}

​
Message Types

{
  type: 'user',
  content: 'How should we structure this feature?',
  images: [],
  timestamp: 1234567890
}

​
Read-Only Mode

Send messages that agents can see but don’t respond to: 
onSendMessage(content, images, readOnly: true)
Read-only messages are useful for providing context without triggering agent responses.

​
Cost Tracking

Group chats aggregate costs from all participants: 
totalCost: number              // Sum of all participant costs
costIncomplete: boolean        // True if any agent lacks cost data
Costs appear in the header with an incomplete indicator if not all agents support cost tracking.

​
Input Panel

The input panel supports:
  • Text input with multi-line support
  • Image attachments via paste or drag-and-drop
  • Staged images preview before sending
  • Read-only toggle for context messages
  • Execution queue indicator when messages are queued
interface GroupChatInputProps {
  onSend: (content: string, images?: string[], readOnly?: boolean) => void
  stagedImages?: string[]
  setStagedImages?: (images: string[]) => void
  readOnlyMode?: boolean
  setReadOnlyMode?: (value: boolean) => void
  executionQueue?: QueuedItem[]
}

​
Message Queue Integration

Group chat integrates with the execution queue:
  • Messages queue when moderator/agents are busy
  • Visual indicator shows queue count
  • Drag-and-drop reordering support
  • Per-agent queue isolation prevents conflicts
If multiple group chats target the same agent, messages will queue sequentially to prevent file conflicts.

​
Keyboard Shortcuts

ShortcutAction
EnterSend message (if Enter-to-send enabled)
Shift+EnterNew line in message
Cmd+EToggle markdown edit mode
Cmd+VPaste images

​
Use Cases

​
Code Review

Participants:
- Claude (architecture analysis)
- Codex (code quality)
- OpenCode (security review)

User: "Review this authentication implementation"
[Paste code]

Each agent provides expertise-specific feedback

​
Documentation

Participants:
- Doc Writer (content creation)
- Tech Reviewer (accuracy)
- Editor (style & clarity)

Iterative refinement through conversation

​
Problem Solving

Participants:
- Research Agent (gather information)
- Analysis Agent (evaluate options)
- Decision Agent (recommend solution)

Structured problem-solving workflow

​
Performance Considerations

Group chats create multiple concurrent agent sessions: 
// Each agent maintains its own context
const contextPerAgent = messages.map(m => ({
  role: m.type === 'user' ? 'user' : 'assistant',
  content: m.content
}))

// Moderator sees full conversation
const moderatorContext = fullConversationHistory
Token usage and costs multiply with participant count. Use focused groups for efficiency.

​
SSH Remote Support

Group chat works with SSH remote agents:
  • Remote agents spawn on remote host
  • Local coordination by moderator
  • Mixed local/remote participants supported

Build docs developers (and LLMs) love

Get started for freeTalk to us