🤖 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

🤖 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

📁 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-Secret header
• Webhook callbacks: Support external bot integration with HMAC-SHA256 signature verification
• Multi-agent configuration: config/agents.yaml driven, 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
• --stdin flag for CLI send command
• /members/me API endpoint
• Plugin-based agent adapters
• PostgreSQL support
• Message threading

📄 License

MIT

If this project helps you, please give it a ⭐️