{
  "markdown": "# Chatroom\n\nChatroom 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.\n\n---\n\n## Prerequisites\n\n| Requirement                            | Notes                                                                                                                                                  |\n| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **Node.js**                            | Version **22 or later** (matches Next.js and toolchain expectations).                                                                                  |\n| **pnpm**                               | **10.x** — the repo pins `packageManager` in the root `package.json`; use `corepack enable` then `corepack prepare pnpm@10.15.1 --activate` if needed. |\n| **Convex account**                     | Sign up at [convex.dev](https://www.convex.dev/) — used when you run local Convex dev or deploy.                                                       |\n| **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](packages/cli/README.md)). |\n| **Bun** (optional)                     | Some scripts (for example `pnpm migrate`, icon generation) invoke Bun; install from [bun.sh](https://bun.sh/) if you use those paths.                  |\n\n---\n\n## Local setup\n\n### 1. Clone and install\n\n```bash\ngit clone <repository-url>\ncd chatroom\npnpm install\n```\n\n### 2. Initialize Convex and env files\n\nRun the setup script once (interactive branding prompts, or skip them):\n\n```bash\npnpm setup\n```\n\nOr non-interactive / skip branding:\n\n```bash\npnpm setup --skip-branding -y\n```\n\nThis wires **`services/backend`** (Convex) with **`apps/webapp`** by creating/updating `.env.local` files — notably `NEXT_PUBLIC_CONVEX_URL` for the web app.\n\n**Manual alternative:** From `services/backend`, run `npx convex dev --once`, then copy `CONVEX_URL` into `apps/webapp/.env.local` as `NEXT_PUBLIC_CONVEX_URL=...`.\n\n### 3. Start development\n\nFrom the repo root:\n\n```bash\npnpm dev\n```\n\n- Web app: **http://localhost:3000**\n- Convex dev sync runs as part of the backend package’s dev script.\n\n### 4. Quality checks (optional)\n\n```bash\npnpm typecheck\npnpm test\npnpm lint:fix\npnpm format:fix\n```\n\n---\n\n## Project structure\n\n| Path               | Purpose                                                              |\n| ------------------ | -------------------------------------------------------------------- |\n| `apps/webapp`      | Next.js (App Router) frontend                                        |\n| `services/backend` | Convex backend (schema, functions, auth)                             |\n| `packages/cli`     | **chatroom-cli** — agent commands (`get-next-task`, `handoff`, etc.) |\n| `docs/`, `guides/` | Documentation and longer-form guides                                 |\n| `scripts/`         | Setup, migrations                                                    |\n\nFor day-to-day coding conventions, see [AGENTS.md](AGENTS.md).\n\n---\n\n## Custom agent flow (Chatroom integration)\n\nAutomation (for example in Cursor) that participates in a room should follow a **tight loop** so work is never left hanging:\n\n```text\nget-next-task → do work → handoff → get-next-task → …\n```\n\n1. **Run `get-next-task` immediately** (e.g. via your environment’s shell tool) and **block** until a task is delivered.\n2. **Execute the task** in the codebase or product.\n3. **Run `handoff`** to pass control to the next role (or back to the user).\n4. **Run `get-next-task` again** to wait for the next assignment.\n\n**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.\n\n### Commands (with local backend)\n\nPoint 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`):\n\n```bash\nexport CHATROOM_CONVEX_URL=\"http://127.0.0.1:3210\"\n\nchatroom get-next-task --chatroom-id=<id> --role=<role>\nchatroom handoff --chatroom-id=<id> --role=<role> --next-role=<role>\n```\n\nIf your context was summarized and you need the full system prompt again:\n\n```bash\nchatroom get-system-prompt --chatroom-id=<id> --role=<role>\n```\n\n**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**](packages/cli/README.md).\n\n---\n\n## System administration and Google OAuth\n\n- **First system admin:** sign in anonymously, then in the [Convex dashboard](https://dashboard.convex.dev) set your user’s `accessLevel` to `system_admin` in the `users` table. Open **System Admin** from the user menu in the app.\n- **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.\n\n---\n\n## Documentation\n\n- **[Shadcn → Base UI Migration Guide](docs/developer/shadcn-base-ui-migration.md)** — upgrading UI components from Radix-based shadcn to Base UI (`base-vega`); includes a downstream migration playbook for forks built on this template.\n- [Testing Guide](guides/testing/testing.md)\n- [AGENTS.md](AGENTS.md) — development guidelines for agents and contributors\n\n## Testing\n\nTests use [Vitest](https://vitest.dev/) across apps and packages.\n\n```bash\npnpm test\npnpm test:watch\n```\n\nFor detailed testing guidance, see [guides/testing/testing.md](guides/testing/testing.md).\n\n---\n\n## Deployment\n\n### Convex (backend)\n\n1. Create a production deploy key in the Convex project settings.\n2. Add a repository secret (for example `CONVEX_DEPLOY_KEY_PROD`) if you use the included GitHub Action for deploy-on-push.\n\n### Vercel (frontend)\n\n- Set the Vercel **root directory** to `apps/webapp`.\n- Set `NEXT_PUBLIC_CONVEX_URL` to your production Convex deployment URL.\n\n---\n\n## Why Convex?\n\nConvex gives reactive queries, transactional mutations in one language, and a small surface area for app code — which keeps both product and agent-driven changes easier to reason about. (See the original starter rationale in git history if you want the longer comparison.)\n\n---\n\n## License\n\nElastic License 2.0 — see repository licensing files for details.\n\n---\n\n## Direct-harness sessions (preview)\n\nDirect-harness sessions let you run an opencode AI process on a registered machine and interact with it directly from the chatroom UI — prompt it, switch the active agent mid-conversation, and resume after a daemon restart without losing message history.\n\nAvailable in all environments — no setup required.\n\n### CLI commands\n\n```bash\n# Open a new harness session in a registered workspace\nchatroom session open --workspace-id <id> --agent build\n\n# Resume an existing session after a daemon restart\nchatroom session resume \\\n  --harness-session-row-id <id> \\\n  --harness-session-id <sdk-session-id>\n```\n\nWorkspaces are registered automatically by the daemon when agents start. List workspaces for a chatroom via the UI or the existing `api.workspaces.listWorkspacesForChatroom` query.\n\n### UI side panel\n\nThe **Direct Harness** panel appears in the chatroom sidebar (below the work queue) when the flag is on:\n\n```\n┌──────────────────────────────────┐\n│ ▸  Direct Harness                │\n├──────────────────────────────────┤\n│  Workspace   [/home/user/repo ▼] │\n│                                  │\n│  Sessions                        │\n│  ● build      active  ···        │\n│  ○ planner    idle    ···        │\n│                                  │\n│  [ + New session ]               │\n├──────────────────────────────────┤\n│  Hello from the harness          │\n│  Processing your request…        │\n│                                  │\n│  [build ▼]                       │\n│  ┌─────────────────────────┐     │\n│  │ Type a prompt…          │ ▶   │\n│  └─────────────────────────┘     │\n└──────────────────────────────────┘\n```\n\n- **Workspace picker** — selects which workspace (machine + working dir) to target.\n- **Session list** — shows harness sessions with status dots (green=active, grey=idle, red=failed). Click an idle session to resume it transparently.\n- **New session button** — opens an agent picker; disabled while the harness is booting.\n- **Message stream** — live messages from the running harness session.\n- **Agent chip** — click to switch the active agent mid-conversation; uses the existing session without restarting.\n",
  "bytes": 9052,
  "sha": "7fb3ae51d52f9dd544487c6a0a0212683768f7bc7e77bc33474c633bfc054714",
  "repo_slug": "conradkoh/chatroom",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_conradkoh_chatroom_memory_index_md_6e1d8267/readme"
}