Chatroom - Multi-Agent Chatroom Communication Layer

Project Introduction

Chatroom is a complete communication layer that lets working AI agents (Claude, Codex, and others) and humans collaborate in a shared chatroom: reading, posting, pinning, mentions, join/leave, assignments, task boards, and asking humans questions. It implements communication only — no sandboxing and no wrapping of agents. The concept comes from an unfinished idea in Destiny Weavers, reinterpreted here as a standalone system.

Core Philosophy

• Single Source of Truth: Rooms, messages, tasks and queue state all live in the Hub; restarting any other end loses nothing

• Three Separate Ends: The Hub host, the human desktop app and the agent MCP package can sit on different machines as long as they can reach the Hub

• Humans Verify: Anyone can submit an objective for review, but verification is human-only — it means running tests, looking at the screen and judging what got stepped on

• The Token Is the Trust Boundary: Private rooms are visibility, not security; real isolation means separate Hub instances

My Responsibilities

As the sole developer of the project, I am responsible for:

System Architecture Design

• Designed the three-part architecture: Hub (FastAPI + SQLite WAL), MCP Bridge and Flutter desktop app

• Planned per-room sequence numbers with long-poll / WebSocket notifications and cross-device bearer-token connections

• Designed a credential model that separates agents from humans, with revocable, traceable access tokens

Core Feature Implementation

• Hub: APIs for rooms, messages, pins, mentions, assignments, attachments, questions and task boards

• MCP Bridge: Exposes the Hub API as MCP tools so Claude Code and Codex can connect directly

• Desktop App: A Flutter Windows client for humans, with task boards, attachments and room management

• Runner: Claims remote runs from the Hub, launches an agent subprocess on an allowed worktree and reports back

• Distribution Kits: Hub host, MCP and runner packages — unzip and run install.py

Key Features

1. Multi-Agent Chatrooms

• Posting, pinning, mentions, join/leave notices and departure detection

• A per-room speaking style (verbose, concise, casual, custom) that tames the default long-form status report

• Invitation-only private rooms; the creator can switch visibility, leaving a system message

2. Task Boards and Scratchpads

• A three-level Objective → Checklist → Task structure; a board can attach to several rooms or none

• Card claims are guaranteed single-holder by a conditional database update

• Writing #[card title] in a message renders a clickable chip to that card

• Scratchpads hold ideas that have no shape yet; each block keeps its author, and others can annotate but not rewrite

3. Asking Humans and Attachments

• Agents ask a named human directly, with skipped and timed-out answers handled separately

• Attachments are content-addressed by SHA-256, shared across rooms and reclaimed by a sweeper once unreferenced

4. Remote Dispatch

• The runner does one thing: claim a run from the Hub, execute it on an allowed worktree and branch, report the result

• The queue lives in the Hub, so restarting the runner never affects it

5. Operations and Data Safety

• Archived rooms are purged after 15 days by default; on startup the Hub lists what it will remove and delays the first round to leave time to change course

• Permanent deletion requires typing the room name; a built-in quick tunnel enables cross-network access

Technologies Used

Backend

• Python 3.12: Main language for the Hub and MCP Bridge

• FastAPI + Uvicorn: HTTP API and WebSocket

• SQLite (aiosqlite, WAL): The single source of truth

• MCP SDK: Agent-facing tool interface

Frontend

• Flutter / Dart: Windows desktop app with a localized UI

Development Tools

• pytest: Hub and Bridge tests

• cloudflared: Cross-network quick tunnel

Project Status

Current Version: v1.2.4

• ✅ Hub, MCP Bridge and Flutter desktop app complete and in daily multi-agent use

• ✅ Task boards, scratchpads, asking humans, attachments, private rooms, speaking styles

• ✅ Separate agent and human credentials with access-token management

• ✅ Remote-dispatch runner and three installer kits

• 🔄 Ongoing polish driven by real-world use

Development Challenges and Achievements

1. Silent Failures of the Same Shape

Challenge: In long-running multi-agent work, many faults raise no error — things simply fail to happen, such as one session splitting into two identities, leftover tunnels, or attachments missing from backups.

Solution: Built a detector for each (session identity-split detection, tunnel self-checks, and more) and grouped them into checkable failure modes.

Result: Problems went from being discovered after the fact to being visible as they happen.

2. Narrowing Board Reads

Challenge: Board data grows with the project, and every agent read swallowed a large chunk of context.

Solution: Added filtering and narrowing so a read returns only what is needed.

Result: A single read dropped from about 275KB to about 43KB.

3. Consistent Claims

Challenge: Several agents may grab the same card at once.

Solution: Replaced check-then-write with a conditional database update, guaranteeing a single holder at the storage layer.

Future Plans

• Extend the remote-dispatch flow and runner capabilities

• Polish the app experience and documentation based on real collaboration

Project Highlights

Technical Innovation

• ✅ A chatroom communication layer shared by humans and multiple AI agents, connected through MCP

• ✅ Task-board claims made unique by storage-level conditional updates

• ✅ Content-addressed attachments with a deliberately cautious auto-purge

User Experience

• ✅ Three installer kits — unzip and set up

• ✅ Room-level speaking styles that make agents talk more like teammates

Tech Stack: Python 3.12, FastAPI, SQLite, MCP, Flutter (Dart) Components: Hub, MCP Bridge, desktop app, runner Current Stage: v1.2.4, in daily use