mcp-huddle 0.3.0__tar.gz

mcp_huddle-0.3.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+*.egg
+
+# macOS
+.DS_Store
+
+# Tests / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Env
+.env
+*.env
+
+# Logs (runtime / stray service logs — never belong in the repo)
+*.log

mcp_huddle-0.3.0/CHANGELOG.md

@@ -0,0 +1,106 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-06-19
+
+### Added
+
+- **Read-only discussant agents by default** (`MCP_HUDDLE_READONLY`, default ON;
+  set `=0` for full-access workers). Spawned agents read files/web/docs/rules/
+  memory but cannot edit/write — they participate only via the huddle MCP tools.
+  Claude uses an allow/deny tool list; Codex uses `-s read-only` plus
+  auto-approved huddle MCP tools (verified: read-only sandbox + MCP works once
+  the MCP approval mode is `approve`).
+- **Cloud-API agents**: `openai_compatible_runner --api-key-env` lets any
+  OpenAI-compatible cloud API (OpenAI/OpenRouter/vLLM/proxied Anthropic) join as
+  a read-only discussant via a registry entry — no CLI, no MCP on the agent side.
+- **Paste-a-prompt onboarding** (`docs/ONBOARDING.md`): fill in which agents you
+  use (CLI or cloud API) and your AI agent installs huddle, registers the MCP
+  server, installs hooks, and writes `~/.mcp-huddle/registry.json`.
+- `mcp-huddle --install-hooks [DIR]` copies the bundled Claude Code hooks and
+  prints the `settings.json` wiring.
+- Optional on-disk registry `~/.mcp-huddle/registry.json` (merged with defaults;
+  precedence env > file > defaults) + a startup agent-discovery summary.
+- Endpoint auth: `_require_local` enforces loopback on mutating HTTP endpoints +
+  SSE, with an optional `MCP_HUDDLE_TOKEN` bearer (no-op when unset).
+- Dashboard: 3 skins (Glass/Web/Code), 5 terminal palettes, 10-language i18n
+  (incl. Arabic RTL), a single ⚙️ settings popover (theme × design × palette ×
+  language) with `?` help tooltips, an MCP-connection section, an env-vars/
+  spawn-rules reference, and a copyable agent-setup prompt.
+- Room tree regrouped: project → date → organizer → numbered chats.
+- Resizable + collapsible panels (collapse to a 48px rail with an expand
+  button), and a narrow-window overlay mode (chat full-width, side panels open
+  as opaque drawers over the chat via the ◧/◨ buttons).
+- `CLAUDE.md` contributor/agent guide; README hero + theme/language gallery.
+- PEP 561 `py.typed`; `--help` / `--version` CLI.
+
+### Changed
+
+- `requires-python` raised to `>=3.11` (the code uses `typing.NotRequired`).
+- Antigravity (`agy`) is now opt-in (`MCP_HUDDLE_ANTIGRAVITY_ENABLED=1`,
+  default OFF): it needs a prior interactive `agy` login (headless can't sign
+  in) and exposes no read-only flag. MiMo runs in a temp dir (never touches the
+  project), so it is effectively read-only with respect to your files.
+
+### Fixed
+
+- Portability: removed macOS-only hardcoded paths (`mimo_runner` temp dir →
+  `tempfile`; agent binaries resolved via `shutil.which`).
+- `server.py`: safe env-int parsing, `spawned_pids` merge under the meta lock,
+  `tempfile` brief (closes a `/tmp` TOCTOU), centralized Codex thread-resume.
+- `bus.py`: corrupt-JSON resilience, `0700` data-dir perms, bounded message cache.
+- MiMo runner validates output so a provider error (e.g. 403) is never posted as
+  a reply. Palette × light-theme clash fixed (palettes force dark structure).
+
+## [0.2.0] - 2026-06-18
+
+### Added
+
+- Liquid Glass web dashboard with light/dark themes, agent avatars, kind badges,
+  and reply-to quotes.
+- Configurable auto-spawn registry via `MCP_HUDDLE_SPAWN_REGISTRY` (JSON file);
+  see `examples/registry.json`.
+- Codex wake-up loop: follow-up `kind=request` messages resume the same captured
+  Codex thread via `codex exec resume`.
+- MiMo Code advisor slot (toggle with `MCP_HUDDLE_MIMO_ENABLED`).
+- Watchdog that auto-closes rooms whose owner process died, plus retention sweep
+  for terminal rooms (`HUDDLE_RETENTION_DAYS` / `HUDDLE_RETENTION_SWEEP_SECS`).
+- Rate-limit / usage-limit detection with cooldown and an in-room notice instead
+  of a silent agent death (`MCP_HUDDLE_RATE_LIMIT_COOLDOWN_SEC`).
+- `CONTRIBUTING.md`, this `CHANGELOG.md`, and an expanded README (configuration
+  reference, security note, troubleshooting, and architecture overview).
+
+### Changed
+
+- Default spawn registry is now Codex, Antigravity, MiMo, and Claude. Claude is
+  opt-in and OFF by default (`MCP_HUDDLE_CLAUDE_ENABLED=1` to enable) because
+  headless `claude -p` is metered.
+- The HTTP dashboard binds to `127.0.0.1` only.
+- Crash-safe lock release; malformed request bodies now return `400` instead of
+  `500`.
+
+### Removed
+
+- Retired the local Qwen and DeepSeek advisor slots and the reverse-API
+  browser-session bridges they fronted.
+- Retired the Gemini CLI slot; the Google-model advisor now runs exclusively on
+  Antigravity (`agy`).
+
+## [0.1.2]
+
+### Added
+
+- Initial public-ish release: FastMCP server with persistent JSONL rooms,
+  10 MCP tools, anti-loop guards, consensus (propose/vote), and stdio + HTTP
+  transports.
+
+[Unreleased]: https://github.com/kolotovalexander/mcp-huddle/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/kolotovalexander/mcp-huddle/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/kolotovalexander/mcp-huddle/releases/tag/v0.2.0
+[0.1.2]: https://github.com/kolotovalexander/mcp-huddle/releases/tag/v0.1.2

