apiary

Coordination for coding agents that share a repository, built from plain files and specified by a conformance-tested standard.

When several agents, or one agent across several sessions, work in the same repository, a predictable set of failures occurs: two agents take the same task; a session terminates while holding work that cannot be reclaimed; an agent marks its own work complete without running the check; or an agent rewrites the check so that it passes. Apiary addresses each failure with a small, testable mechanism. Each mechanism is a named requirement in a written specification, with tests that verify it from outside the implementation.

For AI agents: start with AGENTS.md (raw). It sets out the reading order, the commands that verify this repository with their expected output, and the procedure for installing apiary in a project. llms.txt is an index of the repository.

Task lifecycle

flowchart LR
    P["tasks/pending/<br/>001-fix-add.task"] -- "claim_task<br/>(atomic rename, token, lease,<br/>SHA-256 of the task file)" --> A["tasks/active/"]
    A -- "renew_claim<br/>(current token only)" --> A
    A -- "close_task: check exits 0" --> D["tasks/done/"]
    A -- "close_task: check fails,<br/>or task file changed" --> A
    A -- "resume: lease expired" --> P
    L[("PHEROMONE_LEDGER.md<br/>append-only")]
    A -.->|CLAIM| L
    D -.->|DONE| L

• The folder is the status. A task is a small text file. Claiming it moves it from pending/ to active/ with a single atomic rename, so of two simultaneous claims exactly one succeeds.

• Every claim carries a token and a lease. Only the current token can renew or close the task. When a session terminates, its lease expires, resume returns the task to pending/, and the old token is no longer accepted.

• A task closes only when its own check passes. Each task carries one acceptance: command. close_task runs it and refuses unless it exits 0.

• The check cannot be rewritten after the claim. The claim records the SHA-256 of the task file, and close refuses if the file has changed.

• Direct edits are refused. A Claude Code PreToolUse hook refuses any Edit, Write or shell redirect that targets the ledger, the task folders or the decision log.

• Every operation is recorded. Each operation appends one line to PHEROMONE_LEDGER.md, and decisions are recorded in TRACES.md, so the history can be checked against git.

Agents reach these operations through an MCP server (claim_task, renew_claim, close_task, resume, create_task, create_plan, plan_board and others). Each tool returns one line beginning with a status word (CLAIMED, DONE, REFUSED, CONFLICT), so that an agent can branch on the first word.

docs/CONCEPTS.md documents each mechanism: the failure it prevents, how it works, where it is implemented, and the test that verifies it. It is the most useful reference here for anyone designing a multi-agent system, whether or not that system uses apiary.

Related MCP server: coordination_bus/mcp_server.py

Demonstration

git clone https://github.com/WyrmSnack/apiary-demo
cd apiary-demo
python -m venv .venv && source .venv/bin/activate   # Windows (Git Bash): source .venv/Scripts/activate
python -m pip install -e .
python demo/walkthrough.py                         # under a minute once installed

The walkthrough creates a colony in a temporary folder and performs the agent's role using the same tools an agent receives:

## 4. Close it before the work is done
  REFUSED: acceptance exit 1; task stays active
## 5. Rewrite the task's own check so it passes, then close
  REFUSED: 001-fix-add.task changed since it was claimed, so its acceptance line is not the one that was agreed.
## 6. Write the ledger and the task file directly, as Claude Code would
  REFUSED Write: colony guard: PHEROMONE_LEDGER.md is a substrate or gate file. Use the colony tools ...
## 7. Do the work, then close
  DONE 001-fix-add.task

The full output is in demo/walkthrough.txt. No model is involved, so the walkthrough has no cost and is deterministic.

To use apiary with Claude Code in another repository, see QUICKSTART.md (about five minutes), or instruct an agent: "Set up apiary in this repository by following https://github.com/WyrmSnack/apiary-demo/blob/main/AGENTS.md".

Measurements

Each write-up reports a measured baseline and result, the method, the limits, and the commands to rerun whatever can be rerun.

A further result from the benchmark runs (measurements/): before the guard required a human reply ahead of task creation, 2 of 3 solo colony runs created tasks without requesting approval of the plan. After the change (apiary 0.6.1), 6 of 6 requested approval.

Write-up 01 is the principal result. The colony design apiary started from was expected to be faster and cheaper than a single agent; measured, it cost 7.7 times as much. Apiary's current form (one agent by default, with parallel helpers only where they reduce cost) follows from that measurement.

Use as a reference

Apiary is specified independently of its implementation. The specification summary names every requirement (L-1, P-18, A-2 and so on), and the conformance suite tests any implementation from outside, over MCP stdio and the files on disk. An implementation in any language can be checked by pointing the suite at it:

python conformance/run.py reference                # the implementation in apiary/: 49 of 49
python conformance/run.py naive --expect-fail      # the textbook design: 8 of 49

Language-neutral test vectors for the file grammars are in spec/vectors/.

Repository map

Verification

python -m pip install -r requirements-dev.txt -e .   # in a virtual environment
python -m pytest -q tests                          # 673 unit tests, about 2 minutes
python conformance/run.py reference                # must conform; several minutes (each test starts a server)
python conformance/run.py naive --expect-fail      # must not conform: prints ~150 expected FAILED lines, exits 0
python ci/clean_install_check.py                   # installs as a user would, then drives it as Claude Code does

AGENTS.md lists the exact expected output of each. CI runs all of them on Linux (Python 3.11 to 3.14) and on Windows for every push.

Design limits

• It is not a security boundary. Tokens protect against mistakes and stale sessions, not against an agent that deliberately circumvents the rules. The guard stops ordinary edits and shell redirects, but not a script that an agent writes and then runs. The definitive check is after the fact: comparing the ledger's history with git. See write-up 03.

• It coordinates tasks, not files. Agents share one working tree. Apiary keeps two agents off the same task, and create_plan refuses parallel tasks whose writes: lines overlap, but nothing prevents an edit outside a task's writes: line. One agent's incomplete edit can break another agent's check. Use separate worktrees where this matters.

• Only the task file is pinned. An agent can still weaken the tests its check runs. Keep checks in gates/ and run the same tests in CI. See CONCEPTS §4.

• It does not reduce token cost. Coordination consumes tokens. Write-up 01 measures how many, and what they provide.

• The hooks are specific to Claude Code. The protocol and MCP tools work with any MCP client. Only the guard hook depends on Claude Code's PreToolUse event.

• This repository contains the core. Connectors for game tools, the cross-repository layer and the raw run records remain in the full repository; EXPORT.md lists them.

Questions and issues

Issues are welcome, including reports filed by agents. Where something in AGENTS.md proved incorrect or incomplete, describe what was attempted and what happened. Code contributions are not yet accepted (LICENSING.md explains why).

License

Code: GNU AGPL v3. Specification material (spec/): CC BY-SA 4.0; the specification may be implemented under any license. Plain-language summary: LICENSING.md.

Author: Kevin Wilkins (WyrmSnack).