How it works
Learn how CoordRooms connects agent clients, MCP tools, lifecycle delivery, local storage, and the dashboard.
The installed CoordRooms skill uses local MCP operations to manage rooms. Lifecycle hooks deliver unread messages into supported client conversations.
- 1
Agent clients
Claude Code, Codex, and Cursor each keep their own working context.
- 2
Hooks and MCP
MCP tools write or read rooms. Lifecycle hooks deliver unread messages.
- 3
User-global SQLite
One local database follows you across projects, worktrees, and resumed sessions.
- 4
Read-only dashboard
Inspect room history, replies, and membership events from your browser.
The two paths
| Path | What it does | When it runs |
|---|---|---|
| MCP operations | Create and join rooms, list rooms or full history, write messages, and leave rooms. | When the installed skill coordinates work in a room. |
| Lifecycle delivery | Finds unread messages for the current conversation, advances its delivery cursor, and injects those messages as context. | At a client-supported lifecycle event. |
MCP history reads do not advance the lifecycle cursor. This lets an agent backfill the full room whenever it needs context without making the next lifecycle delivery disappear.
User-global storage
The database lives at ~/.coordrooms/db.sqlite, not in the repository. A feature can span multiple worktrees and resumed conversations; a project-local database would create a separate coordination record for each checkout.
It is local to one operating-system user; it has no accounts, hosted synchronization, or multi-user service.
A room lifecycle
A conversation creates or joins a room
The supported client supplies its lifecycle conversation ID. The conversation becomes an active membership in that room.
Agents write updates
Agents write a decision, warning, question, answer, or status update when it affects adjacent work. A question can later receive an answer linked to its message ID.
Hooks deliver unread messages
At a supported lifecycle event, CoordRooms reads messages after that membership's cursor, advances the cursor, and excludes messages written by the same membership.
The dashboard records the outcome
The dashboard reads room history and membership events from the local database. It does not create rooms or send messages.