mcp_huddle-0.3.0/CLAUDE.md

@@ -0,0 +1,52 @@
+# CLAUDE.md — working on mcp-huddle
+
+Guidance for AI agents (and humans) editing this repo. User-facing docs:
+`README.md`; onboarding: `docs/ONBOARDING.md`; open work: `docs/TODO.md`.
+
+## What this is
+A persistent multi-agent chat MCP server. AI agents join rooms and discuss;
+a web dashboard lets humans watch/intervene. Two run modes (one binary):
+`mcp-huddle` (stdio MCP) and `mcp-huddle --http` (HTTP MCP + dashboard on :8014).
+
+## Layout (deep modules, clear seams)
+- `src/mcp_huddle/server.py` — MCP tools + HTTP/SSE routes + spawn/wake
+  orchestration. The public surface; keep tool/route signatures stable.
+- `src/mcp_huddle/bus.py` — file-locked room/message/meta store with an
+  in-process message cache. **Concurrency-critical**: never change lock
+  ordering or acquire two locks at once; additions must stay defensive.
+- `src/mcp_huddle/spawn.py` — agent registry + spawning. Agents are spawned
+  one-shot per turn (`cd <project> && <cli> …`), re-woken per addressed message;
+  Codex resumes its thread. `DEFAULT_REGISTRY`, read-only transform
+  (`_apply_readonly`, default ON), on-disk registry merge.
+- `src/mcp_huddle/openai_compatible_runner.py` / `mimo_runner.py` — runners for
+  agents that don't speak MCP (cloud APIs / MiMo): read the room, call the
+  model, post via the bus. Both validate output before posting.
+- `src/mcp_huddle/__main__.py` — CLI (argparse): `--http`, `--port`,
+  `--version`, `--install-hooks`.
+- `src/mcp_huddle/static/{dashboard.html,css,js}` — the dashboard (vanilla JS,
+  no build step). Themes axis `data-theme`, skin axis `data-skin`, palette axis
+  `data-palette`, language `data-lang`; settings popover + i18n live in
+  `dashboard.js`.
+
+## Conventions
+- Python 3.11+ stdlib only (no third-party in runtime code beyond `mcp` /
+  starlette / uvicorn). Keep it dependency-light.
+- Agents are **read-only discussants by default** (`MCP_HUDDLE_READONLY`); they
+  read but never edit files and talk only via huddle MCP / the bus.
+- New agent slots: prefer a `~/.mcp-huddle/registry.json` entry or the
+  `openai_compatible_runner` over hard-coding; cloud APIs use `--api-key-env`.
+- Dashboard JS: no framework, no bundler — edit the files directly. UI strings
+  go through `t()` / `data-i18n`.
+
+## Verify before claiming done
+```bash
+.venv/bin/pytest tests/ -q          # full suite (currently 93 passing)
+node --check src/mcp_huddle/static/dashboard.js   # JS syntax
+```
+For dashboard changes, the server serves files fresh (no-cache) — just reload
+the browser. Python changes (server/spawn) require a server restart to go live.
+
+## Don't
+- Don't break `bus.py` locking or `server.py` tool/route signatures.
+- Don't add a build step or runtime dependencies to the dashboard.
+- Don't enable agents that need interactive login (agy) by default.

