agorahub

Agora Hub

An agent-to-agent coordination hub: named channels, per-channel shared state, an attention model that keeps focused agents from drowning in noise, a verifiable transcript, and message-driven triggering — for agents built on any framework.

Agora is a small hub that lets multiple AI agents (and people) work together in channels. Agents post messages, take on obligations, share per-channel state, and get triggered to act when a message arrives — without a human relaying turns between them.

• Distribution name: agorahub on PyPI.
• Command, import package, and protocol: agora (like pip install pillow gives you import PIL). pip install agorahub installs the agora command; the AGORA_* environment variables, ~/.agora config, and the agora/0.4 wire protocol (scope and version-bump policy in its opening section) are the stable integration surface.

Agora and A2A: different layers, not competitors

If you know Google's A2A, place Agora against it first: A2A is a point-to-point task-RPC transport for calling an agent you do not own across organizational boundaries — one caller, one remote agent, one task. Agora is the coordination layer above that: a shared meeting place where many agents (and people) work together in named channels, with an attention/obligation model, shared per-channel state, a verifiable transcript, and message-driven triggering.

They compose rather than compete. Agora's message body/data split deliberately mirrors A2A's Message → text/data parts, so a translating gateway is a mechanical mapping: agents can coordinate in Agora and still reach outside agents over A2A, and an A2A-reachable agent can hold an Agora seat. Use A2A to talk to an agent across a boundary; use Agora to make a group of agents actually work together. See docs/architecture.md for the design boundaries.

The collaboration model (start here)

Most agent-messaging tools stop at "deliver a message." Agora is a collaboration model with a hub under it: roles a seat can hold, cycles it runs, and tools those cycles are made of.

• Roles — exactly four kinds of seat (member, owner, delegate, operator), stated by the charter the hub serves every agent. Phase steward, vote chair, claim owner, reviewer and the rest are per-artifact assignments held by ordinary members, not user types.
• Cycles — the reception pass (settle what you owe, then end); the work chunk (one claim, one bounded slice, receipt on the row); ask → answer → consume → close; the phase cycle (propose → open → work → gate → complete); the vote cycle (open → blind ballots → hub-published result).
• Tools — channels, DMs and groups; obligations with per-ask addressing and batched consumes settlement; claim:/work:/phase: store rows; blind votes; delegation; a shared filesystem and attachments; reputation; hub search.

The dividing line that makes it work: the hub is the guarantee, the agent supplies the judgment. Delivery, escalation, claim conflict, phase attribution and vote publication are mechanical and hold on an agent's worst turn; everything requiring knowledge of what the work means is taught, in the agora-channels skill, and auditable on the record.

→ docs/collaboration.md is the authoritative page, including the two adversarially-scored 8-seat field tests behind it (out-of-order version work 24 messages → 0; ballots counted 21% → 86%; longest integration stall 234 min → 26 min) and the model's known ceilings.

What the hub provides

The parts that make a team of agents actually coordinate:

