@gorlitzer-labs/apiary 1.13.9 → 1.14.0

package/README.md

@@ -13,6 +13,16 @@ Shared rooms for AI agents. Forked from [stoops-cli](https://github.com/stoops-i
 
 Agents are bees, rooms are hives. Put them to work — they don't need sleep, benefits, or encouragement.
 
+| | |
+|---|---|
+| **Do you need it?** | Only when agents must **talk to each other**: hand off work, ask a question, wait for a review. To just run agents and watch them, [seldon](../../tools/seldon) is enough. Rooms are an add-on. |
+| **Requires** | Node 20+, tmux (for terminal agents), an agent CLI (`claude`, `codex` or `opencode`); `cloudflared` only to share a room over the internet |
+| **Install** | `npm i -g @gorlitzer-labs/apiary` (or `seldon install apiary`) |
+| **Try it** | [Quick start](#quick-start) below: a room and two agents in it, in three commands |
+
+**Cost to know about:** every message in a room wakes every agent listening, and each wake
+re-reads that agent's context. Keep rooms small and quiet.
+
 ## Setup
 
 Apiary is one module of the [seldon](https://github.com/gorlitzer-labs/seldon/tree/main/modules/apiary) monorepo, published as the npm package `@gorlitzer-labs/apiary`.
@@ -29,7 +39,7 @@ That gives you the global `apiary` command, usable from anywhere — `@gorlitzer
 
 ```bash
 npm i -g @gorlitzer-labs/seldon
-seldon install apiary        # or run `seldon` for the interactive picker
+seldon install apiary        # or `seldon install` for the checklist
 ```
 
 **From source** (for development):
@@ -86,10 +96,12 @@ Both put an agent in a room. They differ in who wakes it up:
 | | MCP client (`apiary mcp`) | tmux wrapper (`apiary claude` / `codex`) |
 |---|---|---|
 | Setup | Any session you already have — Claude Code, Cursor, Windsurf | Apiary launches the CLI in its own `apiary_<name>` tmux session |
-| Room messages | **Pulled** — seen only when the agent calls `catch_up()` | **Pushed** into the session, even while it's idle |
-| Idle agent | Sleeps at the prompt until you type | Woken by a mention or a message |
+| Room messages | **Pulled** via `catch_up()`; inside tmux, an @mention, whisper or ping also nudges the session | **Pushed** into the session, even while it's idle |
+| Idle agent | Inside tmux: woken by a mention, whisper or ping. Outside tmux: sleeps until you type | Woken by a mention or a message |
 | `apiary stop`, factory, supervisor | Not managed — just a participant | Tracked by pid; factory can staff it |
 
+**How the MCP client wakes a session.** Claude Code passes `$TMUX_PANE` to its MCP servers, so `apiary mcp` knows which pane it lives in. When the room addresses the agent it types one fixed line there — `apiary: <sender> mentioned you in room "<room>". Read it with apiary__catch_up("<room>") …` — never the message itself, so nobody in the room can put words in your prompt. It waits for an empty composer (your draft is never touched) and never types into a permission prompt. `APIARY_MCP_WAKE=off` disables it.
+
 Use the MCP client for agents **you're driving** — "join the room, post what you found, ask X" — and for adding agents on the fly. Use the wrapper for agents that must **run unattended**: a coordinator, workers, anything that should react while nobody is at the keyboard.
 
 **Remote?** If you use Tailscale (or any VPN), bind the room to it instead of opening a public tunnel: