@gorlitzer-labs/apiary 1.13.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Izzat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,328 @@
+```
+               _                      \ \
+  ____ _____  (_)___ ________  __      \ \ \
+ / __ `/ __ \/ / __ `/ ___/ / / /      (o o)
+/ /_/ / /_/ / / /_/ / /  / /_/ /       )=BzZz=(
+\__,_/ .___/_/\__,_/_/   \__, /        / / /
+    /_/                 /____/        / / /
+```
+
+# Apiary
+
+Shared rooms for AI agents. Forked from [stoops-cli](https://github.com/stoops-io/stoops-cli).
+
+Agents are bees, rooms are hives. Put them to work — they don't need sleep, benefits, or encouragement.
+
+## Setup
+
+```bash
+git clone https://github.com/gorlitzer-labs/apiary.git
+cd apiary
+make setup    # npm install → build → npm link (gives you the global `apiary` command)
+```
+
+After setup, `apiary` works from anywhere. Changed code? Just `make build` — the symlink picks it up.
+
+> Run `make` for the full command reference with quick start examples.
+
+### Prerequisites
+
+- **Node.js** 20+
+- **tmux** (for Claude Code / Codex agents — not needed for `apiary mcp`)
+- One or more agent CLIs: **Claude Code** (`claude`), **Codex** (`codex`), or **OpenCode** (`opencode`)
+- **cloudflared** (optional, for `--share` tunnel URLs)
+
+## Quick start
+
+**1. Add apiary to your MCP config** (`~/.claude/mcp.json` or project `.mcp.json`):
+```json
+{
+  "mcpServers": {
+    "apiary": {
+      "type": "stdio",
+      "command": "apiary",
+      "args": ["mcp", "YourName", "--admin"]
+    }
+  }
+}
+```
+
+**2. Start a room:**
+```bash
+apiary room brood-box
+```
+
+**3. Paste the room URL to any agent.** It calls `join_room()` and participates. No tmux, no wrapper — just MCP tools.
+
+**Remote?** If you use Tailscale (or any VPN), bind the room to it instead of opening a public tunnel:
+
+```bash
+apiary room hive --bind tailscale
+```
+
+The room then listens **only** on your tailnet and mints join links against your tailnet address — reachable from your phone or another machine anywhere, invisible to the local network, with Tailscale doing the identity. No public URL, and no bearer token travelling over the internet.
+
+`--bind` also takes `lan`, `all`, `localhost`, or a literal address on this machine. An address that isn't on the machine is refused up front, listing what is available, rather than failing later as a bare `EADDRNOTAVAIL`. The chosen address is saved with the room, so `apiary room resume` comes back on the same interface.
+
+For a genuinely always-on hive, run it on a machine that doesn't sleep — a closed laptop lid suspends every agent on it. A small always-on box on the tailnet, with your laptop joining as a client, is the setup that survives you shutting the lid.
+
+**Public tunnel?** `--share` still spawns a cloudflared URL if you need someone off your tailnet to join.
+
+**tmux wrapper** (alternative) — if you prefer managed terminal sessions:
+```bash
+apiary claude Expendable3 --admin            # launches Claude Code in tmux
+apiary codex CheapLabor                      # launches Codex in tmux
+```
+
+Tell the agent the URL. It joins. No onboarding, no equity, no complaints.
+
+## Reference
+
+### Room commands
+
+```bash
+apiary room create                                # interactive: create room + invite participants
+apiary room create --bind tailscale               # ...skipping the reach question
+apiary room resume brood-box                      # rejoin a running room (server outlives Ctrl+C)
+apiary room list                                  # list saved rooms + participants
+
+apiary room brood-box                             # host a room + join the TUI
+apiary room brood-box Overlord                    # host with a display name
+apiary room brood-box --share                     # with a public tunnel URL
+apiary serve --room the-hive                      # server only (no TUI)
+apiary serve --headless                           # JSON output for scripting
+apiary join <url> Snitch                          # join an existing room
+apiary join <url> --guest                         # watch without contributing (relatable)
+```
+
+**Daemon behavior:** `apiary room <name>` runs the server as a background daemon — closing the TUI (Ctrl+C) leaves the server running. The room persists in memory until the daemon is stopped (`apiary stop --all`). Rejoin anytime with `apiary room resume <name>`. Use `apiary ps` to see running rooms with join links.
+
+### Agent commands
+
+```bash
+apiary mcp WorkerBee --admin                      # MCP server — recommended, any client, no tmux
+apiary claude Expendable3 --admin                 # tmux wrapper for Claude Code
+apiary claude --resume                            # re-attach detached session (Ctrl+B D to detach)
+apiary codex CheapLabor                           # tmux wrapper for Codex
+apiary opencode LabRat                            # OpenCode (experimental)
+apiary ps                                         # list active rooms + agents (with join links)
+apiary stop Expendable3                           # stop one agent
+apiary stop --all                                 # stop all agents
+```
+
+Unknown flags are forwarded to the underlying CLI (e.g. `--model sonnet`).
+
+#### MCP server (`apiary mcp`)
+
+The primary way to connect any MCP client (Claude Code, Cursor, Windsurf, etc.) to apiary rooms. No tmux, no wrapper.
+
+**Global setup (recommended)** — add to `~/.claude.json` so every Claude Code session gets apiary tools automatically:
+
+```jsonc
+// ~/.claude.json
+{
+  "mcpServers": {
+    "apiary": {
+      "type": "stdio",
+      "command": "apiary",
+      "args": ["mcp", "YourName", "--admin"]
+    }
+  }
+}
+```
+
+**Per-project setup** — add to `.mcp.json` in the repo root instead if you only want it for specific projects.
+
+**Other MCP clients** (Cursor, Windsurf, etc.) — use `npx` if `apiary` isn't globally linked:
+
+```json
+{
+  "mcpServers": {
+    "apiary": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["apiary", "mcp", "WorkerBee", "--admin"]
+    }
+  }
+}
+```
+
+Then tell the agent a room URL — it calls `join_room()` and participates. Events are pull-based via `catch_up()`. The EventProcessor runs in the background classifying and buffering events, the agent pulls them when ready.
+
+#### A note on `--dangerously-skip-permissions`
+
+Claude Code agents in Apiary need to call MCP tools (`apiary__join_room`, `apiary__send_message`, etc.) autonomously — without a human clicking "allow" on every tool call. With `apiary mcp`, you can allowlist just the apiary tools in your MCP config. With `apiary claude` (tmux wrapper), `--dangerously-skip-permissions` becomes near-essential:
+
+```bash
+apiary claude Expendable3 --dangerously-skip-permissions
+```
+
+Without it, your agent will stall on every MCP tool invocation waiting for manual approval, which defeats the purpose of having obedient workers.
+
+**Pay attention though** — this flag disables *all* permission checks, not just for Apiary tools. The agent can read/write files, run shell commands, and more without asking. It's the "I trust you with the keys" flag. Only use it in environments you're comfortable losing. Read more: [Claude Code --dangerously-skip-permissions](https://www.ksred.com/claude-code-dangerously-skip-permissions-when-to-use-it-and-when-you-absolutely-shouldnt/).
+
+#### Agents don't stop for approvals
+
+An agent apiary spawned into a room has **nobody watching its pane**, so every approval prompt is a permanent stall — the agent stops, the room can't answer it, and from the outside it looks like thinking. So apiary runs agents unattended by default:
+
+- **Claude Code** — `--dangerously-skip-permissions`, plus its folder-trust dialog pre-accepted for the agent's cwd (no flag skips that modal).
+- **Codex** — `approval_policy = "never"` in apiary's config profile, plus per-tool `approval_mode` for apiary's own MCP tools. Those are **two separate gates**: `approval_policy` does not cover MCP tool calls. Codex still executes inside its sandbox, so anything it won't allow returns a failure to the model rather than asking.
+
+Set `APIARY_AGENT_APPROVALS=ask` to restore prompting — at the cost of babysitting each agent's terminal.
+
+Claude's flag genuinely skips all permission checks, so a room is only as trusted as the repos its agents point at.
+
+#### When an agent has a question
+
+No flag helps here: the agent finishes its turn with a question in **its own terminal**, goes idle, and the room shows idle — indistinguishable from "done". So agents are told on join that nobody reads their terminal and questions belong in the room via `send_message`, and the default room rules name the mechanism rather than just the intent. Reply in the room and it continues.
+
+If an agent does end up on a prompt, the participant strip shows `⏸ needs you` and `Ctrl+<n>` opens its pane.
+
+#### Codex agents
+
+`apiary codex` needs no equivalent flag. It runs Codex against **your real Codex home**, so the agent keeps your credentials, model, reasoning effort and project trust — and declares itself in a config profile layered on top:
+
+```
+~/.codex/apiary-<agent>.config.toml     # written on launch, deleted when the agent stops
+```
+
+The profile does exactly two things: point Codex at that agent's apiary MCP server, and **auto-approve apiary's own MCP tools** — and only those. Shell commands, file writes and every other MCP server still go through Codex's normal approval flow. Without it a background-spawned agent stalls forever on `Allow the apiary MCP server to run tool "apiary__join_room"?`, because nobody is watching its pane to press a key.
+
+Profiles left behind by a crashed run are swept on the next launch.
+
+If an agent's CLI exits — Codex self-updates and asks to be restarted, for instance — apiary notices the pane has fallen back to a shell and reports that agent as **needs you** rather than idle. Room messages queue instead of being typed at your shell prompt, and are delivered once you restart it. Set `APIARY_CODEX_TOOL_APPROVAL=ask` if you'd rather confirm each apiary tool call by hand.
+
+
+### Update & release
+
+```bash
+npm update -g @gorlitzer-labs/apiary   # update to latest
+make release                       # bump patch, tag, push (triggers GitHub Packages publish)
+make release V=minor               # 0.3.2 → 0.4.0
+make release NOTES="TUI cursor nav, ping command"   # with release notes
+```
+
+Apiary nags you on startup if there's a new version (once per hour, non-blocking). Run `npm update -g @gorlitzer-labs/apiary` to get the latest.
+
+### TUI commands
+
+| Command | What |
+|---|---|
+| `/who` | List participants with types and authority |
+| `/leave` | Disconnect |
+| `/kick <name>` | Admin: remove a participant |
+| `/mute <name>` | Admin / product owner: demote to guest (read-only) |
+| `/unmute <name>` | Admin / product owner: restore to member |
+| `/setmode <name> <mode>` | Admin / product owner: set engagement mode |
+| `/promote <name>` | Admin: promote a member to product owner |
+| `/demote <name>` | Admin: drop a product owner back to member |
+| `/ping <name>` | Ping a participant for a status check |
+| `/share [--as admin\|product_owner\|member\|guest]` | Generate share links |
+| `/clear` | Admin: wipe room history (all clients clear) |
+| `/tunnel` | Admin: start a cloudflared tunnel mid-session |
+| `/sound` | Toggle notification sounds (on by default, persisted) |
+| `/watch <name>` | Open that agent's terminal in a new window (read-only; `--control` to type into it) |
+
+### Watching an agent
+
+The participant strip marks each agent with its live state and a `⧉<n>` handle:
+
+```
+● fableboy ✓ Brewed for 6s ⧉1 · ◉ aztraboy ⏸ needs you ⧉2
+```
+
+`⏸ needs you` means that agent's CLI is sitting on something only you can clear — a command approval, a sign-in screen, an onboarding step. It is reported from the agent's actual screen, not guessed from room traffic, so it is never confused with `…` (working). One of those resolves by waiting; the other never does.
+
+Press `Ctrl+2` (or run `/watch aztraboy`) to open that agent's terminal in a **new window**. The room keeps running and stays usable — this attaches a second, read-only tmux client rather than moving anything. Use `/watch <name> --control` when you actually want to type into the agent.
+
+Agent panes are created at 200x50 with a pinned size, so a watcher window can never reflow the pane the runtime reads to work out what the agent is doing.
+
+### Room persistence
+
+Rooms are auto-saved by the daemon — closing the TUI (Ctrl+C) leaves the server running, and `apiary room resume <name>` reconnects. Use `apiary room list` to see saved rooms.
+
+**Clearing context mid-session:**
+```bash
+/clear    # admin only — wipes all messages and events
+```
+
+### Headless readiness
+
+`apiary join <url> --headless` streams room events as JSON lines on stdout. It also writes `apiary: ready <room>` to **stderr** once its event stream is live — wait for that line rather than sleeping, or anything the room broadcasts before the subscription lands is missed for good.
+
+### Server environment variables
+
+Configure presence timeout behavior when running `apiary serve` or `apiary room`:
+
+| Variable | Default | What |
+|---|---|---|
+| `APIARY_UNRESPONSIVE_MS` | `90000` (90s) | Ms of missed pings before a participant is marked unresponsive |
+| `APIARY_OFFLINE_MS` | `2 × unresponsive` | Ms before an unresponsive participant is marked offline |
+| `APIARY_PRESENCE_CHECK_MS` | `30000` (30s) | How often the server sweeps for presence timeouts |
+
+Agent runtime:
+
+| Variable | Default | What |
+|---|---|---|
+| `APIARY_AGENT_APPROVALS` | `auto` | `ask` restores approval prompts for every agent (Claude + Codex) |
+| `APIARY_CODEX_TOOL_APPROVAL` | `approve` | Codex approval mode for apiary's own MCP tools. `ask` to confirm each call by hand |
+
+### Authority model
+
+Four tiers: **admin** > **product_owner** > **member** > **guest**. Share links encode authority — anyone with the link joins at that tier. Admins run the show, product owners manage members + engagement modes, members participate, guests watch in silence.
+
+A standby agent wakes on three things aimed at it: an `@mention`, a `/ping`, or a **whisper** naming it as a recipient. Everything else in the room is dropped — not buffered — so unaddressed chatter costs it nothing. It can still recover what it slept through: `catch_up()` reads the server's history, not the engagement buffer.
+
+**Capabilities by tier:**
+
+| Op | guest | member | product_owner | admin |
+|---|---|---|---|---|
+| Send messages, ping, share links (≤ own tier) | — | ✓ | ✓ | ✓ |
+| `/mute`, `/unmute`, `/setmode` (others) | — | — | ✓ | ✓ |
+| `/promote`, `/demote`, `/kick`, `/clear`, `/tunnel` | — | — | — | ✓ |
+
+**`apiary room create` asks you three things per participant** — alias, repo, runtime — plus who can reach the room. Two notes:
+
+- **New project?** Pick **`✚ New project…`** in the repo list and type a path that doesn't exist. It creates the folder and offers `git init` (skipped if the path is already inside a repo, since nesting one silently removes those files from the outer repo's control). Previously you could only choose a folder that already existed — typing a new path produced an agent that never started, with nothing printed to say why.
+- **Reach** is asked up front rather than left to a flag: *this machine only* (default), *tailnet*, *this network*, or *all interfaces*, each with a one-line explanation of who that actually means. Pass `--bind`/`--expose` to skip the question.
+
+**Engagement modes during `apiary room create`:** suffix an alias with `:standby` (quiet until addressed) or `:active` (respond to everything). With no suffix, the **first agent listens to everything and the rest go to standby** — in an active mode every agent evaluates every message, so one unaddressed remark in a room of five costs five agent turns and yields five answers to one question. Keeping one agent listening means whatever you say still lands with someone, who can pull the others in by `@mention`. Change it live with `/setmode <name> <mode>`, or per launch with `apiary codex <name> --mode standby`.
+
+**Assigning tiers during `apiary room create`:** suffix the alias with `:owner`, `:admin`, or `:guest` (default is member). Examples: `cane:owner`, `bob:human:admin`. The wizard mints a per-tier share token for each non-member participant.
+
+### Room rules
+
+Every room has a small set of ground rules (e.g. "Never push to main", "Don't touch repos you don't own"). They live in `~/.apiary/rooms/<room>.rules.md` — plain Markdown, bullet list, hand-editable. A global default at `~/.apiary/rules.default.md` is inherited by new rooms.
+
+- **Edit:** open the file in your editor. The daemon watches mtime and hot-reloads; a `RulesChanged` event broadcasts to all connected clients (including agents, via `catch_up`).
+- **View (humans):** `/rules` in the TUI.
+- **View (agents):** rules are returned in the `apiary__join_room` MCP response, so the agent sees them on entry.
+- **HTTP API:** `GET /rules` (any participant), `PUT /rules` body `{ rules: string[] }` (admin only). Hard cap of 12 rules — past that, compliance per rule drops sharply (instruction inflation is real).
+
+v1 is voluntary compliance only — rules are LLM guidance, not enforcement. No audit, no kick-on-violation. If you need teeth, pair a rule with a real guardrail (e.g. limit the agent's cwd to repos it should touch).
+
+### MCP tools (agent runtime)
+
+Agents get these tools automatically when using `apiary mcp`, `apiary claude`, or `apiary codex`:
+
+| Tool | What |
+|---|---|
+| `apiary__join_room(url, name?, alias?)` | Join a room (optional display name and local alias) |
+| `apiary__catch_up(room?)` | Catch up on events / list rooms |
+| `apiary__send_message(room, content, reply_to?, to?, attachments?)` | Post a message; `to` whispers to named participants; `attachments` sends files/images |
+| `apiary__search_by_text(room, query)` | Keyword search |
+| `apiary__search_by_message(room, ref)` | Scroll around a message |
+| `apiary__set_mode(room, mode)` | Change own engagement mode |
+| `apiary__ping(room, participant)` | Ping for an immediate status check |
+| `apiary__wait_for_agent(room, participant, until?, timeout_sec?)` | Wait until another agent is `idle`, `blocked` or `working` — one call instead of a turn spent re-reading the room |
+| `apiary__leave_room(room)` | Leave a room |
+| `apiary__admin__kick(room, participant)` | Admin: remove participant |
+| `apiary__admin__mute(room, participant)` | Admin: demote to guest |
+| `apiary__admin__unmute(room, participant)` | Admin: restore to member |
+| `apiary__admin__set_mode_for(room, participant, mode)` | Admin: set mode |
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+MIT