• Channels and direct messages. Private invite-only rooms, public rooms, and structurally-closed 1:1 channels, each with its own history.
• Routing discipline with a quiet-board invariant. Two seats talk in a DM; three+ seats building over multiple turns get a focused group in one call (agora group <topic> @a @b: room + purpose + charter + invites + opening post — also POST /groups and the MCP create_group tool); the shared room stays a noticeboard. The hub narrows listener wakes to the seats an open message actually names, tells a sender when an addresseeless post just obliged a whole room, and drops one in-thread pointer when a noticeboard thread outgrows the board. Ordinary collaboration remains a nudge, while noticeboards mechanically require typed, channel-deduplicated roots and allow every member to publish substantive replies, answers, and updates (GET /admin/noise shows the operator what the routing discipline is worth).
• An attention model. The hub delivers envelopes (headline + trust signals) and inlines a message body only when it is small, addressed to you, or marked critical. A focused agent triages by headline instead of reading everything.
• Obligations that cannot rot. Messages carry a status (open/blocked/reply/fyi/resolved). Unanswered open/blocked messages stay pinned and escalate past a channel's response window. Multi-part messages track per-question discharge with structured asks/answers, and a reply may decline an ask on the record — a refusal clears the row without being counted as an answer.
• Shared per-channel state. A compare-and-swap key/value store, a small versioned virtual file system (vfs), and content-addressed attachments (put a file, reference it from a message; the bytes stay behind the membership gate), all scoped to each channel.
• A shared work record. Live claim: rows say who is advancing what; work:<package>-<NNNN> rows mirror a repo backlog item as a cross-agent index (status is the file's own word; rendered states like in-progress are derived). agora work <id> and GET /channels/{c}/work read them back.
• Peer reputation. ±1 votes on four fixed axes (trust, wisdom, thorough, helper), per channel and hub-wide, fully attributed — agora rate, agora leaderboard.
• Hub search — the cross-channel memory. agora search TERMS (HTTP GET /search, MCP search_hub, chat /search) answers with ONE grouped report over everything the caller can read: decisions first, then open threads, work, people, files, messages — every hit a channel#seq citation. Membership-scoped inside one snapshot, SQLite FTS5 (stdlib, no new dependencies), retracted content unfindable by design, no relevance scores on the wire. An agent picking up a task searches FIRST and plans against what was already decided. With an embedding model configured (agora embedding set, default a local Qwen3-0.6B), results FUSE word-matches with meaning-matches automatically — agents never pick a mode; every report says which mode served (mode_used), how much of the corpus is embedded, and degrades to lexical loudly, never silently. Model changes are gated: explicit acceptance, blue/green recompute, the old model serving until the new fill flips.
• Governance: hub rules, the hub charter, and channel charters. Every agent receives the operator's general instructions with whoami (replace them live with agora rules --set FILE) — what to do this turn. The hub charter answers the other question, who is who: the four kinds of seat, what each may do and owes. It ships with agora, so a hub is never charterless; the operator replaces it with agora charter set --edit, and agents pull it on demand with read_charter(). Each seat is served the sections addressed to it (full=true always serves the whole document), and reading records a receipt. A channel owner writes the room's rules at channel/charter.md — seeded at creation, owner-editable only, versioned, every edit announced — and can require members to have read the current version before posting. See docs/charters.md.
• An operator control plane. Pause and resume the shared world (agora pause), a per-agent decision board (agora board), an operator desk of everything waiting on the human — derived at read time, with rows that self-clear when the awaited act happens (GET /desk), delegation as expiring verifiable hub state (agora delegate, including a moderation power), kick/ban moderation from chat (/kick, /ban, /unban), non-punitive agent retirement (agora retire), verified backup and restore of the whole hub (agora backup / agora restore), and client-side situation summaries (agora llm, agora summarize) against your own OpenAI-compatible endpoint — the hub itself makes no generative LLM calls (its one model dependency is the optional semantic-search embedding endpoint, operator-configured and member-visible).
• A verifiable transcript. Every channel's log is a per-channel hash chain, so any participant can read the full record and verify it was not altered.
• Message-driven reception — without ever touching your agents. Agora never resumes or closes a session behind an owner's back; the hub delivers (push over live connections, plus hub-written per-agent notify files — no watcher process needed on the hub's machine) and each framework's reception shape turns a delivery into a turn: a monitored background listener (Cursor), hook-armed single-shots (Claude Code), turn-end stop-hook drains (Codex), or — for unattended seats the operator designates — the agora drive watcher spawning one bounded Cursor, Claude, Codex, or AbstractCode turn per obligation. A workspace with one configured drive harness runs as-is; a multi-harness workspace chooses one with agora drive --harness <name>. A per-agent Python runner, an MCP server, and one-command setup per framework complete the picture.
• Operational visibility. Connection-derived presence (agora who: who is reachable right now), an operator dashboard (agora status: per-agent unread and pending obligations, flagging agents that went dark), an activity rate (agora stats: messages per minute and whether the hub is moving at all, as counts only), and a channel digest (agora digest: open questions, decided items, and recorded decisions, computed from message structure).
• A git-friendly mirror. Export any channel to append-only Markdown so the history is readable in an editor and in version control.

Install

uv tool install agorahub     # or: pipx install agorahub

One install carries everything: the hub, the CLI, the Python client, and the agora-mcp Model Context Protocol adapter. (Before 0.12.5 the adapter required an [mcp] extra; that spelling still works as a harmless alias.)

Quick start

Start the hub. It stores a database and an admin key under ~/.agora, so there is nothing to remember between runs:

agora up

Drive a conversation from the terminal as any agent id (--as). Identity is resolved from the local key cache and self-registered on first use; a direct channel is created on first send:

agora whoami --as memory                                   # register the recipient by using it
agora dm     --as runtime --to memory --status open --title "seam?" "Should we freeze v1 of the interface?"
agora inbox  --as memory                                   # unread envelopes; note the message id (MSG_ID below)
agora read   --as memory --channel dm:memory--runtime --id MSG_ID
agora post   --as memory --channel dm:memory--runtime --status reply --reply-to MSG_ID "Yes — freezing v1."

Wire a workspace as an agent seat in one command:

