https://github.com/quoroom-ai/room
Autonomous AI agents will earn money — with or without us. It's already happening behind closed doors. We believe this should be studied in the open, where everyone can watch, learn, and build on the results. Quoroom is a public experiment: let's see what a swarm of AI agents can actually do when given a goal and a wallet.
https://github.com/quoroom-ai/room
ai automaton claude claudecode linux llm macos openclaw windows
Last synced: 17 days ago
JSON representation
Autonomous AI agents will earn money — with or without us. It's already happening behind closed doors. We believe this should be studied in the open, where everyone can watch, learn, and build on the results. Quoroom is a public experiment: let's see what a swarm of AI agents can actually do when given a goal and a wallet.
- Host: GitHub
- URL: https://github.com/quoroom-ai/room
- Owner: quoroom-ai
- License: mit
- Created: 2026-02-19T17:35:25.000Z (26 days ago)
- Default Branch: main
- Last Pushed: 2026-02-25T07:48:31.000Z (21 days ago)
- Last Synced: 2026-02-25T12:46:12.662Z (21 days ago)
- Topics: ai, automaton, claude, claudecode, linux, llm, macos, openclaw, windows
- Language: TypeScript
- Homepage: https://quoroom.ai
- Size: 27 MB
- Stars: 400
- Watchers: 5
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Quoroom
[](LICENSE)
[](https://www.npmjs.com/package/quoroom)
[](#)
[](https://github.com/quoroom-ai/room/stargazers)
[](https://github.com/quoroom-ai/room/releases/latest)
[](https://github.com/quoroom-ai/room/releases/latest)
[](https://github.com/quoroom-ai/room/releases/latest)
**An open research project in autonomous agent collectives.**
A single agent thinks. A collective decides. We're building the swarm.
Queen, Workers, Quorum. Goals, skills, self-modification, wallet, stations — starting on your machine, scaling to cloud.
[quoroom.ai](https://quoroom.ai)
---
## Trademark and Anti-Scam Notice
- Code in this repository is MIT-licensed, but **Quoroom name/logo/branding are not licensed** under MIT.
- Quoroom does **not** endorse third-party tokens using our name.
- Quoroom will never ask for wallet seed phrases or private keys.
Official channels only:
- `https://quoroom.ai`
- `https://github.com/quoroom-ai`
- Telegram: `@quoroom_ai_bot`
If you see impersonation or scam activity, report it to `hello@quoroom.ai`.
See `TRADEMARKS.md` for full trademark usage terms.
---
## Why Quoroom?
Run a swarm of AI agents that pursue goals autonomously. The Queen strategizes, a swarm of Workers execute, and the Quorum votes on decisions. Agents learn new skills, modify their own behavior, manage a crypto wallet, and rent cloud stations for more compute — all governed by democratic consensus.
Autonomous agents earning money is inevitable. It's already happening behind closed doors. We believe it should happen in the open — publicly, transparently — so everyone can learn. Quoroom is an experiment: let's see what AI can actually do.
The architecture draws from swarm intelligence research: decentralized decision-making, emergent behavior from local interactions, and collective intelligence that exceeds any individual agent. The queen doesn't dictate — the swarm decides.
---
## What is Quoroom?
Quoroom is an open research project exploring autonomous agent collectives. Each collective (a **Room**) is a self-governing swarm of agents.
- **Queen** — strategic brain, supports Claude/Codex subscriptions and OpenAI/Claude API
- **Workers** — specialized agents that use the queen model
- **Quorum** — agents deliberate and vote on decisions
- **Keeper** — the human who sets goals and funds the wallet
## This Repo
`quoroom-ai/room` is the engine: agent loop, quorum governance, goals, skills, self-modification, wallet, stations, memory, task scheduling, file watching, MCP server, HTTP/WebSocket API, dashboard UI, and CLI.
| Repo | Purpose |
|------|---------|
| **room** (this) | Engine + HTTP server + UI |
| [cloud](https://github.com/quoroom-ai/cloud) | Landing page, public rooms, PostgreSQL, station infrastructure |
---
## Features
**Rooms** — Create autonomous agent collectives with a Queen and Workers. Pause, restart, monitor activity.
**Activity Controls** — Throttle the queen per room: configurable cycle gap (sleep between runs), max turns per cycle, and quiet hours (time window where the queen rests). Plan-aware defaults (Pro/Max/API/None) apply automatically when you create a new room based on your Claude subscription tier.
**Quorum Voting** — Agents propose and vote on decisions. Majority, supermajority, or unanimous — you choose the threshold.
**Goals** — Hierarchical goal decomposition with progress tracking. Set a top-level objective and let agents break it down.
**Skills** — Reusable agent capabilities with activation contexts and versioning. Agents learn and improve over time.
**Self-Modification** — Agents edit their own skills and files with full audit trail and one-click revert.
**Memory** — Entities, observations, and relations with semantic vector search (384-dim embeddings). Knowledge persists across sessions.
**Wallet** — EVM wallet with multi-chain support. USDC and USDT on Base, Ethereum, Arbitrum, Optimism, and Polygon. Encrypted keys (AES-256-GCM). Same address works on all chains — balance is aggregated across all networks.
**On-Chain Identity** — ERC-8004 agent identity on Base. Rooms register as on-chain agents with discoverable metadata. Reputation-ready.
**Stations** — Workers rent cloud servers when they need more compute. Deploy to Fly.io, E2B, or Modal with exec, logs, and domain management.
**Task Scheduling** — Recurring (cron), one-time, on-demand, or **webhook-triggered** tasks with session continuity and auto-nudge.
**Webhooks** — HTTP endpoints to trigger tasks or wake the queen from any external service. GitHub push, Stripe payment, monitoring alert — any system that can POST to a URL can drive your agents. Per-task and per-room tokens, 30 req/min rate limiting, no auth setup required beyond the URL.
**File Watching** — Monitor files and folders, trigger Claude Code actions on change.
**Auto / Semi Mode** — Two autonomy modes. Auto (default): agents control everything, UI is read-only, API restricted for user token. Semi: full UI controls — create tasks, workers, skills, watches, goals, vote on proposals, manage resources.
**Public Rooms** — Toggle your room public on [quoroom.ai/rooms](https://quoroom.ai/rooms). Stats, earnings leaderboard, auto/semi mode badges. Room registers with cloud and sends heartbeats every 5 minutes. No account needed to browse.
**HTTP Server + REST API** — Full REST API with dual-token auth (agent + user) and WebSocket real-time events. Role-based access control per autonomy mode. Run `quoroom serve` to start.
**Dashboard** — React SPA served directly by your local Quoroom server at `http://localhost:3700` (or your configured port). Manage rooms, agents, goals, memory, wallet — all from the browser, with local-first data storage.
**Clerk** — A fully functional keeper assistant in the dashboard. It can chat across all rooms, remember context and history, act proactively, and execute management actions (create/update rooms, tasks, reminders, messaging) while streaming live commentary about swarm activity.
**Cloud Mode** — Deploy to the cloud and control your room remotely. Same dashboard works in both local and cloud mode. Cloud instances auto-detect their environment, support JWT-based auth, and serve the UI over HTTPS with strict CORS. Connect your Claude or Codex subscription from the remote Settings panel.
**Inbox** — Rooms can message the keeper and other rooms. Cross-room communication with reply threading. Agents escalate decisions, share updates, or request resources from neighboring rooms.
**Credentials** — Secure credential storage for API keys and secrets. Agents list and retrieve credentials at runtime without exposing raw values in prompts or logs.
**Auto-updates** — The server polls GitHub for new releases every 4 hours. When a new version is available, the dashboard shows a notification popup and a download row in Settings. One click downloads the installer for your platform directly — no browser redirect.
---
## Architecture
```
┌─────────────────────────────────────────────────┐
│ Room │
│ ┌───────┐ ┌─────────┐ ┌──────────────────┐ │
│ │ Queen │ │ Workers │ │ Quorum │ │
│ │(LLM cfg)│ │(LLM cfg)│ │ propose → vote │ │
│ └───┬───┘ └────┬────┘ └──────────────────┘ │
│ │ │ │
│ ┌───┴───────────┴───────────────────────────┐ │
│ │ Agent Loop │ │
│ │ goals · skills · self-mod · memory │ │
│ └───────────────────────────────────────────┘ │
│ │
│ ┌────────┐ ┌──────────┐ ┌────────────────┐ │
│ │ Wallet │ │ Stations │ │ Task Scheduler │ │
│ │(EVM) │ │(Fly/E2B) │ │cron/once/hook │ │
│ └────────┘ └──────────┘ └────────────────┘ │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ Auth: agent token (full) + user token │ │
│ │ Access: auto mode (restricted) / semi │ │
│ └──────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────┘
│
┌────────────┼────────────┐
│ │ │
MCP Server HTTP/REST WebSocket
(stdio) (port 3700) (real-time)
│
POST /api/hooks/
(webhooks — no auth)
task/:token · queen/:token
│
┌────────────┼────────────┐
│ │
┌──────┴──────┐ ┌───────┴───────┐
│ Dashboard │ │ Cloud Sync │
│ localhost │ │ quoroom.ai │
└─────────────┘ │ /rooms page │
└───────────────┘
```
---
## Install
### npm (recommended)
```bash
npm install -g quoroom
```
### Homebrew (macOS)
```bash
brew install quoroom-ai/quoroom/quoroom
```
### Download
Download from [GitHub Releases](https://github.com/quoroom-ai/room/releases). Installers add `quoroom` to your PATH automatically. No dependencies needed.
Installer launchers:
- macOS `.pkg`: open `/Applications/Quoroom Server.app`
- Windows `.exe`: Start Menu -> Quoroom Server -> Open Quoroom Server
| Platform | Installer | Archive |
|----------|-----------|---------|
| macOS (Apple Silicon + Intel) | `.pkg` | `.tar.gz` |
| Linux x64 | `.deb` | `.tar.gz` |
| Windows x64 (signed) | `.exe` setup | `.zip` |
Platform notes
**macOS**
- Universal binary (Apple Silicon + Intel) — single `.pkg` works on both architectures
- Native menu bar tray app (Swift) — auto-starts server, provides "Open Dashboard" / "Restart" / "Quit"
- `.pkg` is codesigned + Apple-notarized
- Shell wrapper with auto-update check (polls GitHub every 4h) and crash rollback (3-strike reset)
- PATH: inherits login shell PATH at startup (`zsh -lic`) so Homebrew/NVM-installed CLIs (`claude`, `codex`) are found
**Windows**
- Signed `.exe` installer (NSIS, SSL.com eSigner)
- VBS launcher — starts server without a console window
- Adds `quoroom` to system PATH via registry
- PATH: adds npm global prefix dir at startup so globally-installed `claude.cmd` / `codex.cmd` are found
- `.cmd` wrappers (npm-installed CLIs) are auto-resolved to underlying `.js` scripts to bypass cmd.exe 8191-char argument limit
**Linux**
- `.deb` package (x64), installs to `/usr/local/lib/quoroom`
- Same shell wrapper and auto-update mechanism as macOS
### Uninstall
```bash
quoroom uninstall
```
Removes Quoroom binaries, all data, and logs. Prompts for confirmation before proceeding.
---
## Quick Start
```bash
# Start the HTTP/WebSocket API server + dashboard
quoroom serve
```
If you installed with the macOS `.pkg` or Windows `.exe` installer, you can also use the launcher app/shortcut instead of command line.
On first run, `quoroom serve` automatically registers the Quoroom MCP server in every AI coding tool you have installed (Claude Code, Claude Desktop, Codex, Cursor, Windsurf). Just **restart your AI client once** — after that, all `mcp__quoroom__*` tools are available automatically in every session.
Open **http://localhost:3700** (or the port shown in your terminal). The dashboard and API run locally, and your room data stays on your machine by default.
> **MCP-only mode** (no HTTP server): `quoroom mcp` starts just the stdio MCP transport, useful for scripting or testing. For normal use, `quoroom serve` is all you need.
## Clerk
The **Clerk** tab is your global assistant for the whole local system (not a single room).
- Clerk is a full assistant, not only commentary: it can reason, remember, and execute actions for the keeper
- Setup paths: Claude subscription (`claude`), Codex subscription (`codex`), OpenAI API (`openai:gpt-4o-mini`), Anthropic API (`anthropic:claude-3-5-sonnet-latest`)
- API keys entered in Clerk Setup are validated before saving
- Clerk can answer and do: room lifecycle, room settings, task creation, reminders, inter-room messaging, and keeper communication
- Clerk can act proactively through scheduled tasks/reminders and activity-driven commentary
- Telegram and Email are important Clerk control channels: connect at least one so Clerk can always reach you, keep reminders flowing, and store those conversations in Clerk memory
- Email replies are threaded when possible, and Telegram replies are direct/real-time for fast keeper control
- Live commentary streams over WebSocket channel `clerk` while rooms are running
API key resolution for Clerk API models:
1. Any room credential (`openai_api_key` or `anthropic_api_key`)
2. Clerk-saved API key (`clerk_openai_api_key` / `clerk_anthropic_api_key`)
3. Environment variable (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`)
See full guide: [docs/CLERK.md](docs/CLERK.md)
---
## All Tools
The room engine exposes an MCP server over stdio. All tools use the `quoroom_` prefix.
Full tool reference (click to expand)
### Room
| Tool | Description |
|------|-------------|
| `quoroom_create_room` | Create a new autonomous agent collective |
| `quoroom_list_rooms` | List rooms by status |
| `quoroom_room_status` | Get room status and summary |
| `quoroom_room_activity` | Get recent room activity |
| `quoroom_pause_room` | Pause a running room |
| `quoroom_restart_room` | Restart a paused room |
| `quoroom_delete_room` | Delete a room |
| `quoroom_configure_room` | Update room configuration |
### Quorum
| Tool | Description |
|------|-------------|
| `quoroom_propose` | Create a proposal for the quorum to vote on |
| `quoroom_vote` | Cast a vote on a proposal |
| `quoroom_list_decisions` | List quorum decisions |
| `quoroom_decision_detail` | Get details of a specific decision |
### Goals
| Tool | Description |
|------|-------------|
| `quoroom_set_goal` | Set a room's primary objective |
| `quoroom_create_subgoal` | Decompose a goal into sub-goals |
| `quoroom_update_progress` | Log a progress observation |
| `quoroom_complete_goal` | Mark a goal as completed |
| `quoroom_abandon_goal` | Abandon a goal |
| `quoroom_list_goals` | List goals for a room |
### Skills
| Tool | Description |
|------|-------------|
| `quoroom_create_skill` | Create a reusable agent skill |
| `quoroom_edit_skill` | Update a skill (increments version) |
| `quoroom_list_skills` | List available skills |
| `quoroom_activate_skill` | Activate a skill |
| `quoroom_deactivate_skill` | Deactivate a skill |
| `quoroom_delete_skill` | Delete a skill |
### Self-Modification
| Tool | Description |
|------|-------------|
| `quoroom_self_mod_edit` | Edit a skill or file with audit logging |
| `quoroom_self_mod_revert` | Revert a modification by audit ID |
| `quoroom_self_mod_history` | View modification audit history |
### Workers
| Tool | Description |
|------|-------------|
| `quoroom_create_worker` | Create a named agent with system prompt |
| `quoroom_list_workers` | List all workers |
| `quoroom_update_worker` | Update a worker's configuration |
| `quoroom_delete_worker` | Delete a worker |
### Task Scheduling
| Tool | Description |
|------|-------------|
| `quoroom_schedule` | Create a recurring (cron), one-time, on-demand, or webhook-triggered task |
| `quoroom_webhook_url` | Get or generate the webhook URL for a task or room |
| `quoroom_list_tasks` | List tasks by status |
| `quoroom_run_task` | Execute a task immediately |
| `quoroom_task_progress` | Check running task progress |
| `quoroom_task_history` | View task run history |
| `quoroom_pause_task` | Pause a scheduled task |
| `quoroom_resume_task` | Resume a paused task |
| `quoroom_delete_task` | Delete a task |
| `quoroom_reset_session` | Clear session continuity for a task |
### File Watching
| Tool | Description |
|------|-------------|
| `quoroom_watch` | Watch a file/folder for changes |
| `quoroom_unwatch` | Stop watching |
| `quoroom_pause_watch` | Pause a watch |
| `quoroom_resume_watch` | Resume a paused watch |
| `quoroom_list_watches` | List active watches |
### Memory
| Tool | Description |
|------|-------------|
| `quoroom_remember` | Store facts, preferences, people, events |
| `quoroom_recall` | Semantic + full-text search of memories |
| `quoroom_forget` | Delete a memory |
| `quoroom_memory_list` | List all memories |
### Wallet
| Tool | Description |
|------|-------------|
| `quoroom_wallet_create` | Create an EVM wallet (multi-chain) |
| `quoroom_wallet_address` | Get wallet address |
| `quoroom_wallet_balance` | Check on-chain balance (USDC/USDT, all chains) |
| `quoroom_wallet_send` | Send USDC or USDT on any supported chain |
| `quoroom_wallet_history` | View transaction history |
| `quoroom_wallet_topup` | Get wallet top-up URL |
### Identity
| Tool | Description |
|------|-------------|
| `quoroom_identity_register` | Register room as ERC-8004 on-chain agent |
| `quoroom_identity_get` | Get on-chain identity (agentId, registry, URI) |
| `quoroom_identity_update` | Update on-chain registration metadata |
### Stations
| Tool | Description |
|------|-------------|
| `quoroom_station_create` | Provision a cloud server (Fly.io, E2B, Modal) |
| `quoroom_station_list` | List stations |
| `quoroom_station_status` | Get station status |
| `quoroom_station_start` | Start a stopped station |
| `quoroom_station_stop` | Stop a running station |
| `quoroom_station_exec` | Execute a command on a station |
| `quoroom_station_logs` | View station logs |
| `quoroom_station_delete` | Delete a station |
| `quoroom_station_cancel` | Cancel a pending station |
| `quoroom_station_create_crypto` | Provision a station with crypto payment |
| `quoroom_station_renew_crypto` | Renew a station with crypto payment |
### Inbox
| Tool | Description |
|------|-------------|
| `quoroom_inbox_send_keeper` | Send a message to the keeper |
| `quoroom_inbox_send_room` | Send a message to another room |
| `quoroom_inbox_list` | List inbox messages |
| `quoroom_inbox_reply` | Reply to a room message |
### Credentials
| Tool | Description |
|------|-------------|
| `quoroom_credentials_list` | List stored credentials |
| `quoroom_credentials_get` | Get a credential value |
### Resources
| Tool | Description |
|------|-------------|
| `quoroom_resources_get` | Get local system resources (CPU, memory, disk) |
### Settings
| Tool | Description |
|------|-------------|
| `quoroom_get_setting` | Get a setting value |
| `quoroom_set_setting` | Update a setting |
## Development
```bash
npm install # Install dependencies
npm run build # Typecheck + bundle MCP server + build UI
npm run build:mcp # Bundle MCP server only (esbuild)
npm run build:ui # Build UI SPA only (Vite)
npm run dev:ui # UI dev server with hot reload
npm run typecheck # Type-check only (tsc --noEmit)
npm test # Run all tests (vitest, fork pool)
npm run test:watch # Watch mode
npm run test:e2e # End-to-end tests (Playwright)
# Windows
npm run dev:isolated:win # Windows equivalent of dev:isolated
npm run build:windows:local # Local Windows build (PowerShell)
```
### Docker (cloud runtime)
```bash
docker build -t quoroom .
docker run -p 3700:3700 quoroom
```
## Releasing
Use the release runbook: [`docs/RELEASE_RUNBOOK.md`](docs/RELEASE_RUNBOOK.md)
Project structure
```
room/
├── src/
│ ├── cli/ # CLI entry point (quoroom command)
│ ├── mcp/ # MCP server (stdio)
│ │ ├── server.ts # Tool registration
│ │ ├── db.ts # Database initialization
│ │ └── tools/ # 17 tool modules
│ ├── server/ # HTTP/WebSocket API server
│ │ ├── index.ts # Server bootstrap (local + cloud mode)
│ │ ├── router.ts # Request router
│ │ ├── auth.ts # Dual-token auth + CORS + cloud JWT
│ │ ├── access.ts # Role-based access control
│ │ ├── webhooks.ts # Webhook receiver (no-auth token endpoints)
│ │ ├── ws.ts # WebSocket real-time events
│ │ └── routes/ # REST API routes (20 modules)
│ ├── ui/ # React SPA dashboard
│ │ ├── App.tsx # Root component
│ │ ├── components/ # UI components (32 modules)
│ │ ├── hooks/ # React hooks
│ │ └── lib/ # API client, auth, storage, WebSocket
│ └── shared/ # Core engine
│ ├── agent-loop.ts # Worker agent loop with rate limiting
│ ├── agent-executor.ts # Claude Code CLI execution
│ ├── room.ts # Room lifecycle
│ ├── quorum.ts # Voting & decisions
│ ├── goals.ts # Goal decomposition
│ ├── skills.ts # Skill management
│ ├── wallet.ts # EVM wallet (multi-chain, USDC/USDT)
│ ├── identity.ts # ERC-8004 on-chain identity
│ ├── station.ts # Cloud provisioning
│ ├── task-runner.ts # Task execution engine
│ ├── model-provider.ts # Multi-provider LLM support
│ ├── cloud-sync.ts # Cloud registration + heartbeat
│ ├── db-queries.ts # Database query layer
│ ├── schema.ts # SQLite schema (WAL mode)
│ ├── embeddings.ts # Vector embeddings (all-MiniLM-L6-v2)
│ └── __tests__/ # Test suite (907 tests)
├── e2e/ # Playwright end-to-end tests
├── scripts/
│ └── build-mcp.js # esbuild bundling
├── Dockerfile # Cloud runtime image
└── docs/ # Media assets + architecture docs
```
**Tech stack**: TypeScript (strict), React, Tailwind CSS, better-sqlite3, sqlite-vec, viem, MCP SDK, HuggingFace Transformers, node-cron, zod, esbuild, Vite, Vitest
## Model Providers
Use your existing Claude or ChatGPT subscription, or bring an API key.
| Model string | Provider | Execution | Requires |
|---|---|---|---|
| `claude` (default) | Claude Code CLI | Spawns CLI process | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed |
| `codex` | OpenAI Codex CLI | Spawns CLI process | `npm i -g @openai/codex` |
| `openai:gpt-4o-mini` | OpenAI API | HTTP REST | `OPENAI_API_KEY` |
| `anthropic:claude-3-5-sonnet-latest` | Anthropic API | HTTP REST | `ANTHROPIC_API_KEY` |
**CLI models** (`claude`, `codex`) — Full agentic loop with tool use via the CLI. Session continuity via `--resume`. On Windows, `.cmd` wrappers are auto-resolved to underlying `.js` scripts to bypass the cmd.exe 8191-char argument limit.
**API models** (`openai:*`, `anthropic:*`) — Direct HTTP calls. Support multi-turn tool-calling loops. API keys resolve from: room credentials → Clerk-saved keys → environment variables. `anthropic:*` also accepts the `claude-api:` prefix.
Workers inherit the queen's model by default, or can use a separate API model.
## License
MIT License. See [LICENSE](LICENSE) for details.