multi-agent-room

name	multi-agent-room
description	Orchestrate a team of named subagents in shared threads. One orchestrator drives multiple peers with distinct identities; each subagent sees its own inbox and can cross-check findings by posting to a thread the peer is a member of.

Multi-agent thread orchestration

Run a team of NAMED subagents that coordinate in shared THREADS, all driven by one orchestrator. Each subagent has its own identity and inbox, and posts to threads the relevant peers are members of.

When to use it

Orchestrate subagents when:

• Multiple reviewers need to see each other's work (code review, audit, cross-validation).
• A subagent should hand off findings to a peer for verification.
• The team needs a shared narrative (all readable in one thread history).
• You want to parallelize independent work (each agent runs concurrently) and then synthesize.

Setup

1. Start a thread and name its members. A thread is addressed by at least two of three coordinates — {subject, path-glob, members}. For a private team, list the members explicitly so only they see it; discovery is scoped, never global, so unrelated agents never surface it.

   agents {mode: "thread_start", subject: "review-pr-42", members: ["security", "perf"]}
   

2. Assign each subagent a short name. Pass as_agent to every tool call the subagent makes. Names like "security", "perf", "correctness" are clearer than defaults. A named member must join with agents mode join (or be added with mode add_member) before it can post.

3. Distribute the subagent contract. Each subagent's prompt should include:

   • Its assigned as_agent name (e.g. "security").
   • The shared thread's subject (e.g. "review-pr-42").
   • Instructions to:
     • Call agents {mode: "register", as_agent: "security", name: "Security Reviewer", …} once.
     • Call agents {mode: "join", thread: "review-pr-42", as_agent: "security"} to participate.
     • Call agents mode post with as_agent: "security" to share findings.
     • Call agents mode inbox with as_agent: "security" to see addressed messages.

Broadcast vs targeted hand-off

• Thread post (agents mode post + as_agent): everyone on the thread sees it. Use for:

  • Announcing a finding the whole team should see.
  • Replying to a peer's discovery (reply_to: <id> keeps it linked).
  • Summarizing your work.

• Targeted hand-off: to reach one peer privately, use agents mode thread_start for a two-member thread (members: ["security", "perf"]) — only those two discover it. Use for:

  • Asking a peer to cross-check your finding.
  • Sharing a detail not ready for the whole team.
  • Hand-off: "I found X; can you validate my approach?".

Reading and synthesis

As the orchestrator:

1. Let all subagents post to their threads (in parallel).
2. Read the shared thread: agents {mode: "history", thread: "review-pr-42"} (front-matter only).
3. For each message that matters, fetch the body: agents {mode: "message", message_id: "…"}.
4. Read each subagent's inbox with agents mode inbox and its as_agent identity. (Messages appear as front-matter; bodies come from mode message.)
5. Synthesize: combine the findings into a verdict, decision, or report.

Example: two-agent security + performance cross-check

Orchestrator setup:

agents {mode: "thread_start", subject: "review-auth-pr", members: ["security", "perf"]}

# Spawn agent "security"
# Prompt: "You are agent 'security' on thread 'review-auth-pr'. Register yourself,
# join the thread, analyze the diff for auth bugs, post findings, and start a
# two-member thread with 'perf' asking them to check your fix's perf implications."

# Spawn agent "perf"
# Prompt: "You are agent 'perf' on thread 'review-auth-pr'. Register yourself,
# join the thread, analyze the diff for performance regressions, post findings, and
# reply to 'security' with your take on their auth fix."

Agent "security" steps:

agents {
  mode: "register", as_agent: "security", name: "Security Reviewer", description: "Auth auditor"
}
agents {mode: "join", thread: "review-auth-pr", as_agent: "security"}
agents {
  mode: "post", thread: "review-auth-pr", as_agent: "security", subject: "SQL injection check",
  body: "Parameter X is quoted..."
}
agents {
  mode: "thread_start", subject: "cross-check-sanitized-input",
  members: ["security", "perf"], as_agent: "security"
}
agents {
  mode: "post", thread: "cross-check-sanitized-input", as_agent: "security",
  subject: "Cross-check: sanitized input",
  body: "I added validation at line 42..."
}
agents {mode: "inbox", as_agent: "security", mark_read: true}  # See perf's response

Agent "perf" steps:

agents {
  mode: "register", as_agent: "perf", name: "Performance Reviewer", description: "Latency auditor"
}
agents {mode: "join", thread: "review-auth-pr", as_agent: "perf"}
agents {
  mode: "post", thread: "review-auth-pr", as_agent: "perf", subject: "Cache impact check",
  body: "New validation adds ~2ms..."
}
agents {
  mode: "post", thread: "cross-check-sanitized-input", as_agent: "perf",
  subject: "Auth fix validated",
  body: "Sanitization looks solid...", reply_to: "msg-sec-2"
}

Orchestrator synthesis:

agents {mode: "history", thread: "review-auth-pr"}  # See front matter
agents {mode: "message", message_id: "msg-sec-1"}  # Get security's body
agents {mode: "message", message_id: "msg-perf-1"}  # Get perf's body
agents {mode: "history", thread: "cross-check-sanitized-input"}
agents {mode: "message", message_id: "msg-perf-2"}  # Get perf's hand-off body
# Synthesize: "Security + perf sign off. Ready to merge."

Recency and thread freshness

Reads default to RECENT so stale chatter never confuses an agent:

• agents modes history / inbox return only the last 24 hours by default. Pass since_hours: N for a wider window, or since_hours: 0 for the full append-only log. Nothing is ever deleted — older history stays reachable explicitly.
• Every front-matter row carries age_secs (seconds since the message was posted) so you can gauge staleness without converting timestamps yourself.
• agents mode thread_list flags each thread stale: true after over 7 days without a post. The CLI renders this as an ACTIVE / STALE marker per thread. Idle threads auto-archive; skip stale ones unless you are intentionally reviewing old context.

Notes

• A named member must join with agents mode join (or be added with add_member) before posting.
• A private two-member thread reaches exactly one peer — only its members discover it.
• Front-matter-only reads (history, inbox) are cheap. Fetch bodies only when needed.
• The CLI offers parity: basemind agents post … --as-agent security, basemind agents thread-start --subject <subject> --member perf --as-agent security, basemind agents history <thread> --since-hours 0 (all history), basemind agents thread-list (shows ACTIVE / STALE per thread).