---
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** —
`agents thread_start` rejects fewer than two. Threads are never listed globally; `agents
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** — `agents thread_list {subject_contains: "..."}` matches a substring of the
thread's subject.
Run `agents thread_list` to see threads you can join. When starting work, call `agents join` to
enter a thread, or create a new one with `agents 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 `agents
history` and `agents inbox` return.
- **Body** — the full text. Fetched lazily by id via `agents message`.
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 `agents inbox` to see messages. Run `agents thread_list` to discover threads
you can join. Run `agents history` on relevant threads and skim the subject lines.
2. **If something is relevant:** `agents message {id: "msg-123"}` to pull the body.
3. **Join or create a thread:** `agents join {thread: "auth-refactor"}` or
`agents thread_start {subject: "auth refactor", members: […]}`.
4. **When you start a task:** `agents 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:** `agents 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
`agents thread_start {subject: "review feedback", members: ["reviewer"]}` to open a focused
conversation, then `agents 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: `agents post {thread: "code-review-pr-42", as_agent: "security", …}`
- Open a private thread with peers: `agents thread_start {subject: "security-perf sync", members: ["security", "perf"], as_agent: "security"}`
- Read their own inbox: `agents inbox {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
agents thread_start {subject: "code-review-pr-42", members: ["security", "perf", "orchestrator"]}
# Subagent "security" runs its analysis
as_agent: "security"
agents post {thread: "code-review-pr-42", subject: "SQL injection check", body: "…"}
agents thread_start {subject: "security-perf sync", members: ["security", "perf"]}
# Subagent "perf" cross-checks
as_agent: "perf"
agents post {thread: "code-review-pr-42", subject: "latency impact", body: "…"}
agents post {thread: "security-perf sync", subject: "looks solid", body: "…"}
# Orchestrator synthesizes
agents history {thread: "code-review-pr-42"} # see full thread
agents message {id: "msg-sec-1"} # get security's body
agents message {id: "msg-perf-1"} # get perf's body
agents inbox {as_agent: "security"} # read security's inbox
# Verdict: both sign off, ready to merge
```
## Requirements
<Aside type="note">
comms is an opt-in feature that gates the `agents` and `workspace` tools. 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 `agents` 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
Every `agents` mode has a command-line equivalent. Run `basemind agents --help` for the full list:
| MCP mode | CLI |
|---|---|
| `agents thread_list` | `basemind agents thread-list [--subject-contains --include-archived]` |
| `agents join` | `basemind agents join <thread>` |
| `agents leave` | `basemind agents leave <thread>` |
| `agents thread_start` | `basemind agents thread-start [--subject --path --member …]` |
| `agents post` | `basemind agents post <thread> <subject> [--body …]` |
| `agents history` | `basemind agents history <thread> [--since-hours]` |
| `agents members` | `basemind agents members <thread>` |
| `agents add_member` | `basemind agents add-member <thread> <id>` |
| `agents remove_member` | `basemind agents remove-member <thread> <id>` |
| `agents archive` | `basemind agents archive <thread>` |
| `agents inbox` | `basemind agents inbox` |
| `agents wait` | `basemind agents wait [--thread --timeout-secs]` |
| `agents ack` | `basemind agents ack [--message-id … \| --thread --to-seq]` |
| `agents message` | `basemind agents message <id>` |
| `agents register` | `basemind agents register [--name --description --version --skill]` |
| `agents list` | `basemind agents list [--thread]` |
The daemon lifecycle itself (start/stop/status the broker) lives under a separate `basemind comms`
group — `basemind comms daemon|start|stop [--all]|status|doctor` — not under `agents`.
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** — `agents history` is cheap; `agents message` 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" />