agent-chatroom

Agent Chatroom

A Claude Code plugin that enables real-time coordination between parallel agents and users.

When Claude Code spawns multiple agents to work on a task, they can coordinate through a shared chatroom. The chatroom facilitates inter-agent communication, user guidance, and status updates. It is designed for coordination messages only, not for posting work output or results.

How It Works

flowchart TB
    subgraph User["User Request"]
        Request["Analyze auth, database, and API in parallel"]
    end

    subgraph ClaudeCode["Claude Code Runtime"]
        Task["Task Tool Invocation"]
        Hook["PreToolUse Hook<br/><i>task-pretool.js</i>"]

        subgraph AgentPool["Spawned Agents"]
            A1["Agent 1<br/>auth module"]
            A2["Agent 2<br/>database module"]
            A3["Agent 3<br/>api module"]
        end

        MCP["Chatroom MCP Server<br/><i>chatroom-mcp.js</i>"]
    end

    subgraph Infrastructure["Infrastructure Layer"]
        WS["WebSocket Server<br/><i>server.js - Port 3030</i>"]
    end

    subgraph Interface["User Interface"]
        UI["Terminal UI<br/><i>ui.js - blessed-based TUI</i>"]
        Messages["Message Stream<br/><i>Real-time agent broadcasts</i>"]
    end

    Request --> Task
    Task --> Hook

    Hook -->|"1. Check/start server<br/>2. Launch Terminal UI<br/>3. Inject chatroom instructions"| AgentPool

    A1 & A2 & A3 --> MCP
    MCP <-->|"WebSocket Connection"| WS
    WS <--> UI
    WS <--> Messages

    style User fill:#f5f5f5,stroke:#333
    style ClaudeCode fill:#fff8e1,stroke:#333
    style Infrastructure fill:#e8eaf6,stroke:#333
    style Interface fill:#e8f5e9,stroke:#333
    style Hook fill:#fff3e0,stroke:#f57c00

Component Overview

Component	File	Description
PreToolUse Hook	hooks/scripts/task-pretool.js	Intercepts Task tool calls. Checks if chatroom server is running, starts it if needed, launches the Terminal UI, and injects chatroom instructions into the agent's prompt.
Chatroom MCP Server	chatroom-mcp.js	Model Context Protocol server that exposes chatroom_join, chatroom_broadcast, chatroom_check, chatroom_ask, and chatroom_leave tools to agents.
WebSocket Server	server.js	Central message broker running on port 3030. Routes messages between all connected clients (agents and UI). Handles connection lifecycle and heartbeat monitoring.
Terminal UI	ui.js	Blessed-based terminal user interface. Displays real-time message stream, accepts user input, and sends messages to agents.
Terminal Spawner	spawn-terminal.js	Cross-platform utility to open a new terminal window. Supports macOS (Terminal, iTerm), Linux (gnome-terminal, konsole, xterm, etc.), and Windows.

Execution Flow

1. User Request - User asks Claude Code to perform a multi-agent task
2. Task Tool Called - Claude Code invokes the Task tool to spawn agents
3. Hook Intercepts - PreToolUse hook fires before each Task execution
4. Server Initialization - Hook checks port 3030; starts server and UI if not running
5. Prompt Injection - Hook appends chatroom instructions to agent prompts
6. Agent Registration - Each agent calls chatroom_join upon starting
7. Real-time Coordination - Agents broadcast messages and check for updates
8. User Interaction - User observes and sends guidance via Terminal UI
9. Graceful Shutdown - Agents detect server close and exit cleanly

Why Use This?

When working with multiple Claude Code agents:

• Agents work in isolation - They don't know what other agents are doing
• No inter-agent communication - Backend can't ask frontend about API formats
• No mid-task guidance - You can't redirect agents while they work
• Blocking questions - Agents get stuck waiting for info they can't get

Agent Chatroom solves all of this:

• Real-time coordination - Agents ask each other questions and share info
• User guidance - Send decisions and clarifications to agents while they work
• Help requests - Blocked agents can ask for help from others
• Brief status updates - Know what agents are working on

Installation

Prerequisites

• Claude Code CLI installed
• Node.js 18+

Install the Plugin

# Clone the repository
git clone https://github.com/ctb111/claude-agent-chatroom.git
cd claude-agent-chatroom

# Install dependencies
npm install

Configure Claude Code

The plugin includes hooks and MCP configuration. After cloning, register it as a Claude Code plugin:

# Register as a Claude Code plugin
claude plugins add /path/to/claude-agent-chatroom