Basemind Comms

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: <id> 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

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.