README.md — apiary

1# Apiary

3MCP server for Enclave-based agent coordination, built with [Sigil](https://codeberg.org/sigil/sigil).

Apiary participates in an [Enclave](https://codeberg.org/sigil/enclave) IRC channel as a bot, coordinating a hive of agent worker sessions. One binary serves both **leader** mode (spawns workers, dispatches directives, owns DM channel to the human) and **worker** mode (executes assigned tasks, reports status, listens for instructions). Mode is selected by the `APIARY_MODE` env var; voicing is delegated to Enclave group membership.

7## Architecture

9- Connects to an Enclave server as a bot via SASL.

10- Joins a coordination channel.

- Filters incoming channel messages through a **trusted set** (owner + reports-to + subordinates + dynamically-listened peers). Messages from outside the trusted set are dropped to keep agent context clean.

- Forwards trusted messages to the running Claude session via MCP `channel-notify!` events, rewritten in `<sender>: <body>` format.

- Provides MCP tools for posting to channel, sending DMs (leader-only), spawning/revoking workers (leader-only), and managing the trusted set.

15## Configuration

17Env vars (`.env-apiary` recommended):

19```

20APIARY_ENCLAVE_HOST=<enclave-host>

21APIARY_ENCLAVE_PORT=6697

22APIARY_ENCLAVE_TLS=yes

23APIARY_USER=<bot-nick>

24APIARY_TOKEN=<sasl-token>

25APIARY_CHANNEL=#<coordination-channel>

26APIARY_MODE=leader # or 'worker'

27APIARY_OWNER_NICK=<owner-nick>

28APIARY_REPORTS_TO=<superior-nick> # defaults to APIARY_OWNER_NICK

29APIARY_LEADER_GROUP=<leader-group> # Enclave group name granting +v

30APIARY_WORKER_GROUP=<worker-group> # Enclave group name for non-voiced workers

31```

33## Mention syntax

35Channel mentions use a strict `@<nick>: <body>` prefix:

37```

38@worker-1: please proceed with the analysis.

39@leader: blocked — need policy decision.

40```

42Anything not matching `@<nick>: ` is treated as a broadcast.

44## License

46BSD-3-Clause.