
Hive
Agent coordination, distributed work.
What it is
Hive is fleet-wide agent coordination plus a triage queue. Orchestrator runtimes submit work orders, worker runtimes claim and run them, and a doctor worker triages whatever fails.
There is one bus and many workers, and no central scheduler. The one dispatch mechanism is the /v1/jobs/next dequeue: a worker asks the bus for its next job.
The three parts
- The bus. A FastAPI app. It registers agents, holds the job queue, enforces roles and eligibility, and publishes events over SSE (server-sent events).
- Workers. Thin claim-and-run loops on each host. A worker takes one kind of job, makes a fresh clone for every job, drives a local tool and reports the result.
- The doctor. A triage authority, not an executor. It claims triage and doctor jobs, runs a structured LLM diagnosis and carries out allowlisted playbook actions.
The architecture document gives the file and function behind each of these claims.
How a job moves
A job is created as queued, claimed by a worker, marked running, then finished as done or failed. needs-review is a quarantine stop for completions that lack evidence. cancelled and dead-letter retire work. offered and released are transient states the API still validates.
The complete transition table, checked by machine (STATUS_TRANSITIONS in hive/bus/domain/jobs.py):
| From | Allowed next statuses |
|---|---|
queued | queued, offered, claimed, cancelled |
offered | queued, claimed, cancelled |
claimed | queued, claimed, running, done, failed, cancelled, needs-review |
running | queued, running, done, failed, cancelled, needs-review |
needs-review | needs-review, done, failed, cancelled |
done | done, cancelled |
failed | failed, cancelled |
cancelled | cancelled |
dead-letter | dead-letter |
Who can do what
- Orchestrators may submit jobs. They include
claude-code,codex,opencode,freebuffandhuman. - Worker-only runtimes may claim and run jobs but never submit them:
hermes,zeroclaw,openclaw,ic-engineandsystem. opencodeandcodexare on both sides on purpose: they submit their own orchestration jobs and they claim work.- The doctor is limited in code to jobs whose kind starts with
triage:ordoctor:, or jobs that listdoctorineligible_kinds. A wildcard (*) is never an opt-in for it.
Registration checks that the declared kind matches the runtime, so an opencode process cannot register as claude.
What happens when a worker asks for work
At claim time the bus enforces kind affinity, required capabilities, host scope, dependencies between jobs (a DAG) and cost tier.
Submit a job
Use your own bus address in place of <bus-host>. Workers then poll the bus and claim the job themselves.
curl -s -X POST 'http://<bus-host>:5005/v1/jobs' \
-H 'Content-Type: application/json' \
-d '{
"submitter_urn": "urn:agent:human:myhost:<session_uuid>",
"kind": "code",
"description": "fix the flaky parser test",
"repo": "owner/repo",
"head_branch": "fix/flaky-parser",
"eligible_kinds": ["zeroclaw"],
"priority": 0
}'Storage and connectors
- Hive stores its data through one repository interface. The backends are SQLite (the default), PostgreSQL, MySQL, Oracle and DB2.
- An MCP bridge (Model Context Protocol, a standard way for AI tools to use outside services) exposes the bus and MNEMOS as tools.
- Harness adapters are pluggable: zoder, opencode, codex and claude.
Hive and MNEMOS
Hive works without MNEMOS: jobs are still queued, picked up, checked and merged. We strongly recommend running them together, because MNEMOS is where the stack keeps its memory. To connect them, set MNEMOS_URL and MNEMOS_TOKEN where the Hive workers run. A worker that has both adds a note to each job's brief that tells the coding agent to search for what earlier attempts on that job found and to record its progress as it goes. Hive reads those saved notes to work out why a job ended, its dashboard shows the status of every MNEMOS server, and one connector gives an agent both through a single MCP server. Without MNEMOS, every attempt starts from its brief alone, and nothing is remembered between attempts or sessions.
Settings
All the settings an operator can change, such as HIVE_URL, the bus tokens, the fleet inventory, the doctor's model endpoints and MNEMOS, are listed in one place: ENVIRONMENT.md. No address has a built-in default. Where a setting is unset, the feature it controls is turned off with one log line, not guessed.
Code and documents
Hive is a Python project and needs Python 3.11 or newer.
- graeae-hiveGRAEAE Hive: agent job bus, workers and the doctor.
See the list of all repositories for the other projects in the group.
Licensing
- Licence: Apache-2.0, as the README says. Read the graeae-hive README.