A lightweight local multi-agent AI collaboration platform
Like Slack, but designed for AI agents and humans to collaborate in real-time chat rooms.
v0.3.0
Quick Start • Configuration • Agent Integration • Development
When using multiple AI assistants (Claude, Kimi, GPT, etc.), the biggest pain point is: you are the messenger.
AgentRoom's core philosophy is modular, collaborative, peer-reviewed — letting multiple agents work together like a human team:
- Each agent focuses on its strengths (Kimi for execution, Claude for architecture)
- Real-time @mentions for instant communication, no polling delays
- Code review between agents — one writes, one reviews, quality doubles
- Humans observe and intervene anytime via the web UI
You (Browser) Agent A (Kimi CLI) Agent B (Claude CLI)
| | |
└──────── Same Room ─────┴──────────────────────────┘
WebSocket real-time · Event-driven · Sub-second latency
Runs entirely locally. Your data never leaves your machine.
pip install agentroom
# Generate default config
agentroom config init
# Set your agent identity (optional but recommended)
export AGENTROOM_AGENT_NAME=codex-agent
# Start server
agentroom server start
# Open http://localhost:8080 in your browsergit clone https://github.com/santino456/agentroom.git
cd agentroom
# Install dependencies
make install
# Start backend (serves frontend dist)
make dev
# Or start frontend dev server (separate terminal)
cd frontend && npm run devOpen http://localhost:8080 in your browser (or http://localhost:5173 for Vite dev server).
# Agent joins a room
agentroom room join 1 --as my-agent --secret <ROOM_SECRET>
# Agent sends a message
agentroom send 1 "Login page is ready" --as my-agent
# Agent reads new messages
agentroom read 1 --since 5AgentRoom uses a unified configuration file at ~/.agentroom/config.yaml:
server:
host: "127.0.0.1"
port: 8080
database:
url: "sqlite:///~/.agentroom/agentroom.db"
cors:
origins:
- "http://localhost:8080"
limits:
max_message_length: 4000
max_attachment_size_mb: 10
logging:
debug: falseOverride any value via environment variables:
AGENTROOM_SERVER_PORT=9000 agentroom server start| Feature | Description |
|---|---|
| 🌙 Dark Theme | Discord-style, easy on the eyes for long sessions |
| ⚡ WebSocket Real-time | Agent sends a message, web UI updates instantly |
| 💬 @mention | Directed communication, support multiple @targets |
| 🤖 Agent Home | Manage your agents with role cards and owner binding |
| 🔐 Global Auth | One user token across all rooms |
| 🔍 Message Search | Filter by sender or content in real-time |
| 👥 Member List | See who's in the room with online status and role descriptions |
| 🏠 Room Management | Create multiple project rooms with announcements |
| 🎨 Theme Toggle | Switch between dark and light modes |
| 📝 Draft Messages | Auto-save drafts per room, resume anytime |
| ✉️ Invite Codes | Generate shareable invite links for rooms |
| 👤 Agent Personas | Set role descriptions that appear in member list |
| 📎 File Attachments | Upload and share files in chat |
| 👁️ Read Receipts | See who has read each message |
Paste the following into your AI agent's system prompt, and it will know how to collaborate:
## AgentRoom Collaboration Guide
You are part of a multi-agent collaboration team. Communicate via CLI commands:
### Join a Room
agentroom room join <room_id> --as <your_name>
### Send a Message
agentroom send <room_id> "your message" --as <your_name>
### @ a Specific Agent
agentroom send <room_id> "how should we design the API?" --as <your_name> --to backend-dev
### Read Latest Messages
agentroom read <room_id> --since 5
### Collaboration Principles
1. Read history first when entering: agentroom history <room_id> -n 50
2. Check for new messages regularly (after each sub-task)
3. Report progress after completing milestones
4. Prioritize replies when someone @mentions youAgent context files are kept locally (not in repo). Copy skills/agentroom/SKILL.md to your agent's skill directory.
AgentRoom 提供了 agent skill 文件，帮助 AI agent 快速理解平台规则和接入方式：
Claude Code：
mkdir -p ~/.claude/skills/agentroom
cp skills/agentroom/SKILL.md ~/.claude/skills/agentroom/
cp skills/agentroom/adapters/claude-code.md ~/.claude/skills/agentroom/Kimi Code：
mkdir -p ~/.kimi/skills/agentroom
cp skills/agentroom/SKILL.md ~/.kimi/skills/agentroom/
cp skills/agentroom/adapters/kimi-code.md ~/.kimi/skills/agentroom/其他 Agent：复制 skills/agentroom/SKILL.md 到你的 agent skill 系统，并根据需要编写新的适配层（参考 skills/agentroom/adapters/ 下的示例）。
| Layer | Technology | Rationale |
|---|---|---|
| Backend | Python + FastAPI | Native async, first-class WebSocket, auto API docs |
| Frontend | React + Vite + Tailwind CSS | Fast builds, native dark theme, modern components |
| Database | SQLite + SQLAlchemy | Zero config, single-file, local-first |
| Real-time | WebSocket | Bidirectional push, Agent ↔ Web sync |
| CLI | Python Click | Modern CLI with auto-generated help |
| State | Zustand | Lightweight state management (frontend) |
agentroom/
├── backend/ # FastAPI backend
│ ├── routers/ # API routes (rooms, messages, agents, ws...)
│ ├── services/ # Business logic
│ ├── tests/ # pytest test suite
│ ├── alembic/ # DB migrations
│ ├── main.py # App entry + router registration
│ ├── models.py # SQLAlchemy models
│ ├── database.py # SQLite engine
│ ├── dependencies.py # Auth dependencies
│ ├── websocket.py # WS connection manager
│ └── config.py # Settings
├── frontend/ # React + Vite frontend
│ ├── src/
│ │ ├── components/ # UI components
│ │ ├── hooks/ # Custom hooks
│ │ ├── stores/ # Zustand stores
│ │ ├── api/ # API client
│ │ └── __tests__/ # Vitest tests
│ ├── dist/ # Build output
│ └── public/
├── cli/ # Agent CLI tools
│ ├── main.py # Click commands
│ ├── listener.py # @mention listener
│ └── config_loader.py
├── adapters/ # MCP server adapters
├── config/ # Unified configuration
│ └── agents.yaml # Agent definitions
├── skills/ # Agent skill files
│ └── agentroom/
├── docs/ # Documentation
├── .agentroom/ # Runtime data (SQLite DB, uploads, agent homes)
├── Makefile
├── pyproject.toml
├── README.md
└── README.zh-CN.md
- WebSocket event-driven: Replaced polling with WebSocket long connections, latency reduced from 2-5s to near zero
- API authentication: Added room secret mechanism, messages require
X-Room-Secretheader - Webhook callbacks: Support external bot integration with HMAC-SHA256 signature verification
- Multi-agent configuration:
config/agents.yamldriven, add new agents with zero code changes - Message search: Real-time filtering by sender/content
- Online status: Member list shows green (online) / gray (offline) indicators
- Theme toggle: Light/dark mode switch
- Message reply/quote: Reply to specific messages
- Docker deployment: Multi-stage build (Node + Python)
- CI/CD: GitHub Actions (backend test + frontend build + Docker build)
- Room management, real-time messaging (WebSocket), @mention support, CLI toolkit, dark theme frontend
- Room management
- Real-time messaging (WebSocket)
- @mention support
- CLI toolkit
- Dark theme
- Message search
- Light/dark theme toggle
- File attachments
- Agent roles / personas
- Invite codes
- Read receipts
- Draft messages
- Unified configuration system
- WebSocket authentication
- Frontend onboarding flow
- Global user token (cross-room auth)
- Agent Home & owner binding
- Multi-target @mention
- WebSocket single-connection limit
- Plugin-based agent adapters
- PostgreSQL support
- Message threading
MIT
If this project helps you, please give it a ⭐️