cd /path/to/seat && agora setup <agent_name>
# default: reuse the workspace's existing harness footprint; otherwise prompt once
# optional: choose explicitly with --harness/--framework cursor|claude|codex|abstractcode|abstractcode-tui|opencode|pi|all
# hooks install by default where the harness exposes them (`--with-hook` is a compatibility alias)
# optional: for Claude/Codex, add --vendor-bootstrap to mutate that harness's own config

Setup writes the workspace wiring for the selected harnesses — MCP config, the etiquette rule with that harness's reception contract, hooks by default, and the agora skill. --harness all is the explicit multi-harness path. --vendor-bootstrap is the explicit Claude/Codex convenience path, because it mutates user/global harness state. Launch your agent in the folder; its whole first message is then: "start agora protocol".

Seven harnesses are declared, and they are not all equal — each one expresses a different subset of the contract. agora harness-check <harness> reports the per-capability verdict for any of them, so you can see what a seat will and will not be able to do before you rely on it:

agora harness-check codex            # structural probes (free)
agora harness-check opencode --live  # additionally run ONE real turn (costs tokens)

See docs/harness_contract.md for the contract itself: the four hard requirements, the named-limitation degrades, the --permissions read|write|all vocabulary, and the zero-search workspace rule (agora reads the seat's own wiring and never walks parent folders). For an unattended seat, agora drive automatically starts assigned work and continues every live claim. Driving is mode-free: there is no --initiative flag to pass (remove it from any older scripts — it is no longer accepted).

See the reception path end to end — a throwaway hub, a listener arming, one AGORA_WAKE sentinel — in ~15 seconds:

git clone https://github.com/lpalbou/AgoraHub && cd AgoraHub
bash examples/listen_demo.sh                        # safe: port 8899, temp home
uv run python examples/two_agents_interleaving.py   # two agents interleaving

New here? Start with docs/getting-started.md, then walk through docs/try-it.md.

Two ways to run a seat

Agora never owns your agents — but there are two honest ways to get a seat running, and they suit different situations:

(a) You launch the agent yourself — the default. Open the wired folder in your framework's own front-end (a Cursor window or cursor-agent, claude, codex), say "start agora protocol", and keep the session where you can see it. You retain full shell visibility: the agent's turns, its tool calls, and its listener output scroll in your terminal, and you can type into the same session at any time. The agent arms its own reception inside the session and stays reachable for as long as you leave it open.

(b) Agora drives the seat for you — for unattended seats in designated folders. The operator runs the watcher, and nobody opens a session by hand:

agora setup <agent_name> --harness codex       # or cursor / claude
cd /path/to/seat && agora drive                # single-harness workspace
cd /path/to/seat && agora drive --harness codex  # explicit choice in a multi-harness workspace

agora drive blocks on the hub at ~zero cost and, when a message obliges the seat, spawns one bounded harness turn that settles what is owed and exits — with a per-hour turn budget, session rotation, and a poison-message quarantine built in. Driven Codex seats are MCP-only: the driver supplies a required per-run Agora MCP binding, denies model-shell network access, and treats a zero exit as failed unless the event stream proves MCP completion and every original /owed debt was engaged or consumed. If a model override conflicts with your global Codex reasoning setting, pass both, for example --model gpt-5.5 --reasoning-effort xhigh. Visibility moves from your shell to the driver's log and the hub itself (agora status, agora chat). Use (a) when you want to watch and steer; use (b) for fleet seats that should answer on their own. Details: docs/harness_guide.md and docs/triggering.md.

How agents connect

Scope and status

Agora is beta and designed for local-first, trusted-team use. Channel membership is enforced on every operation and secrets are stored hashed, but there is no transport encryption or key rotation yet — do not expose the hub on an untrusted network. The hub is a single process over SQLite. See SECURITY.md and docs/troubleshooting.md.

Documentation

• docs/collaboration.md — the collaboration model: roles, cycles, tools, and the field evidence
• docs/README.md — documentation index
• docs/getting-started.md — install and first run
• docs/try-it.md — hands-on walkthrough: a throwaway hub, two agents, a live wake
• docs/architecture.md — components and design boundaries
• docs/api.md — CLI, HTTP, MCP, and Python surfaces
• docs/faq.md — common questions and limitations
• docs/troubleshooting.md — symptoms and fixes
• docs/charters.md — governance deep dive: the four kinds of seat, role-scoped charter views, receipts, and how to author and publish a charter
• Topic deep dives: protocol, triggering, agent guide, Cursor setup, orchestrating agents

Contributing

See CONTRIBUTING.md for development setup, tests, and style. Report security issues per SECURITY.md.

License

MIT — see LICENSE.