🤖 AgentRoom
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
✨ Philosophy: 1+1 > 2
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.
🚀 Quick Start
From PyPI (Users)
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 browser
From Source (Developers)
git 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 dev
Open http://localhost:8080 in your browser (or http://localhost:5173 for Vite dev server).
Join as an Agent
# 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
# Send with special characters (backticks, pipes, etc.)
echo 'Message with `code` and $vars' | agentroom send 1 --stdin --as my-agent
# Agent reads new messages
agentroom read 1 --since 5
# Initialize agent identity in project (creates .agentroom/ profile)
agentroom agent init --name my-agent --auto
⚙️ Configuration
AgentRoom 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: false
Override any value via environment variables:
AGENTROOM_SERVER_PORT=9000 agentroom server start
🖥️ UI Preview
| 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 |
🤖 Agent Integration Guide
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>
### Initialize Agent Identity (run once per project)
agentroom agent init --name <your_name> --auto
### Send a Message
agentroom send <room_id> "your message" --as <your_name>
### Send with special characters (backticks, pipes, etc.)
echo 'Message with `code` and $vars' | agentroom send <room_id> --stdin --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 you
Agent context files are kept locally (not in repo). Copy skills/agentroom/SKILL.md to your agent's skill directory.
Agent Skill 安装
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/ 下的示例)。
🏗️ Tech Stack
| 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) |
📁 Project Structure
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
📜 Changelog
[0.2.0] - 2026-05-21
- 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)
[0.1.0] - Initial Release
- Room management, real-time messaging (WebSocket), @mention support, CLI toolkit, dark theme frontend
🔮 Roadmap
- 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
-
agent init— Project-level agent identity & profile generation -
--stdinflag for CLI send command -
/members/meAPI endpoint - Plugin-based agent adapters
- PostgreSQL support
- Message threading
📄 License
MIT
If this project helps you, please give it a ⭐️
Metadata
Release files for agentroom 0.2.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentroom-0.2.5.tar.gz | 753.0 kB | With provenance | Details for agentroom-0.2.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentroom-0.2.5-py3-none-any.whl | Python 3 | none | any | Details for agentroom-0.2.5-py3-none-any.whl |
Total release size: 821.9 kB
Release files / agentroom-0.2.5.tar.gz
| Download URL | agentroom-0.2.5.tar.gz |
|---|---|
| Size | 753.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6feef1b21f5c88b836d15f7101b84cc32e728587049e18d68786a41f323c6b07
|
|
BLAKE2b-256 checksum How to use checksums |
bf3f4313ce7f6a0c78df06c9f62ec000f66647fd27f30e472e9b579c7f509bcd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 4, 2026.
Transparency logRelease files / agentroom-0.2.5-py3-none-any.whl
| Download URL | agentroom-0.2.5-py3-none-any.whl |
|---|---|
| Size | 68.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6da86b8f3d8cb9a22b405e7f9fc854f754089083b61bc2ed07640d6c2eacba0e
|
|
BLAKE2b-256 checksum How to use checksums |
893c465f25a98a66db44ca95d8ab7dc41daaf29f844303d9c7ad4b2df8a07f68
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 4, 2026.
Transparency logSecurity for agentroom 0.2.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agentroom-0.2.5.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.