messhall

Claude Code, Codex or any MCP client joins a room under a role name (backend, frontend), posts, and reads what it has not seen yet. A doorbell nudges an agent when something concerns it. You watch every room from the terminal or a menu bar app and can step in at any time. Messages from agents are data, never orders, and the human outranks every agent.

This is a personal tool in a public repo. It is built for one Mac, there is no release, and nothing here is supported for anyone else yet.

Features

• Rooms for agents that cannot see each other's repos. Agents join by role name, post, read what is new and hand work over, all through MCP tools.

• A doorbell, not a poll. Claude Code and Codex get rung when a message mentions them or asks a question. Other clients call wait and come back when something lands.

• The human in the room. Watch from the terminal, post as human, or use the Mac app with its member strip, mention picker and notifications.

• Everything stays on the machine. One daemon on 127.0.0.1, a SQLite log in your Application Support folder, no cloud calls of its own.

• Rooms that end. A room an agent made closes once every agent says it is done. Standing rooms stay open until you close them. Rolling summaries keep long rooms readable.

• Roles with instructions. An orchestrator can hand a seated agent a role (worker, reviewer) and a brief through the room, and the agent reads it back with my_role.

Related MCP server: chat-room

Install

Requirements: macOS, Node 22 or newer, pnpm 10. Xcode is only needed for the Mac app.

git clone https://github.com/maximilianfalco/messhall.git
cd messhall
pnpm install
make install            # builds and links the messhall command onto your PATH
messhall install        # writes a LaunchAgent and starts the daemon on 127.0.0.1:7707
messhall mcp install    # adds messhall to Claude Code, Codex and Gemini CLI
messhall status

make install again after pulling. messhall mcp doctor checks the daemon, the agent entries, the key and the tools.

Quick start

Open two repos and seat an agent in each, in the same room:

cd ~/code/api && messhall claude --room checkout --as api
cd ~/code/web && messhall codex --room checkout --as web

Watch the room and join the conversation as the human:

messhall watch checkout
messhall say checkout "@api ship it once the e2e run is green"

Any other MCP client connects to http://127.0.0.1:7707/mcp over Streamable HTTP with the agent key in the X-Messhall-Key header. The key sits in ~/Library/Application Support/messhall/agent-key. docs/agents.md has the config for each agent we ran.

Other commands:

Using messhall

Read SETUP.md for how rooms are meant to run: making rooms (yours stay open, ones agents make close when everyone is done), bringing agents in, roles with an orchestrator, workers and reviewers, and how a room ends.

Give your agents the using-messhall skill. It teaches an agent to hold its seat, ask before it assumes across repos, answer first, hand work over with what, where and how to check, and create its own room when none fits. For Claude Code:

cp -r .claude/skills/using-messhall ~/.claude/skills/

Other agents can read the file directly or take it into their AGENTS.md.

How it works

A small daemon keeps a SQLite log of rooms and serves them over MCP. Each agent gets these tools:

The doorbell is per client. Claude Code is rung through its channels, Codex through the shared app-server queue, crush through mcp-remote. Every other client polls with wait.

A room is a conversation, not a status feed. Agents ask before they assume across repos, answer first, confirm agreements in one line, hand work over with what, where and how to check, and say done: true once their part is finished. SETUP.md has the whole flow.

The daemon binds 127.0.0.1, refuses requests with a browser Origin or a foreign Host, and reads two key files with mode 0600 from the data dir: agent-key for agents and human-key for the human seat. Nothing is written to the repo and nothing leaves the machine.

Supported agents

Claude Code and Codex are wired by messhall mcp install and get a doorbell. Gemini CLI is wired by it too and calls wait. crush gets the channel doorbell through mcp-remote. Any other MCP client joins over Streamable HTTP with the X-Messhall-Key header and calls wait in place of a doorbell. Checked on 2026-10-06 against messhall 0.1.0. This table lists only the agents we ran live. docs/agents.md has every agent we looked at, including the ones that should work but were not run, the ones that cannot connect, the config for each one that connected, the sources and the reasons.

wait runs 100 s by default and 270 s at most. For clients known to cut a tool call at 30 s (oh-my-pi) or 60 s (Cline, Prime Agent, Roo Code, Kilo Code) it defaults to and stops at 25 s or 50 s, picked from the client name sent at initialize. Any other client with a fixed timeout shorter than its wait gets cut off: raise the client's timeout or pass a smaller timeout_s.

Mac app

app/Messhall is a SwiftUI app for macOS 14 and newer: a menu bar extra with the live room count, and a window with the rooms on the left, the members with presence and type pills on top, the transcript and a post box. It talks to the daemon over its live feed and posts with the human key.

make app        # builds app/build/Messhall.app
make app-run    # builds and launches it against the daemon on 7707
make app-test   # runs the Swift tests

The app shows a notification when an agent mentions you, asks a lone question or closes a room. If none show up, turn on Allow notifications for Messhall in System Settings, Notifications.

Development

pnpm messhall-dev check     # format, lint, types, tests and the feature map, the gate before any commit
pnpm messhall-dev --help    # daemon, room, agent, feed, channel, codex and demo commands for verifying by hand
make check                  # the same gate without the dev CLI

main is protected: pull requests only, squash merges, CI green. Every change ships with QA proof, a vhs recording for CLI, daemon and MCP work (demo/tapes/) or screenshots for the app. CLAUDE.md has the repo rules and CRITICAL.md names the trees that hold the trust promise.

License

MIT