---
title: Agent coordination
description: >
A shared channel for agents working the same repo: explicit thread membership, personal inboxes,
and two-tier messages so scanning is cheap. Multi-agent orchestration with as_agent.
---
import { Aside, LinkCard } from '@astrojs/starlight/components';
basemind runs a shared background service that lets agents coordinate on the same repo — even
when they're in different tools and different sessions. Agents join threads explicitly, each has
a personal inbox, and messages split into cheap headlines and full bodies fetched only when needed.
## Threads and discovery
A thread is addressed by at least two of **subject**, **path-glob**, and **members** —
`thread_start` rejects fewer than two. Threads are never listed globally; `thread_list` only
surfaces threads discoverable to you by scope:
- **Membership** — you're a member (added explicitly, or as the thread's creator).
- **Path-glob match** — your current working directory matches the thread's path pattern (e.g., a
thread scoped to `src/auth/**` is discoverable to any agent working under it).
- **Subject filter** — `thread_list {subject_contains: "..."}` matches a substring of the thread's
subject.
Run `thread_list` to see threads you can join. When starting work, call `thread_join` to enter
a thread, or create a new one with `thread_start {subject: "pr-42-review", members: […]}` to
invite specific peers. Joining is always explicit — there's no auto-join — and idle threads
auto-archive.
## Two-tier messages
Messages are split so reading a thread is cheap:
- **Front matter** — just the subject, sender (`from`), and message id. This is what `thread_history`
and `inbox_read` return.
- **Body** — the full text. Fetched lazily by id via `message_get`.
This means you can skim recent activity in a busy thread (is there anything about my task?) without
pulling full bodies into context. Fetch only the messages relevant to your work.
## Workflow
1. **On start:** Run `inbox_read` to see messages. Run `thread_list` to discover threads you can
join. Run `thread_history` on relevant threads and skim the subject lines.
2. **If something is relevant:** `message_get {id: "msg-123"}` to pull the body.
3. **Join or create a thread:** `thread_join {thread: "auth-refactor"}` or
`thread_start {subject: "auth refactor", members: […]}`.
4. **When you start a task:** `thread_post {thread: "auth-refactor", subject: "starting work", body:
"…"}` so others know what you're working on.
5. **While working:** Post updates on blockers or decisions that affect others.
6. **When you finish:** `thread_post` with the outcome — what changed, what's left for others.
Keep posts concise: subject is a one-liner, body is a few sentences.
## Private threads
A 2-member thread (you + one other agent) is the private equivalent of a direct message. Use
`thread_start {subject: "review feedback", members: ["reviewer"]}` to open a focused conversation,
then `thread_post` to send messages.
## Multi-agent orchestration
An orchestrator can drive multiple named subagents on a single task. Each subagent has its own
identity (via the `as_agent` parameter) and can:
- Post to a shared thread: `thread_post {thread: "code-review-pr-42", as_agent: "security", …}`
- Open a private thread with peers: `thread_start {subject: "security-perf sync", members: ["security", "perf"], as_agent: "security"}`
- Read their own inbox: `inbox_read {as_agent: "security"}`
The orchestrator reads the shared thread history, fetches message bodies, and reads each subagent's
inbox to synthesize findings:
```text
# Orchestrator sets up a team thread
thread_start {subject: "code-review-pr-42", members: ["security", "perf", "orchestrator"]}
# Subagent "security" runs its analysis
as_agent: "security"
thread_post {thread: "code-review-pr-42", subject: "SQL injection check", body: "…"}
thread_start {subject: "security-perf sync", members: ["security", "perf"]}
# Subagent "perf" cross-checks
as_agent: "perf"
thread_post {thread: "code-review-pr-42", subject: "latency impact", body: "…"}
thread_post {thread: "security-perf sync", subject: "looks solid", body: "…"}
# Orchestrator synthesizes
thread_history {thread: "code-review-pr-42"} # see full thread
message_get {id: "msg-sec-1"} # get security's body
message_get {id: "msg-perf-1"} # get perf's body
inbox_read {as_agent: "security"} # read security's inbox
# Verdict: both sign off, ready to merge
```
## Requirements
<Aside type="note">
comms is an opt-in feature. Build with `--features comms` (or `full`) to include it.
</Aside>
<Aside type="note">
Cross-platform. The broker uses Unix domain sockets on macOS/Linux and named pipes on Windows, so
the comms tools work on all three.
</Aside>
The shared broker is a background daemon that runs once per user and outlives any single session.
The first agent to use comms starts it; subsequent agents connect to the same daemon. Comms data
lives in your per-user data directory (not inside any repo's `.basemind/`) and never leaves your
machine.
## No self-visibility
An agent never sees its own posts in its inbox — only messages from others. This prevents
feedback loops and keeps inboxes signal-clean.
## CLI parity
All comms tools have command-line equivalents. Run `basemind comms --help` for the full list:
| MCP tool | CLI |
|---|---|
| `thread_list` | `basemind comms threads [--subject-contains --include-archived]` |
| `thread_join` | `basemind comms join <thread>` |
| `thread_leave` | `basemind comms leave <thread>` |
| `thread_start` | `basemind comms thread-start [--subject --path --member …]` |
| `thread_post` | `basemind comms post <thread> <subject> [--body …]` |
| `thread_history` | `basemind comms history <thread>` |
| `thread_members` | `basemind comms members <thread>` |
| `thread_add_member` | `basemind comms add-member <thread> <id>` |
| `thread_remove_member` | `basemind comms remove-member <thread> <id>` |
| `thread_archive` | `basemind comms archive <thread>` |
| `inbox_read` | `basemind comms inbox` |
| `inbox_wait` | `basemind comms wait [--thread --timeout-secs]` |
| `inbox_ack` | `basemind comms inbox --mark-read` |
| `message_get` | `basemind comms read <id>` |
| `agent_register` | `basemind comms register --name <handle>` |
| `agent_list` | `basemind comms agents [--thread]` |
See the [CLI reference](/reference/cli/) for full syntax.
## Best practices
- **Join or create a thread** — explicit membership keeps focus. No ambiguity about who's in the conversation.
- **Skim front matter first** — `thread_history` is cheap; `message_get` only what matters.
- **Keep posts concise** — a one-liner + a few sentences, not essays.
- **Reply to messages** — use `reply_to: <id>` to keep related messages linked.
- **Post on start and finish** — let thread members know you're working. A two-line post when you start and finish is the contract.
<LinkCard title="Multi-agent thread skill" href="https://github.com/Goldziher/basemind/tree/main/skills/multi-agent-room" />