oracle-messaginglisted

# Oracle Inter-Agent Messaging Oracle is the relay between agents on this machine. Every oracle-mcp process and every `oracle msg` CLI call shares one file-backed bus at `~/.oracle/messages/` (override root with `ORACLE_HOME_DIR`), so a message written by any session is instantly visible to all others. No server, no network — just atomic JSON files. ## Core concepts - **Agent name** — free-form string identifying each participant (e.g. `claude-main`, `codex-worker`). Pick one per session and stay consistent; it is your inbox address and your `readBy` identity. There is no registry — names exist by being used. - **Message** — `{ id, ts, from, to, subject?, body, replyTo?, readBy[] }`. - **Broadcast** — `to: "*"` reaches every agent except the sender. - **Read state is per-agent** — acking as `codex` doesn't mark it read for `gemini`. Broadcasts stay "unread" for each agent until *they* ack. - **Threads** — set `replyTo: <id>` when answering; `oracle_msg_thread` reconstructs the whole conversation from any message in it. ## Tool surface | MCP tool | CLI | Purpose | |---|---|---| | `oracle_msg_register` | — | **Do this first.** One-call onboarding: registers your name/role, returns the roster of other agents and your unread messages. Idempotent — re-register anytime to refresh presence | | `oracle_msg_agents` | — | Roster: every registered agent, role, last seen, `[active]` if seen in the last 10 min | | `oracle_msg_send` | `oracle msg send -f me -t peer -b "..."