Chatroom
Chatroom is a multi-agent collaboration stack: a Next.js web app and Convex backend where people and AI assistants coordinate in shared rooms with role-based handoffs. This repository is a pnpm + Turborepo monorepo containing the product UI, Convex functions, and the chatroom CLI agents use to pull tasks and hand off work.
Prerequisites
| Requirement | Notes |
|---|
| Node.js | Version 22 or later (matches Next.js and toolchain expectations). |
| pnpm | 10.x — the repo pins packageManager in the root package.json; use corepack enable then corepack prepare [email protected] --activate if needed. |
| Convex account | Sign up at convex.dev — used when you run local Convex dev or deploy. |
| chatroom CLI (for agent workflows) | Install globally (npm install -g chatroom-cli) or build from packages/cli in this repo (see packages/cli/README.md). |
| Bun (optional) | Some scripts (for example pnpm migrate, icon generation) invoke Bun; install from bun.sh if you use those paths. |
Local setup
1. Clone and install
git clone <repository-url>
cd chatroom
pnpm install
2. Initialize Convex and env files
Run the setup script once (interactive branding prompts, or skip them):
pnpm setup
Or non-interactive / skip branding:
pnpm setup --skip-branding -y
This wires services/backend (Convex) with apps/webapp by creating/updating .env.local files — notably NEXT_PUBLIC_CONVEX_URL for the web app.
Manual alternative: From services/backend, run npx convex dev --once, then copy CONVEX_URL into apps/webapp/.env.local as NEXT_PUBLIC_CONVEX_URL=....
3. Start development
From the repo root:
pnpm dev
4. Quality checks (optional)
pnpm typecheck
pnpm test
pnpm lint:fix
pnpm format:fix
Project structure
| Path | Purpose |
|---|
apps/webapp | Next.js (App Router) frontend |
services/backend | Convex backend (schema, functions, auth) |
packages/cli | chatroom-cli — agent commands (get-next-task, handoff, etc.) |
docs/, guides/ | Documentation and longer-form guides |
scripts/ | Setup, migrations |
For day-to-day coding conventions, see AGENTS.md.
Custom agent flow (Chatroom integration)
Automation (for example in Cursor) that participates in a room should follow a tight loop so work is never left hanging:
get-next-task → do work → handoff → get-next-task → …
- Run
get-next-task immediately (e.g. via your environment’s shell tool) and block until a task is delivered.
- Execute the task in the codebase or product.
- Run
handoff to pass control to the next role (or back to the user).
- Run
get-next-task again to wait for the next assignment.
Reliability tip: Keep the full handoff and get-next-task commands (including CHATROOM_CONVEX_URL if you use a custom deployment) in your last todo items so you do not skip the handoff after compaction or long runs.
Commands (with local backend)
Point the CLI at your local Convex dev URL (same value as NEXT_PUBLIC_CONVEX_URL in apps/webapp/.env.local, often http://127.0.0.1:3210):
export CHATROOM_CONVEX_URL="http://127.0.0.1:3210"
chatroom get-next-task --chatroom-id=<id> --role=<role>
chatroom handoff --chatroom-id=<id> --role=<role> --next-role=<role>
If your context was summarized and you need the full system prompt again:
chatroom get-system-prompt --chatroom-id=<id> --role=<role>
End-to-end flow for humans: create a room in the web app, copy the agent prompt from the UI, install/authenticate the CLI (chatroom auth login when using the hosted backend), then run the loop above. Full CLI options, roles, and environment variables are documented in packages/cli/README.md.
System administration and Google OAuth
- First system admin: sign in anonymously, then in the Convex dashboard set your user’s
accessLevel to system_admin in the users table. Open System Admin from the user menu in the app.
- Google OAuth: configure credentials under System Admin → Google Auth; then move
system_admin to your Google user in the users table as described in the in-app flow.
Documentation
Testing
Tests use Vitest across apps and packages.
pnpm test
pnpm test:watch
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
