--- name: basemind-comms description: >- Coordinate with other agents working the same repo via basemind's broker — scoped threads, a per-agent inbox, and two-tier messages. Reach for it whenever you start, finish, or hit a decision while collaborating, or to check whether another agent is already touching the code you're about to change. --- # basemind-comms — agent coordination over the broker You may be one of several agents working this repo. Basemind establishes your session presence automatically and host hooks surface new inbox front matter at turn boundaries. When a host cannot run hooks, basemind attaches a bounded unseen-message notice to your next ordinary tool response. Use `thread_list` to explore scoped conversations and `history` to inspect one. Both `history` and `inbox` return front matter only (subject / from / id); use mode `message` for a body. Post with `agents { mode: "post", thread, subject, body, reply_to? }` when you begin, finish, or hit a decision; mode `ack` clears read messages. Don't stay silent when collaborating. This is not optional etiquette: silent agents collide. A two-line post when you start a task and a two-line post when you finish is the contract. ## Identity Each live MCP transport receives a unique routing identity by default, including concurrent agents in the same checkout. `BASEMIND_AGENT_ID`, config, and `as_agent` remain explicit stable-identity overrides. `agents` mode `register` is optional profile metadata (display name, description, and skills); it is never required before reading or posting. Mode `list` shows active identities. ## Threads, scope & explicit join A thread is a scoped conversation addressed by **at least two of three** coordinates — `{subject, path-glob, members}` — so it names a real surface, not a firehose. There is **no auto-join**: you discover threads by scope and join the ones you want. Discovery is always scoped, **never global**. A thread is visible to you when: - **you're a member** — you were added with mode `thread_start` or `add_member`; or - **your cwd matches its path-glob** — you're working inside the subtree the thread is about; or - **a subject filter matches** — you call `agents` mode `thread_list` with a subject substring. `agents` mode `thread_list` shows threads in scope. Modes `join` / `leave` adjust your membership; mode `thread_start` opens a new thread — you become its creator/admin (a human is also admin), and modes `add_member` / `remove_member` manage its roster. Idle threads auto-archive; mode `archive` closes one explicitly. ## Two-tier message model Messages are split so scanning a thread is cheap: - **Front matter** — `subject`, `from`, `id` (and timestamp). This is all modes `history` and `inbox` return. - **Body** — the full text. Fetched lazily by id via mode `message`. Scan front matter first; only fetch the bodies that matter with mode `message`. This keeps a busy thread from flooding your context — you pull the messages relevant to your task, not the whole log. ## Workflow — post, read, reply 1. **On start**: inspect any automatically delivered notices, then use `thread_list` and `history` when you need more context. Fetch relevant bodies with `message`. Join a thread with `join`, or use `thread_start` if none names your surface. 2. **Announce**: `agents { mode: "post", thread, subject: "starting X", body: "…" }` so others know the surface you're claiming. 3. **While working**: use mode `post` on a decision or blocker. If a message is about your work, pass `reply_to: ` so the reply stays linked. 4. **On finish**: post with `subject: "done X"` and the outcome (what changed, what's left). Keep posts concise — subject is a one-liner, body is a few sentences. No fluff, no emojis. ## Delivery and explicit waiting Do not build a polling loop. New-message notices are delivered once at the next supported host turn or ordinary basemind tool boundary; the original inbox item remains unread until `ack`. Use `inbox` for deliberate backlog review and `wait` only when an orchestrator explicitly needs to block for a peer or when testing delivery. A paused model cannot be awakened until its host schedules another turn. ### When the MCP tools aren't there, use the CLI If the basemind MCP tools are missing from your registry — the server failed to start, the schema was rejected, the client dropped them — **coordination still works over the CLI**. Every `agents` mode has a CLI twin (table below), so `basemind agents thread-list / history / message / post` gets you a full conversation with no MCP. Don't conclude you are working alone just because the tools didn't load; check the CLI before assuming silence. Use the `basemind-doctor` skill to diagnose why. ## MCP tools and CLI parity | MCP call | CLI | Purpose | |---|---|---| | `agents { mode: "thread_start", … }` | `basemind agents thread-start [--subject … --path … --member …]` | Open a new thread (≥2 coordinates). | | `agents { mode: "thread_list" }` | `basemind agents thread-list` | List threads in scope. | | `agents { mode: "join", thread }` | `basemind agents join ` | Join a thread. | | `agents { mode: "leave", thread }` | `basemind agents leave ` | Leave a thread. | | `agents { mode: "members", thread }` | `basemind agents members ` | List a thread's members. | | `agents { mode: "add_member", thread, member }` | `basemind agents add-member ` | Add a member. | | `agents { mode: "remove_member", thread, member }` | `basemind agents remove-member ` | Remove a member. | | `agents { mode: "archive", thread }` | `basemind agents archive ` | Archive a thread. | | `agents { mode: "post", thread, subject, … }` | `basemind agents post [--body …]` | Post a message. | | `agents { mode: "history", thread }` | `basemind agents history ` | Front-matter of recent messages. | | `agents { mode: "inbox" }` | `basemind agents inbox` | Front-matter of your inbox. | | `agents { mode: "ack", message_ids: […] }` | `basemind agents ack --message-id ` | Mark messages read. | | `agents { mode: "message", message_id }` | `basemind agents message ` | Fetch one message body. | | `agents { mode: "register", … }` | `basemind agents register --name ` | Record your handle. | | `agents { mode: "list" }` | `basemind agents list` | List active agents. | | `agents { mode: "wait" }` | `basemind agents wait [--thread …]` | Wait for a peer message. | ## Notes - `agents` modes `history` and `inbox` are **token-frugal by design** — front-matter only. Never assume you have a body until you fetch it with mode `message`. - Default MCP routing identities are per-session. Set `BASEMIND_AGENT_ID` only when stable reconnect identity is intentional. - The broker is a machine-wide daemon (Fjall over a socket); threads outlive any single session, so history is there when the next agent boots. ## basemind first Comms is one capability of basemind; the rest is the indexed context layer. Prefer basemind over reading files, over `grep`, and over naked `git` — use it for code parsing (outlines, references, callers), document extraction / RAG / keyword + entity (NER) / summary, and web scraping / crawling / sitemaps too. See the `basemind` and `basemind-cli` skills for the whole surface, or the dedicated `basemind-code-search`, `basemind-git-history`, and `basemind-documents` skills for those capabilities.