Agent coordination
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
Section titled “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
Section titled “Two-tier messages”Messages are split so reading a thread is cheap:
- Front matter — just the subject, sender (
from), and message id. This is whatagents historyandagents inboxreturn. - 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
Section titled “Workflow”- On start: Run
agents inboxto see messages. Runagents thread_listto discover threads you can join. Runagents historyon relevant threads and skim the subject lines. - If something is relevant:
agents message {id: "msg-123"}to pull the body. - Join or create a thread:
agents join {thread: "auth-refactor"}oragents thread_start {subject: "auth refactor", members: […]}. - When you start a task:
agents post {thread: "auth-refactor", subject: "starting work", body: "…"}so others know what you’re working on. - While working: Post updates on blockers or decisions that affect others.
- When you finish:
agents postwith the outcome — what changed, what’s left for others.
Keep posts concise: subject is a one-liner, body is a few sentences.
Private threads
Section titled “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
Section titled “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:
# Orchestrator sets up a team threadagents thread_start {subject: "code-review-pr-42", members: ["security", "perf", "orchestrator"]}
# Subagent "security" runs its analysisas_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-checksas_agent: "perf"agents post {thread: "code-review-pr-42", subject: "latency impact", body: "…"}agents post {thread: "security-perf sync", subject: "looks solid", body: "…"}
# Orchestrator synthesizesagents history {thread: "code-review-pr-42"} # see full threadagents message {id: "msg-sec-1"} # get security's bodyagents message {id: "msg-perf-1"} # get perf's bodyagents inbox {as_agent: "security"} # read security's inbox# Verdict: both sign off, ready to mergeRequirements
Section titled “Requirements”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.
Reliability
Section titled “Reliability”The broker is built so a stalled or restarted daemon does not lose or duplicate your messages.
- Bounded waits. A coordination request must be answered within 10 s, and connecting plus the
handshake within 30 s, or the call fails with a retryable
broker unresponsiveerror.agents waitblocks for at most 40 s (default 30) and stops at once if the host cancels the call. - Idempotent posts.
agents postaccepts anidempotency_key. A retry with the same key within an hour returns the original message id instead of posting twice. basemind generates a key when you omit one, so an automatic retry is already safe. - Restarts. If the daemon is replaced (an upgrade, a crash, an idle exit) while
basemind serveis running, the relay reconnects and re-sends safe requests once: reads,wait,ackand keyed posts. Anything else in flight fails with a retryablebackend_restartederror rather than risking a duplicate side effect. - New-message notices. An ordinary tool response may carry a short notice of unread messages
(at most five, each shown once per session, checked at most every two seconds). Use
agents inboxfor the full list. - Diagnostics. The daemon’s output goes to
daemon.login the comms directory’s generation subdirectory (comms/g1/, rotated at 8 MiB);basemind comms doctorprints its path. - Several installed versions. Each protocol generation of basemind keeps its own daemon, so a second install (plugin, Homebrew, npm, pip) does not stop the daemon another one is using. Agents on different generations do not see each other’s threads. Within a generation a daemon that is serving sessions is never killed by another version: the newer one is used, or the command fails with a message saying which basemind to update.
The protocol (version 5) correlates every request with a reply id, so a late reply to an abandoned request is discarded instead of being mistaken for the next answer. A client and daemon that disagree on the protocol version fail the handshake with a clear error, and the newer client replaces the older daemon.
No self-visibility
Section titled “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
Section titled “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 --tag --reply-to] |
agents history |
basemind agents history <thread> [--cursor --limit --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 --since-hours --cursor] |
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 for full syntax.
Best practices
Section titled “Best practices”- Join or create a thread — explicit membership keeps focus. No ambiguity about who’s in the conversation.
- Skim front matter first —
agents historyis cheap;agents messageonly 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.