Agent Chatroom MCP

Public preview in preparation: Core features work, but installer distribution and the latest Claude Code channel integration are still under development. See ROADMAP.md for the public roadmap and CONTRIBUTING.md for how to contribute.

When multiple subagents are working, this MCP tool stops an agent right before a critical decision and lets a human approve, give feedback, or intervene in real time from a dashboard or phone.

The core is the blocking gate — an agent pauses right before a risky or hard-to-reverse action (deploy, delete, external call…) and waits until a human responds. The response isn't given in the terminal; the human answers from a dedicated operations dashboard (including a phone on the same Wi-Fi) via buttons and input fields.

Above: Live demo of the operations dashboard — on the right, NEEDS YOU gates (approve button, feedback input, blocker resolution) are handled directly by a human. On the left, the roster (per-agent status); in the center, the stream (date separators, type filter). The desktop uses a 3-pane layout; mobile adapts with a bottom sheet. (Demo state from seed.py)

Why it exists (core value)

• 🚦 Blocking gates — the agent stops right before a decision and waits for a human. Not a polled notification that can be ignored, but a real intervention point that only resolves when the human answers.

• 📱 Dashboard/phone interaction — approve/reject with [Approve]/[Reject] buttons, feedback fields, and blocker-resolution fields with no terminal needed. Intervene even from a phone while away.

• 🗄️ SQLite as single source of truth — distinct subagents share one DB file (WAL) and merge state. Everything is in-memory free; all timestamps are UTC ISO 8601.

Related MCP server: @looppause/mcp

Why it was built (core value)

• 🚦 Blocking gates — the agent pauses before a decision and waits for a human. Not a polled notification that can be ignored, but a real intervention point that only proceeds when the human answers.

• 📱 Dashboard/phone — approve, reject, give feedback, or clear blockers with buttons and inputs, no terminal needed. Intervene from your phone while away.

• 🗄️ SQLite as the single source of truth — distinct subagents share one DB file (WAL) and all state; no in-memory-only state, timestamps are UTC ISO 8601.

Three kinds of gates (MCP tools)

Implementation is DB-polling — the server polls the DB for a decision (the dashboard writes the human's choice to the DB). The agent stays blocked until then.

Monitoring dashboard

• Room separation & switching — per-task rooms, switched via deep links (mcp://).

• Per-room attention badges — pending approvals (amber) and open blockers (red) shown even when the room is not focused.

• NEEDS YOU panel — highlights the three gate kinds waiting for a human.

• Roster with 4 states — per-agent status derived (waiting 🟡, blocker 🔴, done 🟢, working 🟡*).

• Type filter — message-type chips filter the stream.

• Date separators — stream shows date dividers (YYYY-MM-DD (weekday), with Today/Yesterday).

• Auto-refresh — polls every few seconds, with an empty-state hint.

Other MCP tools

• post_message — record a message · read_messages — query with since / limit.

• wait_for_message — wait for a mention from legacy session-based workers. The replacement channel-based path is planned for v6.

• join_room / leave_room / kick / set_presence — room membership and status.

Current extensions

• Room management — create, rename, soft-delete, restore from trash, backup then permanent delete.

• v4 local mediator PoC — GGUF model judgment, routing, DB bridge. Models are never auto-downloaded.

• v5 event spawn — mention-based Claude CLI workers, with role, model, effort, autonomy ping-pong, and dashboard controls.

• v6 planning — wake idle sessions without pinging, workspaces, shared/role memory, and session handover. Not yet implemented.

Quick start

Beginner friendly: run each step line by line. Prerequisites: Python 3.13 and a virtual environment (.venv) created in this folder.

1) Install dependencies

.venv/bin/python3 -m pip install -r requirements.txt

2) Register the MCP server (stdio)

Register this server in Claude Code. Replace /absolute/path with the actual path to this project.

claude mcp add agent-chatroom -e CHATROOM_DB=/절대경로/chatroom.db -- /절대경로/.venv/bin/python3 /절대경로/src/server.py

→ After registration, run /mcp in Claude Code and you'll see the tools as mcp__agent_chatroom__*.

3) Turn on the dashboard (separate from the MCP server)

The easiest way is a one-liner (prints startup checks + starts the dashboard; no new behavior):

python launch.py

The original manual command still works too:

.venv/bin/python3 src/dashboard/server.py

Then open http://127.0.0.1:7777 in your browser. If a gate is waiting, the dashboard must be running for a human to answer.

To view from a phone on the same Wi-Fi:

DASHBOARD_HOST=0.0.0.0 .venv/bin/python3 src/dashboard/server.py

When it starts, it will print the LAN address like http://192.168.x.x:7777; open that on your phone.

4) Tour the dashboard with sample data

To see the actual behavior without a real agent, seed the dashboard with a demo state:

.venv/bin/python3 seed.py

→ This fills the dashboard with sample agents, gates, and messages (screenshot above). The demo data is in-memory only; restart clears it.

🔐 Security

• Dashboard access is local/trusted-network only. The 0.0.0.0 flag exposes it to the whole Wi-Fi, so anyone on the network can approve or reject. Use only on networks you trust.

• Do not port-forward it to the internet — that would expose the controls publicly.

• For access from outside your Wi-Fi (e.g., LTE), use Tailscale. It connects only your own devices, with no open internet port, so auth is handled by your tailnet. When you start with 0.0.0.0, the startup output shows a → Tailscale: http://100.x:7777 address. Steps: PHASE3-TAILSCALE.md. (Do not expose via Tailscale Funnel or similar.)

• On first launch, macOS may ask to allow incoming connections — allow it so your phone can connect. Change the port with the DASHBOARD_PORT env var.

Usage notes

• Keep the dashboard open while a gate is waiting. request_approval blocks the agent until a human decides (or until timeout_seconds). If the dashboard is closed, no one can answer and the agent stays blocked.

• wait_for_message is session-based and legacy. It works, but the newer mention-based channel (v6) is recommended.

• SQLite concurrency — The server uses WAL mode and busy timeout; concurrent reads from the dashboard and writes from MCP tools are safe.

Contributing

Bug reproductions, docs improvements, and OS compatibility checks are all welcome. For larger features, open an issue first to agree on scope and safety boundaries, then submit a small PR. Details in CONTRIBUTING.md.

License

Mozilla Public License 2.0. If you distribute modified files, those files must be released under MPL-2.0 terms; larger works that combine them may use other terms.