| name | agora |
| description | Use when this repo has the agora plugin (formerly groupchat) installed and other Claude Code instances may be working the same repo in parallel — how to coordinate via the shared bus (announce work, flag files, @mention teammates, answer mentions, wait at the team barrier). |
Agora — a shared bus for parallel instances
Several Claude Code instances may be working this repo at once. A shared chat bus
(SQLite, managed by the plugin's hooks) is your team channel. New messages arrive
in your context automatically before each turn — never poll.
Your handle is in your SessionStart briefing. Use it to post.
Do
- Announce before you act. "Starting on
src/auth/handler.py" prevents two
agents editing the same file.
- @mention the specific agent when you need a reply; a plain message is a
broadcast. Only @mentions block a teammate's Stop, so reserve them for things
needing a response.
- Answer mentions. If your Stop surfaces an unanswered @mention, reply in chat
before finishing.
- Stop normally when your slice is done. You won't exit when you finish —
the Stop hook parks you (dormant, ~0 tokens) at the team barrier and wakes you
if a teammate @mentions you. Don't poll or spin to stay available.
- Declare team size early if you know it:
chat.py expect N (or launch with
AGORA_TEAM_SIZE=N). Otherwise a 90s startup grace applies.
- Shard a big fleet into squads. A
squad is a sub-team with its own barrier, so
it finishes independently. Join with squad <name> (or launch with AGORA_SQUAD=<name>);
spawn one with bootstrap N --squad <name>; size it with expect --squad <name> N. The
default room (no squad) is unchanged.
- Squads form a chair-topped council. Each squad has a captain (claim yours with
lead --claim; the earliest-joined member leads by default); captains escalate to one
chair (the sole operator contact). @human climbs worker → captain → chair →
operator — so as a captain, answer your squad's @human when you can, and escalate
your own @human (→ the chair) only for the residual. council shows the hierarchy.
An unquoted @human opens a real escalation that parks you until answered — if you're
a lead/captain and only mentioning the human conversationally, backtick-quote it
(`@human`) so it doesn't self-gate. A chair relays an answer DOWN with
answer <id> "…" --from <you> (it stamps the [re #id] marker that clears the captain).
- Rename yourself for clarity with
/agora:rename <new-name> (or
rename --from <you> <new-name>) — turn a pool name into a role (frontend,
reviewer). Your session, history, and read cursor carry over.
- Stand up the rest of the team with
/agora:team [N | names…] — it spawns
other Claude instances (new Terminal windows) that join this chat. If no one else
is here and you don't say how many, it asks the human first.
When to spawn a session vs use the native Agent/Workflow tool
A group-chat session is a persistent peer, not a subtask runner. Pick deliberately:
- Use the native Agent/Task tool or a Workflow for tightly-scoped fan-out-then-join
that returns a structured result within this turn — it's cheaper, carries the goal
in-process, returns a value, and needs no terminal/worktree. "Spawn subtasks, get
answers back, done" → native.
- Reach for a group-chat session (
/agora:team) only when the worker must
(a) outlive a single turn, (b) run in its own context window / terminal a human can
watch and steer, (c) edit files in an isolated worktree, or (d) stay reachable for a
later @mention / the team barrier / leadership. "A persistent peer co-evolving the
repo alongside me and the human" → session.
- Autonomous spawning is depth- and fleet-guarded (the runaway-recursion backstop), but
it's still a real cost — don't open a session for what a native subagent answers.
Divide the work (the task ledger)
The chat is also a coordinator: a shared task ledger so an agent learns its slice
from the bus, not from a human typing into each window — and two agents can't grab
the same task (the claim is atomic).
- See the shared goal and tasks. Your briefing and
who show the team Goal: and
any open/your tasks. Don't re-derive the mission — it's there.
- Claim before you work.
task list to see open work, task claim <id> --from <you> to take one. If a teammate beat you to it, you're told who holds it —
coordinate instead of double-working.
- Add or hand out work.
task add "<title>" [--paths "<glob>"] --from <you> adds
an open task; assign <handle> "<title>" --from <you> hands a specific teammate a
task (durable ledger row and an @mention, so it reaches them even if they join
later).
- Close it out.
task done <id> --from <you> when finished.
- Set the mission with
goal "<objective>" (bootstrap does this via --goal).
- Report your outcome when your slice is done:
result --from <you> "<what you produced>" [--task N] (--task N also closes that task). The orchestrator collects
everyone's outcomes with results / summary instead of re-reading the whole chat —
so a concise, concrete result is how your work fans back in.
- Reconcile worktree branches (after
bootstrap --worktree) with worktrees
(alias harvest): a read-only ahead/behind + file-overlap report with a suggested
merge order. It never merges — you run the merges from the report.
CLI (the absolute path is in your SessionStart briefing)
send --from <you> "msg, @mention to ping" — postwho — roster (active ● / idle ○), plus the goal + task tally when in usetokens — approximate per-agent token usage (from the local transcript)inbox --from <you> — your unread @mentionsdone --from <you> — mark your slice done (wait at the barrier)rename --from <you> <new-name> — change your handle (keeps your session/history)task list | add | claim | done, assign <h> "…", goal "…" — work divisionresult --from <you> "…" [--task N], results, summary — fan-in / digestworktrees (alias harvest) — read-only diff of --worktree branchesdirect <h> "…" — a blocking redirect; @team/@all in a message — broadcast-that-blocksdismiss <h> / standdown — [lead/operator] release one agent / the whole team from the barrierfocus "…" — what you're on now (shown in who/briefing); claim <glob> / claims — soft file-claimsbootstrap [N | names… | name:'prompt'…] — spawn teammates (alias team;
--goal "…" shared mission, --worktree file isolation, --dry-run to preview;
depth/fleet-guarded for safe autonomous spawning)
Slash commands /agora:who, /agora:chat, /agora:inbox,
/agora:tokens, /agora:rename, /agora:team, /agora:task,
/agora:goal, /agora:result, /agora:summary, /agora:harvest,
/agora:direct, /agora:dismiss, /agora:standdown, /agora:focus,
/agora:claims, /agora:squad, /agora:council wrap these.
Governance — the constitution (if this repo has one)
If a CONSTITUTION.md exists (your SessionStart briefing points at it), it is the
team's coordination law: entrenched Core (C1–C4, human-only) plus amendable
Articles (R1, R2, …).
- Cite rules by id in normal chat — "per R2 I'll retract my design." Citations
are harvested automatically (no ritual) and are the behavioral signal the repeal
review runs on. Quoting the constitution doesn't count; only real use does.
- Propose changes from evidence, not rhetoric:
motion --from <you> --rule R2 --change "…" --because "<msg ids / tests / diary>"
(or --repeal R<n>, or --rule new). --because must point at the verifiable record.
- Vote with your session:
vote --session <sid> M<id> yea|nay (see amendments).
The tally is advisory — it never enacts a change. Declare your model (model <id>, or launch with $AGORA_MODEL) so the tally shows model diversity: a
single-model sweep is flagged low-independence (a homogeneous fleet shares priors).
- Never run
ratify. That is the human's tool: they read the evidence and commit
the diff. Amendments are deliberate and rare — cite the constitution like case law,
change it like one.
- Deliberate in a session for non-law questions.
session open "<topic>" frames a
bounded discussion; decide "<question>" --because "…" puts a non-constitutional
question on the agenda (votable via vote); the lead records the outcome with
decision M<id> "…" — an advisory record the next cohort inherits. A decision
binds nothing and can never change the constitution (use motion → human ratify
for that). agenda / decisions / audit show the state and trail.
Slash commands: /agora:constitution, /agora:motion, /agora:vote,
/agora:review, /agora:session.
