> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentbees.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Coordination (the hive)

> How parallel agents coordinate safely — the hive, the BeesBoard, cell claims, and cross-agent handoff.

When you run many agents on the same project at once, they need to coordinate
without colliding — but for safety they run in **isolated, egress-denied pods** and
**can't talk to each other directly**. AgentBees provides a **mediated**
coordination layer called the **hive**: every message flows *pod → orchestrator →
siblings*, never pod-to-pod.

<Warning>
  Everything a sibling agent produces is treated as **untrusted data** by the receiver. Agents are
  instructed never to follow instructions embedded in another agent's messages — coordination
  carries information, not commands.
</Warning>

## The hive tools

When coordination is enabled for your org, agents get a toolset (an MCP server):

| Tool                                                        | What it's for                                                                                                                                     |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hive_swarm`                                                | List active sibling tasks (id, role, branch). Call it first.                                                                                      |
| `hive_broadcast` / `hive_ask` / `hive_reply` / `hive_inbox` | Short mediated messages between siblings                                                                                                          |
| `beesboard_post` / `beesboard_read`                         | The **BeesBoard** — a project blackboard for declared interfaces/contracts (e.g. `module:auth.login`) so dependents build against declared shapes |
| `claim_cell` / `release_cell`                               | **Soft, advisory** file/module claims (TTL'd, auto-expiring) so two agents don't edit the same file                                               |
| `hive_conflicts`                                            | Read-only cross-branch conflict check                                                                                                             |
| `honeybox_search` / `honeybox_get`                          | Search/fetch your org's reusable skills ("HoneyBox") — trusted org content                                                                        |

You can hint the agent to use these from the New Task form's **Agent coordination**
strip, which appends coordination guidance to your prompt.

## Deterministic conflict detection

Beyond agent-to-agent chat, the orchestrator computes conflicts and diffs
**deterministically** (no LLM): it fetches sibling `task-<id>` branches and runs
`git merge-tree` to find conflicting paths, and `git diff --numstat` for pairwise
diffs with an **overlap** list of files both branches touched. This powers the
`hive_conflicts` tool and the optional **Workspace Coordinator** agent — a peer that
**never edits code**; it only detects conflicts and tells each worker to fix its own
side.

<Note>
  **Pipelines vs coordination.** A *pipeline* runs stages sequentially on **one shared branch**.
  *Coordination* is for **parallel** tasks that each have their **own** branch and need to avoid
  stepping on each other.
</Note>

## Cross-agent handoff

If a task **pauses**, you can resume it with a **different agent CLI in place** — on
the **same live pod and worktree**, with no new workspace provisioned.

<Steps>
  <Step title="On a paused task, pick a resume agent">
    The resume banner offers Claude / Codex / Gemini.
  </Step>

  <Step title="AgentBees builds a handoff brief">
    A portable, agent-neutral summary — the task, the original request, where the previous agent
    left off, the uncommitted diff, and project notes.
  </Step>

  <Step title="The new agent takes over">
    The pod swaps the CLI in place and the chosen agent continues from the brief.
  </Step>
</Steps>

<Tip>
  Handoff is great when one model gets stuck — hand the exact same in-progress workspace to a
  different agent and let it continue, without losing any state.
</Tip>