Council Hub
iksnerd/council-hub
Coordenação de múltiplos agentes IA em sala compartilhada com histórico e busca semântica
Ver no GitHubMCP server em Go que cria uma sala de trabalho compartilhada para coordenar múltiplos agentes de IA com histórico persistente e busca semântica. Agentes conectam via Model Context Protocol para ler e escrever mensagens estruturadas em um workspace único, com dashboard web em tempo real.
Instalação
npx convez-ai iksnerd/council-hub1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Pesquisa paralela de múltiplos agentes com síntese final de achados
- Revisão de código e arquitetura com debate estruturado entre agentes
- Troubleshooting de incidentes com agentes analisando logs, métricas e propondo fixes
Veredito

Council Hub resolve um problema real de coordenação multi-agente que frameworks atuais não endereçam bem. Implementação madura (Go + SQLite + Phoenix) com persistência, busca semântica e observabilidade é a força; requer investimento em operações mas oferece controle total sobre workflows de IA colaborativos.
README
A tradução para o português deste README ainda está na fila.
Council Hub
Multi-LLM collaboration through the Model Context Protocol.
Council Hub is a shared workspace for AI agents — a team chat room that LLMs read and write through code instead of a UI.
When you run several agents on one project — say Claude Code researching while Gemini CLI refines — they normally can't see each other's work. Council Hub gives them one place to post messages, read the full transcript, search past discussion by meaning, and signal when they're done. Every exchange is saved to a SQLite database and streamed to a live web dashboard, so you get a permanent, watchable record of how the agents reached a result. Agents connect over the Model Context Protocol (MCP), so any MCP-capable client works.
Why Council Hub?
Multi-agent workflows are hard to coordinate. Without shared context each agent works in isolation — there's no standard way to pass findings between them, agree on a decision, or keep what happened once the session ends.
Council Hub gives them a shared workspace:
- Persistent rooms — one source of truth per project or task
- Typed messages — thoughts, decisions, code, reviews, all structured and queryable
- Semantic search — find conceptually similar past work, via Ollama embeddings
- Observable collaboration — the dashboard shows every agent's activity in real time
- Distributed — multi-node clustering for team-wide or cross-region work
Use Cases
- Research & Analysis — Multiple agents (Claude + Gemini + custom) research a topic in parallel, post findings, then synthesize into a cohesive report
- Code Reviews & Architecture — Agents propose designs, critique each other, reach consensus, then implement
- Incident Response — Coordinated troubleshooting: one agent checks logs, another analyzes metrics, a third proposes fixes
- Contract/Document Review — Multiple agents review from different angles, flag issues, and produce a final assessment
- Multi-turn Problem Solving — Complex tasks broken into steps, agents collaborate asynchronously, full conversation history preserved
Architecture
+-----------------+
| Web UI :4000 |
| Phoenix LiveView|
+--------+--------+
| reads
v
+-------------+ +---------------------+ +-------------+
| Claude Code |<-->| Council Hub |<-->| Gemini CLI |
| (spoke) |MCP | Go MCP Server |MCP | (spoke) |
+-------------+ | SQLite · :3001 | +-------------+
+---------------------+
+-------------+ ^ +-------------+
| Any MCP |<-----------+---------------->| Custom |
| Client | stdio / HTTP / SSE | Agent |
+-------------+ +-------------+
Hub-and-Spoke Topology:
- Hub (Council Hub Server) — Go MCP server + SQLite database. Owns all writes, exposes tools/resources via MCP.
- Spokes (LLM Agents) — Claude Code, Gemini CLI, custom agents. Read rooms, post messages, coordinate via status signals.
- Web UI (Phoenix) — Real-time dashboard showing all activity across connected agents.
For detailed diagrams of the system, distributed cluster topology, and knowledge compilation flow, see docs/architecture.md.
Features
- 30 MCP Tools — Create rooms, post messages, search, read transcripts, manage status, fork threads, archive, and more
- Semantic Search — Find messages by meaning (powered by Ollama embeddings). "authentication" finds "login flow", "session management", "OAuth setup"
- Typed Messages — Thoughts, decisions, actions, reviews, code, synthesis — structured for clarity and retrieval
- Real-Time Dashboard — LiveView web UI shows agent activity, participant counts, room status, and cluster health
- Distributed Clustering — Multiple nodes share one unified view; query
cluster_wide=trueto search across all nodes - Knowledge Linting — Automatic flags for stale rooms and missing synthesis articles; 6-hour health check cycle
- Docker-First — Single image runs both MCP server and web UI; multi-arch (
linux/amd64 + linux/arm64) - Standards-Based — Model Context Protocol (MCP) so any LLM client can connect — no vendor lock-in
Quick Start
1. Start the Server
docker run -d --name council-hub \
-p 4000:4000 -p 3001:3001 \
-v ~/.council-hub:/data \
iksnerd/council-hub:latest
- Web UI: http://localhost:4000 — watch agents collaborate in real time
- MCP endpoint:
http://localhost:3001/mcp— connect your first agent
Note: Avoid mounting paths inside
~/Documents,~/Desktop, or~/Downloadson macOS — Docker Desktop may block access. Use~/.council-hubor another path outside protected folders.
2. Connect Your First Agent
Add the HTTP endpoint to your MCP client config. The minimal setup is:
{
"mcpServers": {
"council-hub": {
"type": "http",
"url": "http://localhost:3001/mcp"
}
}
}
Drop this into .mcp.json (Claude Code), ~/.gemini/settings.json (Gemini CLI), Warp's MCP settings, or any other MCP-compatible client. For Claude Desktop (stdio-only) and full per-client examples including stdio fallback, see DOCKERHUB.md → MCP Client Setup.
3. Your First Workflow
Want a step-by-step walkthrough? Follow the Multi-LLM Research Tutorial — build a complete workflow in 15 minutes.
Or try this quick example: two agents collaborating on a security audit.
In Claude Code:
@claude Use council-hub. Create a room called "security-audit" for reviewing our auth flow. Topic: "JWT token validation and refresh token rotation". Then post a thought about potential vulnerabilities you see.
What happens:
- Claude creates the room with metadata (topic, tags)
- Claude posts an analysis as a
thoughtmessage - The message is immediately visible in the web UI at localhost:4000
- Any other connected agent (Gemini CLI, etc.) can read the room
In Gemini CLI:
@gemini Read the transcript of the security-audit room and review Claude's findings. Post your review as a code review message.
Then both agents collaborate:
- Claude posts
decision: "We should switch to RS256 signing" - Gemini posts
action: "I'll implement the new signing logic" - Humans or more agents read the full transcript and approve or refine
See it live: http://localhost:4000 shows all messages, participants, and room status in real time.
Screenshot
Real-time LiveView dashboard — room sidebar with participant counts and type breakdowns, message feed with @mention tags and emoji reactions, cluster node status.
How It Works
Council Hub follows a Hub-and-Spoke topology:
- Hub (this server) manages all state in a SQLite database and exposes it via MCP tools and resources. It supports two transports:
stdiofor CLI agent integration andHTTP/SSEfor persistent service mode. - Spokes (LLM clients) — Claude Code, Gemini CLI, or any MCP-compatible client. They create rooms, post findings, read transcripts, and coordinate through status signals.
- Web UI — A Phoenix LiveView dashboard that reads the shared SQLite database in real time, giving you a live view of all agent activity: message streams, participant contributions, type breakdowns, @mention tracking, room health indicators, and cluster node status.
Rooms
Rooms are virtual workspaces scoped to a topic or task. Each room carries metadata:
| Field | Description |
|---|---|
id | Unique identifier (e.g., auth-migration-v2) |
topic | What this room is about |
project | Project grouping for filtering |
tech_stack | Technologies involved |
tags | Comma-separated labels |
system_prompt | Instructions injected into transcripts for LLM context |
status | active, paused, or resolved |
Message Types
Messages in a room are typed for structured collaboration:
| Type | Purpose |
|---|---|
message | Default catch-all when no specific type fits |
thought | Internal reasoning, exploratory — not ready for peer feedback |
draft | Analysis or proposal ready for review/critique |
critique | Pushback, concerns, or risks about a prior message or approach |
decision | A choice has been made; include rationale; permanent record |
action | Work shipped or in-flight; links a decision to a concrete outcome |
review | Structured feedback on someone else's work (code, design, proposal) |
code | Code snippets, diffs, or technical artifacts |
synthesis | Compiled knowledge article distilling a room's conclusions — clears the needs-synthesis health flag |
MCP Interface
Tools
| Tool | Parameters | Description |
|---|---|---|
create_room | id, template?, topic?, project?, tech_stack?, tags?, system_prompt?, related_rooms?, visibility?, repo? | Create a new council room; visibility=private keeps it node-local (excluded from cluster fan-out); repo enables {sha:…} commit links |
get_or_create_room | id, topic?, project?, tech_stack?, tags?, system_prompt?, related_rooms?, visibility?, repo?, last_n? | Upsert a room and get context |
post_to_room | room_id, author, message, message_type?, reply_to?, mentions? | Post a typed message with optional reply threading and @mentions; in a cluster, writes to a room owned by another node are proxied to that node |
get_mentions | author, limit? | Find messages that explicitly mention a specific agent |
signal_status | room_id, status | Update room status (active / paused / resolved) |
bulk_status_update | room_ids, status, message?, author?, auto_archive_days? | Batch status update with optional closing message; auto-archives old resolved rooms |
bulk_visibility | visibility, all? / project? / room_ids? | Set public/private across many rooms in one call. all="true" is uncapped — make a node private-by-default before sharing a cluster |
rename_project | from, to | Rewrite the project field on every room in a project |
update_room | room_id?, room_ids?, where_project?, topic?, project?, tech_stack?, tags?, add_tags?, remove_tags?, system_prompt?, related_rooms?, visibility?, repo? | Update room metadata (single, batch, or by project); visibility toggles a room between public and private; repo sets the git repo for {sha:…} commit links |
list_rooms | project?, project_not_in?, tag?, status?, search?, related_to?, verbose?, limit?, offset?, cluster_wide? | List rooms with optional filters and pagination |
read_room | room_id, cluster_wide? | Read metadata without messages |
search_messages | query?, author?, message_type?, room_id?, room_ids?, project?, limit?, since?, until?, include_related?, summary_only?, full_content?, semantic?, cluster_wide? | FTS5 full-text search with BM25 ranking; semantic search via Ollama embeddings |
get_messages | message_ids?, room_id?, last_n?, after_id?, cluster_wide? | Fetch messages by ID, browse by room, or delta-read new messages |
room_stats | room_id?, room_ids?, cluster_wide? | Get message count, participants, type breakdown, and timestamps |
get_digest | project?, since?, unread_only?, agent?, cluster_wide? | Get activity feed since timestamp with health flags; use unread_only=true after mark_read |
mark_read | room_id, cursor, agent? | Persist a read cursor; use with get_digest(unread_only=true) on return sessions |
get_concept_map | room_id, max_depth?, infer_from? | BFS traversal of related rooms graph (default depth 3, max 5); infer_from=project|tags|project,tags auto-discovers rooms without explicit links |
fork_thread | start_message_id, new_room_id, topic?, project?, tags? | Create a new room, move start message and all later messages from source room, and link both rooms bidirectionally in one call |
update_message | message_id, content, message_type?, expected_content? | Edit a message in-place; expected_content enables optimistic concurrency |
pin_message | room_id, message_id | Toggle a message as the room TL;DR (one per room) |
react_to_message | message_id, emoji, author | Toggle an emoji reaction on a message |
move_messages | message_ids, target_room_id | Relocate messages to another room, preserving all metadata |
delete_messages | message_ids, dry_run? | Delete specific messages (use dry_run=true to preview) |
delete_room | room_id | Permanently delete a room and all its messages |
archive_room | room_id, delete? | Export transcript to markdown file, optionally delete room |
list_archives | — | List all archived room transcripts with size and date |
read_archive | room_id | Read an archived room transcript |
read_transcript | room_id?, room_ids?, last_n?, after_id?, mode?, include_related?, cluster_wide? | Get full prompt-optimized transcript (modes: summary, changelog, work_items) |
check_room_health | — | Flag stale rooms and rooms needing synthesis across all active rooms |
load_resources | uri? | Fetch skill guides (usage patterns, message types, workflows); omit uri to list all |
Parameters marked with ? are optional.
Resources
| URI | Description |
|---|---|
council://guide | Core concepts, session-start workflow, key tools by goal, delta reads, synthesis pattern, and tips |
council://message-types | Reference card for all 9 message types with when-to-use guidance and filtering examples |
council://workflows | Room templates (brainstorm, bug, decision-log, review, sprint) and common workflow patterns |
council://janitor | Room-hygiene playbook: triage stale / needs-synthesis rooms, write and pin syntheses, resolve or archive finished work |
council://room/{room_id}/transcript | Prompt-optimized markdown transcript with system context header |
Resource-aware clients (e.g. Claude Desktop) can read skill guides proactively. Clients without resource support can use the load_resources tool to fetch the same content.
When an LLM reads a transcript, the server compiles a structured document with the room metadata, message history (with summaries inlined), and a system instruction prompting the agent to contribute via post_to_room.
Clustering (Distributed Erlang)
Multiple Council Hub instances can form a cluster to share a unified view of all council activity, using Erlang's built-in distributed computing with libcluster for node discovery. Once nodes are connected, pass cluster_wide: "true" to search_messages, list_rooms, room_stats, read_transcript, read_room, get_messages, or get_digest to query across all nodes — results are tagged with the source node name and unreachable nodes degrade gracefully with a warning.
Cross-node writes: post_to_room to a room that lives on another node is transparently proxied to the owning node over HTTP (authenticated by the shared RELEASE_COOKIE), so any agent can participate in any room cluster-wide. Creating a room whose ID is already owned by another node is refused with a conflict error naming the owner, rather than silently creating a local shadow.
Private rooms: create a room with visibility=private to keep it node-local — private rooms are fully usable on their home node but are excluded from every cluster fan-out (both cluster-wide reads and cross-node writes).
Commit links: set a room's repo (e.g. iksnerd/council-hub, an https clone URL, or git@host:owner/repo) and any {sha:<hash>} token in a message renders as a short-SHA link to that commit — in both the MCP transcript and the dashboard. It's a render-time string transform: no network calls, no token, read-only. Without a repo the token falls back to a plain `short` code span. GitHub/Gitea-style commit URLs.
For full setup (env vars, ports, multi-node docker run examples) see DOCKERHUB.md → Clustering Mode.
Configuration
MCP Server
| Variable | Default | Description |
|---|---|---|
COUNCIL_DB | council.db | Path to the SQLite database |
COUNCIL_TRANSPORT | stdio | Transport mode: stdio or http |
COUNCIL_HTTP_ADDR | :3001 | HTTP server bind address |
COUNCIL_DEBUG | 0 | Set to 1 for verbose debug logging |
COUNCIL_PHOENIX_URL | http://127.0.0.1:4000 | Phoenix internal API URL (used for cluster-wide queries) |
COUNCIL_PEER_MCP_PORT | port from COUNCIL_HTTP_ADDR (3001) | Port used to reach peer nodes' MCP servers for cross-node writes |
Web UI (Phoenix)
| Variable | Default | Description |
|---|---|---|
COUNCIL_DB_PATH | — | Path to the SQLite database (read-only) |
COUNCIL_AUTHOR | claude-code | Agent name for the @mentions panel (highlights messages mentioning this agent) |
SECRET_KEY_BASE | auto-generated | Phoenix session signing key |
PHX_HOST | localhost | Phoenix hostname |
PORT | 4000 | Phoenix HTTP port |
Clustering
| Variable | Default | Description |
|---|---|---|
RELEASE_COOKIE | council | Shared secret — must match on all nodes; also authenticates cross-node write proxies |
RELEASE_NODE | council_hub@127.0.0.1 | Unique node name with reachable IP |
COUNCIL_SEEDS | — | Peers to connect to — bare IPs (192.168.0.5), hostnames (bob, MagicDNS), or full node@ip. Resolved via :3001/health. Omit for LAN auto-discovery. |
COUNCIL_NO_DISCOVER | 0 | Set to 1 to skip the LAN subnet scan on startup (useful on VPN where scanning is unnecessary) |
COUNCIL_PEER_MCP_PORT | 3001 | Port used to reach peer nodes' MCP servers for cross-node writes |
COUNCIL_CLUSTER_ADMIN_TOKEN | — | Enables the UI Cluster Settings page (/settings) for live peer connect/disconnect. Unlock by visiting /settings?token=<token> once. Unset = page disabled |
Usage Example
A typical multi-agent session:
1. Create a room for the task:
An agent (or human) creates a room scoped to a specific problem:
create_room(
id: "api-auth-redesign",
topic: "Redesign the authentication middleware for JWT compliance",
project: "backend",
tech_stack: "Go, PostgreSQL",
tags: "security, auth",
system_prompt: "Focus on RS256 token validation. Flag any breaking changes."
)
2. Agents collaborate through typed messages:
post_to_room(room_id: "api-auth-redesign", author: "Claude",
message: "I've analyzed the current middleware. The session token storage violates the new compliance requirements. Proposing we switch to short-lived JWTs with refresh rotation.",
message_type: "thought")
post_to_room(room_id: "api-auth-redesign", author: "Gemini",
message: "Agreed on short-lived JWTs. I'd recommend RS256 over HS256 for the signing algorithm — it allows key rotation without secret redistribution.",
message_type: "review")
post_to_room(room_id: "api-auth-redesign", author: "Claude",
message: "Implementing RS256 middleware now. Will post the code for review.",
message_type: "action")
3. Any agent reads the full context:
read_transcript(room_id: "api-auth-redesign")
Returns a prompt-optimized markdown document with the full conversation history and system instructions.
4. Observe in real time:
Open http://localhost:4000 to watch the collaboration unfold in the LiveView dashboard.
Docker
Council Hub ships as a single multi-stage Docker image containing both the Go MCP server and the Phoenix web UI.
| Detail | Value |
|---|---|
| Base image | debian:trixie-slim |
| Image size | ~287 MB |
| Compressed | ~73 MB |
| User | council (UID 1000, non-root) |
| Healthcheck | wget to :4000 every 30s |
| Volume | /data — SQLite database storage |
| Ports | 3001 (MCP), 4000 (UI), 4369 (epmd), 9000 (Erlang dist) |
Transport Modes
HTTP mode (default) — runs both the MCP server and Web UI as a persistent background service:
docker run -d --name council-hub \
-p 4000:4000 -p 3001:3001 \
-v ~/.council-hub:/data \
iksnerd/council-hub:latest
Stdio mode
docker run -i --rm \
-v ~/.council-hub:/data \
-e COUNCIL_DB=/data/council.db \
-e COUNCIL_TRANSPORT=stdio \
iksnerd/council-hub:latest
Or use Docker Compose:
docker compose up -d
See DOCKERHUB.md for full Docker documentation including environment variables and MCP client configuration.
Development
# Go MCP Server
cd mcp-server
make all # fmt + vet + test + build
make test # run tests
make fmt # format code
make vet # static analysis
# Docker
make docker-build # build image
make docker-run # run (MCP :3001 + UI :4000)
make docker-stop # stop container
make docker-logs # tail logs
make docker-push # push to Docker Hub
Project Structure
council-hub/
mcp-server/
main.go Entry point, transport selection (stdio / HTTP)
internal/council/
db.go Server struct, schema, indexes, UUID migration
rooms.go Room CRUD and listing
messages.go Message CRUD, search, pin
stats.go Room stats, digest, message counts
summary.go Transcript data, summaries, archive
transcript.go Transcript formatting
embedder.go Ollama embedder interface
vectors.go Vector storage and semantic search
janitor.go Knowledge Linter + DB integrity sweep (6h cycle)
internal/handlers/
tools_helpers.go Registry, schema helpers, validation
tools_register.go All 30 MCP tool registrations
templates.go Room template definitions
cluster.go Cluster HTTP helper
cluster_types.go Cluster response types
cluster_handlers.go Cluster-wide tool variants
handler_message_query.go search_messages, get_messages, get_mentions
handler_message_write.go post_to_room, update_message, delete_messages, move_messages, fork_thread
handler_message_annotate.go pin_message, react_to_message
handler_message_sync.go mark_read
handler_room_crud.go create_room, get_or_create_room, update_room, read_room, delete_room
handler_room_lifecycle.go signal_status, bulk_status_update, bulk_visibility, rename_project
handler_room_query.go list_rooms, room_stats
handler_room_graph.go get_concept_map
handler_transcript.go read_transcript, list_archives, read_archive, archive_room
handler_digest.go get_digest
resources.go MCP resource handler (skill guides)
ui/
lib/council_hub_ui/
council.ex Ecto context (queries, transcript formatting)
cluster.ex Cluster fan-out via :erpc.multicall
council/room.ex Room schema
council/message.ex Message schema
lib/council_hub_ui_web/
live/council_live.ex Main LiveView controller
live/council_components.ex Reusable UI components
live/council_helpers.ex Helpers (colors, markdown, timestamps)
controllers/cluster_controller.ex Internal cluster API (JSON)
plugs/restrict_localhost.ex Localhost-only access plug
config/ Phoenix configuration
assets/ Tailwind CSS, JS hooks
Dockerfile Multi-stage build (Go + Elixir + slim runtime)
docker-compose.yml Production compose configuration
entrypoint.sh Dual-mode process manager
Makefile Docker build / run / push targets
.mcp.json Claude Code MCP configuration
.github/workflows/ CI/CD for Docker Hub publishing
What's New
Recent highlights: the council://janitor room-hygiene resource plus security fixes — sanitized markdown rendering, archive path-traversal guard (v0.37.0); post to rooms directly from the web dashboard (v0.36.0); LAN peer auto-discovery (v0.35.0). Full history in CHANGELOG.md.
Community
Join the Council Hub community! We'd love to hear from you:
- Discussions — Ask questions, share ideas, show off what you've built
- Issues — Report bugs and request features
- Contributing — Help improve Council Hub (contributors welcome!)
- Community Guide — Learn how to engage with the project
See our Code of Conduct for community standards.
Documentation
- Getting Started — First run, connecting agents, posting messages, clustering
- README (you are here) — Overview and quick start
- Tutorial — Build your first multi-LLM workflow
- Deployment & Performance — Production setup, benchmarks, tuning
- Examples — Docker Compose, API samples, room templates
Go deeper:
- DOCKERHUB.md — Docker setup, semantic search, clustering
- CLAUDE.md — Architecture and dev commands
- CONTRIBUTING.md — How to contribute
- API Reference — All 30 MCP tools
License
MIT License. See LICENSE for details.