Hive Orchestration

Hive is Moxxy's multi-agent collaboration system. It provides structured orchestration through a Queen/Worker hierarchy, task boards, inter-agent signals, and voting consensus.

Overview

+-----------------------------------------------------------+
|                         Hive                               |
+-----------------------------------------------------------+
|                                                            |
|   +------------------+                                    |
|   |   Queen Agent    |                                    |
|   |   (Coordinator)  |                                    |
|   +--------+---------+                                    |
|            |                                              |
|     +------+------+------+                                |
|     |      |      |      |                                |
|     v      v      v      v                                |
|   +----+ +----+ +----+ +----+                             |
|   | W1 | | W2 | | W3 | | W4 |   Worker Agents            |
|   +----+ +----+ +----+ +----+                             |
|     |      |      |      |                                |
|     +------+------+------+                                |
|            |                                              |
|            v                                              |
|   +------------------+    +------------------+            |
|   |   Task Board     |    |   Signal Bus     |            |
|   |                  |    |                  |            |
|   |  Create / Claim  |    |  Broadcast msgs  |            |
|   |  Complete / Fail |    |  Between agents  |            |
|   |  Review / List   |    |                  |            |
|   +------------------+    +------------------+            |
|                                                            |
|   +------------------+                                    |
|   |  Voting / Consensus |                                 |
|   |                  |                                    |
|   |  Propose / Vote  |                                    |
|   |  Resolve         |                                    |
|   +------------------+                                    |
|                                                            |
+-----------------------------------------------------------+

How It Works

Queen/Worker Hierarchy

A hive has one Queen agent that coordinates work and multiple Worker agents that execute tasks.

• The Queen creates the hive, recruits workers, creates and assigns tasks, reviews results, and makes decisions
• Workers claim tasks from the board, execute them, and report results back

This is a structured orchestration pattern, not simple flat fact-sharing between agents.

Task Boards

The task board is the central work distribution mechanism. Tasks flow through a lifecycle:

created --> claimed --> completed --> reviewed
                   \-> failed

The Queen creates tasks, workers claim and execute them, and the Queen reviews the results.

Signals

Signals allow agents in a hive to communicate directly. A signal is a message broadcast to hive members, enabling coordination without going through the task board.

Voting Consensus

For decisions that need group agreement, the hive supports a proposal/vote/resolve workflow. The Queen or any worker can propose a decision, all members vote, and the proposal is resolved based on the votes.

Hive Primitives

All hive operations are performed through primitives:

Hive Management

Primitive	Description
hive.create	Create a new hive (caller becomes Queen)
hive.recruit	Recruit a worker agent into the hive
hive.disband	Disband the hive and release all workers

Task Management

Primitive	Description
hive.task_create	Create a new task on the board
hive.task_claim	Claim an available task (worker)
hive.task_complete	Mark a claimed task as complete with results
hive.task_fail	Mark a claimed task as failed
hive.task_review	Review a completed task (Queen)
hive.task_list	List tasks on the board with optional filters

Communication

Primitive	Description
hive.signal	Send a signal to hive members
hive.board_read	Read the current state of the task board

Consensus

Primitive	Description
hive.propose	Create a proposal for voting
hive.vote	Cast a vote on a proposal
hive.resolve_proposal	Resolve a proposal based on votes

Work Distribution

Primitive	Description
hive.assign	Directly assign a task to a specific worker
hive.aggregate	Aggregate results from multiple workers

Example: Research Hive

1. Queen Creates the Hive

The Queen agent creates a hive and recruits specialized workers:

hive.create({ "name": "research-team", "goal": "Research AI safety papers" })
hive.recruit({ "agent": "web-researcher-1" })
hive.recruit({ "agent": "web-researcher-2" })
hive.recruit({ "agent": "summarizer" })

2. Queen Creates Tasks

hive.task_create({
  "title": "Find recent AI safety papers",
  "description": "Search arxiv for papers on AI alignment published in 2026",
  "assigned_to": "web-researcher-1"
})

hive.task_create({
  "title": "Find industry AI safety reports",
  "description": "Search for corporate AI safety publications from major labs",
  "assigned_to": "web-researcher-2"
})

3. Workers Claim and Execute

Each worker claims its task, executes the research using browse.fetch and memory.store, then reports completion:

hive.task_claim({ "task_id": "task_001" })
# ... execute research ...
hive.task_complete({
  "task_id": "task_001",
  "result": "Found 12 papers on AI alignment from 2026..."
})

4. Queen Reviews and Aggregates

hive.task_review({ "task_id": "task_001", "verdict": "approved" })
hive.task_review({ "task_id": "task_002", "verdict": "approved" })

hive.aggregate({ "task_ids": ["task_001", "task_002"] })

5. Queen Assigns Follow-Up

hive.task_create({
  "title": "Summarize all research findings",
  "description": "Create a comprehensive summary of the collected papers and reports",
  "assigned_to": "summarizer"
})

Signals for Coordination

Signals enable real-time coordination between hive members:

# Queen broadcasts a priority change
hive.signal({
  "message": "Focus on papers from the last 3 months only",
  "target": "all"
})

# Worker reports a finding
hive.signal({
  "message": "Found a key paper that changes our research direction",
  "target": "queen"
})

Voting Example

When the team needs to make a collective decision:

# Queen proposes a direction
hive.propose({
  "topic": "Should we expand scope to include AI governance papers?",
  "options": ["yes", "no"]
})

# Workers vote
hive.vote({ "proposal_id": "prop_001", "choice": "yes" })
hive.vote({ "proposal_id": "prop_001", "choice": "yes" })
hive.vote({ "proposal_id": "prop_001", "choice": "no" })

# Queen resolves
hive.resolve_proposal({ "proposal_id": "prop_001" })
# Result: "yes" wins 2-1

Data Storage

All hive state (hives, tasks, signals, proposals, votes) is stored in the central ~/.moxxy/moxxy.db SQLite database. There is no separate swarm.db.

Best Practices

Hive Design

1. Clear goals - Define the hive's purpose when creating it
2. Specialized workers - Each worker should have a focused role
3. Granular tasks - Break work into small, well-defined tasks
4. Review everything - The Queen should review completed tasks before aggregating

Task Design

1. Descriptive titles - Workers need to understand what is expected
2. Clear acceptance criteria - Define what "done" means
3. Appropriate scope - Tasks should be completable by a single worker in one run

Coordination

1. Use signals sparingly - Signals are for important coordination, not chat
2. Use voting for decisions - When the team needs consensus, use the formal voting mechanism
3. Aggregate results - Use hive.aggregate to combine worker outputs into a unified result