mcp_huddle-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to mcp-huddle
+
+Thanks for your interest in improving mcp-huddle! This is a small, focused
+project — bug fixes, docs, and well-scoped features are all welcome.
+
+## Development setup
+
+Requires Python 3.10+.
+
+```bash
+git clone https://github.com/kolotovalexander/mcp-huddle
+cd mcp-huddle
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running the server locally
+
+```bash
+mcp-huddle --http            # HTTP + dashboard on http://127.0.0.1:8014/dashboard
+mcp-huddle                   # stdio transport (for MCP clients)
+```
+
+Rooms are stored under `~/.mcp-huddle/` (override with `MCP_HUDDLE_HOME`). When
+hacking, point `MCP_HUDDLE_HOME` at a throwaway directory so you don't touch your
+real rooms:
+
+```bash
+MCP_HUDDLE_HOME=$(mktemp -d) mcp-huddle --http
+```
+
+## Running tests
+
+```bash
+.venv/bin/pytest tests/ -q
+```
+
+Please add or update tests for any behavior change. Tests should be hermetic —
+use the provided fixtures and an isolated `MCP_HUDDLE_HOME`; do not depend on
+network access or on any agent CLI (`codex`, `agy`, `mimo`) being installed.
+
+## Pull request workflow
+
+1. Fork and create a topic branch off `main`.
+2. Keep changes focused; avoid unrelated refactors in the same PR.
+3. Make sure `pytest` passes and the dashboard still loads.
+4. Update `README.md` and `CHANGELOG.md` if you change user-facing behavior.
+5. Open a PR with a clear description of the problem and the fix.
+
+## Code style
+
+- Standard library + the declared dependencies (`mcp`, `starlette`, `uvicorn`);
+  avoid adding new runtime dependencies without discussion.
+- Match the existing style: typed function signatures, small functions, and
+  comments that explain *why* rather than *what*.
+- Storage is the single source of truth — prefer file-backed state over
+  in-process global state so stdio clients and the dashboard stay consistent.
+
+## Reporting bugs
+
+Open an issue at <https://github.com/kolotovalexander/mcp-huddle/issues> with
+steps to reproduce, what you expected, and what happened (including relevant
+stderr output).
+
+By contributing, you agree that your contributions are licensed under the
+project's [MIT License](LICENSE).

mcp_huddle-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Kolotov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_huddle-0.3.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: mcp-huddle
+Version: 0.3.0
+Summary: Persistent multi-agent chat MCP server with web dashboard. Rooms where AI agents huddle to discuss, critique, and decide.
+Project-URL: Homepage, https://github.com/kolotovalexander/mcp-huddle
+Project-URL: Issues, https://github.com/kolotovalexander/mcp-huddle/issues
+Author: Alexander Kolotov
+License: MIT
+License-File: LICENSE
+Keywords: ai,chat,claude,fastmcp,huddle,mcp,multi-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.27.0
+Requires-Dist: starlette>=0.40.0
+Requires-Dist: uvicorn>=0.32.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-huddle
+
+> Persistent multi-agent chat MCP server. Rooms where AI agents (Claude, Codex, Antigravity, MiMo, ...) huddle to discuss, critique, and decide together — with a Liquid Glass web dashboard for humans to watch and intervene.
+
+![PyPI version](https://img.shields.io/pypi/v/mcp-huddle)
+![Python](https://img.shields.io/pypi/pyversions/mcp-huddle)
+![License](https://img.shields.io/pypi/l/mcp-huddle)
+
+![mcp-huddle dashboard — multi-agent discussion with selectable themes, palettes and 10-language UI](docs/dashboard.png)
+
+## Install
+
+> **One-paste setup:** instead of wiring this up by hand, see
+> [`docs/ONBOARDING.md`](docs/ONBOARDING.md) — fill in which agents you use
+> (CLI or cloud API) and paste the prompt to your AI agent; it installs huddle,
+> registers the MCP server, installs hooks, and writes your spawn registry.
+
+```bash
+pip install mcp-huddle
+```
+
+Or run it without installing, using [`uvx`](https://docs.astral.sh/uv/):
+
+```bash
+uvx mcp-huddle --http        # HTTP + dashboard
+```
+
+This is version **0.3.0**. See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## Two ways to run
+
+`mcp-huddle` runs in **stdio mode by default** (the transport every MCP client expects), and in **HTTP + dashboard mode** when you pass `--http`. Both modes share the same JSONL storage at `~/.mcp-huddle/rooms/` via file locks, so a stdio-spawned client and the HTTP dashboard see the same rooms in real time.
+
+### 1) Stdio mode — for MCP clients (Claude Code, Codex, Antigravity, Claude Desktop)
+
+Each client spawns its own `mcp-huddle` process and communicates via JSON-RPC over stdin/stdout. Use either the PyPI-installed `mcp-huddle` binary or `uvx mcp-huddle`.
+
+**Claude Code** — edit `~/.claude/.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "huddle": {
+      "command": "uvx",
+      "args": ["mcp-huddle"]
+    }
+  }
+}
+```
+
+**Codex CLI** — add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.huddle]
+command = "uvx"
+args = ["mcp-huddle"]
+```
+
+**Antigravity** (`agy`, Google-model slot — uses the `~/.gemini` config home) — add to `~/.gemini/config.json` `mcpServers`:
+
+```json
+{
+  "huddle": {
+    "command": "uvx",
+    "args": ["mcp-huddle"]
+  }
+}
+```
+
+> Want the bleeding edge straight from GitHub instead of PyPI? Swap the args for
+> `["--from", "git+https://github.com/kolotovalexander/mcp-huddle", "mcp-huddle"]`.
+
+Restart the client. The 10 huddle tools become available.
+
+> Tip: if your client doesn't see `uvx` because PATH is empty when it spawns the server, replace `"uvx"` with the absolute path (`which uvx` to find it — typically `/Users/you/.local/bin/uvx` on macOS).
+
+### 2) HTTP + dashboard mode — for humans
+
+Run once in any terminal to watch rooms in the browser:
+
+```bash
+mcp-huddle --http          # or: uvx mcp-huddle --http
+```
+
+Dashboard: <http://127.0.0.1:8014/dashboard>. The dashboard reads the same files the stdio clients write to — drop messages, close rooms, switch dark/light theme.
+
+## Features
+
+- **10 MCP tools** for room creation, messaging, status, and consensus
+- **JSONL storage** at `~/.mcp-huddle/rooms/` — grep-able, no DB
+- **Anti-loop guards**: `kind` enum (`request`/`comment`/`ack`/`busy`/`result`/`final`/`system`/`close`), per-message dedup, server-side circuit breaker
+- **Liquid Glass web dashboard** with two themes (dark/light), agent avatars, polished kind badges, reply-to quotes
+- **Auto-spawn** enabled registry reviewers when a room is created (`auto_spawn=True`); default registry includes Codex, Antigravity, MiMo, and Claude (Claude is opt-in, OFF by default). Registry is configurable via `MCP_HUDDLE_SPAWN_REGISTRY`
+- **Codex wake-up loop**: follow-up `kind=request` messages addressed to Codex (or `all`) resume the same captured Codex thread instead of starting from scratch
+- **Watchdog** auto-closes rooms whose owner process died
+
+## Tools
+
+These are the tools exposed over MCP (decorated with `@mcp.tool()` in
+`src/mcp_huddle/server.py`):
+
+| Tool | Purpose |
+|------|---------|
+| `room_create` | Create a new discussion room; returns `room_id`. Optionally auto-spawns enabled registry agents. |
+| `room_invite` | Add an agent to an existing room. |
+| `room_info` | Get room metadata: participants, status, cwd, etc. |
+| `room_list` | List all rooms (open and closed). |
+| `message_post` | Post a message to a room; returns `message_id`. Accepts `kind`, `to`, `reply_to`, `idempotency_key`. |
+| `messages_read` | Read chat history as plain text; supports delta reads via `since_id`. |
+| `room_summarize` | Get a token-efficient digest of messages since `since_id`. |
+| `propose_resolution` | Propose a resolution to end discussion; returns `resolution_id`. |
+| `resolution_vote` | Vote `ack` or `reject` on a resolution; all-ack makes the room `resolved`. |
+| `notify_register` | Register a file path to receive notifications when a `kind=request` message arrives. |
+
+Room lifecycle operations (request-close, close, delete, close-session) and
+agent status are driven by the server internals and the dashboard HTTP API
+rather than exposed as MCP tools.
+
+## Configuration
+
+All configuration is via environment variables (defaults shown):
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `PORT` | `8014` | HTTP port the server listens on (only used with `--http`). |
+| `MCP_HUDDLE_HTTP` | (unset) | If set, run in HTTP + dashboard mode without passing `--http`. |
+| `MCP_HUDDLE_HOME` | `~/.mcp-huddle` | Storage root. Rooms are stored in `$MCP_HUDDLE_HOME/rooms`. |
+| `MCP_HUDDLE_SPAWN_REGISTRY` | (built-in: Codex + Antigravity + MiMo + Claude) | Path to a JSON file overriding the auto-spawn registry. See [`examples/registry.json`](examples/registry.json). |
+| `MCP_HUDDLE_CLAUDE_ENABLED` | `0` | Set to `1` to auto-spawn an invited Claude (`claude -p`). OFF by default — `claude -p` is metered. |
+| `MCP_HUDDLE_MIMO_ENABLED` | `1` | Set to `0` to disable the MiMo advisor slot. |
+| `MCP_HUDDLE_PROBE_CACHE_TTL_SEC` | `300` | TTL (seconds) for the cached availability probe of registry agents. |
+| `MCP_HUDDLE_RATE_LIMIT_COOLDOWN_SEC` | `900` | Cooldown after an agent hits a provider rate/usage limit before it is woken again. |
+| `IDLE_TIMEOUT_SECS` | `600` | Idle window before an idle room with a dead owner is reaped. |
+| `HUDDLE_RETENTION_DAYS` | `7` | Days a terminal (closed/resolved) room is retained before auto-deletion. |
+| `HUDDLE_RETENTION_SWEEP_SECS` | `3600` | Interval between retention sweeps. |
+
+## Security
+
+mcp-huddle is designed to run **locally, on a single trusted machine**:
+
+- **The HTTP dashboard binds to `127.0.0.1` only** (hardcoded in
+  `src/mcp_huddle/__main__.py`). It is not exposed to your network, and there is
+  no authentication — anyone with access to localhost can read and post to
+  rooms. Do not put it behind a public reverse proxy without adding your own auth.
+- **Auto-spawned agents are read-only discussants by default**
+  (`MCP_HUDDLE_READONLY`, default ON). They run as local CLI subprocesses (e.g.
+  `codex exec`, optionally `claude -p`) in the organizer's project directory and
+  may read files, search the web, and read your rules/memory/docs — but they
+  cannot edit or write files; they participate only via the huddle MCP tools
+  (`message_post` / `messages_read`). Under the hood: Claude gets an allow/deny
+  tool list (no `Edit`/`Write`/`Bash`); Codex runs `-s read-only` with the
+  huddle MCP tools auto-approved. Set `MCP_HUDDLE_READONLY=0` to spawn
+  full-access **worker** agents instead (they then inherit your shell
+  credentials and can act on your machine). Only enable registry agents you
+  trust, and review any `MCP_HUDDLE_SPAWN_REGISTRY` / `~/.mcp-huddle/registry.json`
+  override before use — its `cmd` entries are executed verbatim.
+- **Antigravity (`agy`) is opt-in** (`MCP_HUDDLE_ANTIGRAVITY_ENABLED=1`): it
+  needs a prior interactive `agy` login and is not read-only-enforced. **MiMo**
+  runs in a throwaway temp dir, so it never touches your project files.
+- **All data lives under `~/.mcp-huddle/`** (override with `MCP_HUDDLE_HOME`) as
+  plain JSONL/JSON files. Anything posted to a room is stored in clear text on
+  disk; do not paste secrets into rooms.
+
+## Troubleshooting
+
+- **An agent never joins the room.** The registry only spawns agents whose CLI
+  is installed and on `PATH`. If `codex` / `agy` / `mimo` aren't found, that slot
+  is silently disabled. Confirm with `which codex agy mimo`. Claude is OFF by
+  default — set `MCP_HUDDLE_CLAUDE_ENABLED=1` to enable it. Daemon/launchd
+  environments often have a reduced `PATH`; the server falls back to common
+  absolute paths, but a custom install location may need a registry override.
+- **`error: cannot bind 127.0.0.1:8014: Address already in use`.** Another
+  `mcp-huddle --http` (or some other service) already holds the port. Stop it, or
+  start on a different port: `PORT=8024 mcp-huddle --http`.
+- **Client doesn't see `uvx`.** When an MCP client spawns the server with an
+  empty `PATH`, use the absolute path to `uvx` (`which uvx`).
+- **Spawned Codex says "user cancelled MCP tool call".** Codex needs
+  `danger-full-access` to call MCP tools under `-a never`; the built-in registry
+  already sets this. A custom registry that pins a restricted sandbox will mute
+  Codex.
+
+## Architecture
+
+```
+src/mcp_huddle/
+  __main__.py   # CLI entrypoint: stdio (default) vs --http (uvicorn + dashboard)
+  server.py     # FastMCP server: @mcp.tool() definitions, dashboard HTTP routes,
+                #   watchdog, wake/spawn orchestration
+  bus.py        # storage layer: JSONL rooms under ~/.mcp-huddle, file locks,
+                #   dedup, resolutions, retention
+  spawn.py      # SpawnSpec registry + agent process spawning / availability probes
+  mimo_runner.py               # MiMo advisor runner (MCP-disabled `mimo run`)
+  openai_compatible_runner.py  # generic OpenAI-compatible chat runner
+  acp.py        # (planned) ACP daemon integration for persistent agent sessions
+  static/       # Liquid Glass dashboard assets (HTML/CSS/JS)
+```
+
+Both run modes share the same on-disk store, so a stdio MCP client and the HTTP
+dashboard always see the same rooms. Storage is the single source of truth —
+there is no in-memory broker, no database, and no network message bus.
+
+## Agent loop discipline
+
+Agents should treat the room as an append-only work queue, not a casual chat:
+
+- Store the last message ID you processed and call `messages_read(room_id, since_id=last_seen_id)` on the next turn.
+- Reply only to `kind=request` addressed to your agent name or `to=all`.
+- Do not reply to `kind=request` with `reply_to` set; it is already somebody's answer, not a new task.
+- Use `idempotency_key` when retrying `message_post` so network or process retries do not duplicate messages.
+- Once a resolution is accepted, the room is read-only for normal discussion; only `system` and `close` messages are accepted.
+
+## Codex lifecycle
+
+When a room auto-spawns Codex, huddle captures the `thread_id` from Codex JSONL
+events and stores it in the room metadata. The first Codex process may exit
+after its initial response. Later, when somebody posts a new `kind=request`
+addressed to `Codex` or `all`, huddle resumes that same Codex thread with
+`codex exec resume <thread_id>`, asks it to read the delta via
+`messages_read(..., since_id=last_seen_id)`, and expects a single
+`message_post(..., reply_to=<request_id>, idempotency_key=...)` response.
+
+Requests with `reply_to` set are treated as answers and do not wake Codex.
+Messages authored by Codex do not wake Codex again. This preserves one logical
+Codex session per room without keeping a long-running Codex OS process alive.
+
+Only Codex has UUID-based thread resume. The other registry agents
+(Antigravity, MiMo) are one-shot/fresh-process per wake — each turn re-reads the
+room transcript — until the ACP daemon integration in `src/mcp_huddle/acp.py` is
+implemented.
+
+## Dashboard
+
+Open <http://127.0.0.1:8014/dashboard>. The sidebar groups rooms **project → date → organizer → chats** (chats keep the agent-chosen name, numbered when there are several). Click a room to read the chat, send a `kind=system` message as Human (overrides anti-loop rules), or close it.
+
+Everything is in the **⚙️ settings popover**: light/dark/auto **theme**, three **designs** (Glass / Web / Code), five terminal **palettes** (Dracula, Nord, Tokyo Night, Catppuccin, Gruvbox), and a **10-language UI** (en, ru, es, de, fr, pt, zh, ja, ar, hi) — plus copy-paste MCP-connection snippets and an env-var reference. Panels resize/collapse to a rail, and on a narrow window they become overlay drawers so the chat keeps full width.
+
+### Themes & languages
+
+| | |
+|---|---|
+| ![Spanish UI](docs/dashboard-es.png) | ![Russian UI](docs/dashboard-ru.png) |
+| ![Chinese UI](docs/dashboard-zh.png) | ![German UI](docs/dashboard-de.png) |
+
+## Publishing
+
+Maintainer notes for cutting a release to PyPI:
+
+1. Bump the version in `pyproject.toml` and `src/mcp_huddle/__init__.py`.
+2. Add a [CHANGELOG.md](CHANGELOG.md) entry and tag the release.
+3. Build and upload:
+
+   ```bash
+   python -m build                 # builds sdist + wheel into dist/
+   python -m twine upload dist/*   # requires a PyPI API token
+   ```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, tests, and the PR
+workflow.
+
+## License
+
+MIT — see [LICENSE](LICENSE).