volekerb/hivemill

Hivemill is a self-hosted software factory of AI coding agents (Claude Code and Cursor),
with separate review, QA and a judge that decides the merge.

Quickstart · Docs · Examples · Adopt with Claude · Security · Discussions

https://github.com/user-attachments/assets/dfec91f4-de05-4592-aaec-3662ce674c4a

how it was made · seeded demo data only

What you get

You describe what you want built to one boss agent. A director staffs a team, and a chain of coders, QA, reviewers and a judge ships it as pull requests. The agent that writes a change never reviews, tests or merges it. Hivemill's CLI is factory.

Fixed roles Each role has its own prompt and permissions, enforced by hooks rather than by trust.	Independent review A separate reviewer and QA check every pull request against a real test run.	A judge merges Only on passing reviewer and QA verdicts. Anything else goes back with findings.
One source of truth Goals, tasks, messages and verdicts are rows in SQLite with an append-only log.	Small-box friendly A spawn gate queues agents until RAM, load and Claude process count allow.
Two runtimes, side by side A Claude org and a Cursor org, each a full chain of command, share one box and one DB (runtimes).	A read-only web UI Goals, agents, throughput, quality, and cost, tokens and wall time per task, in light and dark.	Opt-in containment A worker guard on every tool call, an optional sandbox, a GitHub token per worker role and optional per-task clones (guard, sandbox).

One change, five steps

1. You ask. Describe what you want to the boss. It becomes a goal with success criteria.
2. A team forms. A director staffs a lead, who plans tasks. Each task gets its own worktree and branch.
3. A coder builds. It opens a pull request and stops. It cannot merge or review.
4. Two others check. A reviewer reads the diff. QA runs the tests against the acceptance criteria.
5. A judge decides. Both pass, it merges. Either fails, it goes back with findings. Every verdict is stored.

The roles and the merge gate as diagrams are under How it works.

The factory runs on herdr, the terminal multiplexer that hosts the agent panes (source, pinned release v0.9.5).

Quickstart

Install

Needs a fresh Debian or Ubuntu machine and a logged-in Claude Code (the Cursor org also needs the Cursor Agent CLI, see docs/runtimes.md). In Claude Code:

/plugin marketplace add volekerb/hivemill
/plugin install hivemill
/hivemill:setup

The full guide, with the installer options and the manual steps, is docs/SETUP.md.

Look around without installing

Seeded fictional data, nothing real runs (docs/demo-data.md). Run from the repository root:

export TRIAL=$(mktemp -d)
python3 ci/demo_seed.py --home "$TRIAL/demo" --now 2026-10-25T12:00:00+01:00
HOME=$TRIAL/demo/home FACTORY_HOME=$TRIAL/demo bin/factory serve --bind 127.0.0.1 --port 18624

Open http://127.0.0.1:18624/ to see the read-only web UI on the demo data. In another shell, put HOME=$TRIAL/demo/home FACTORY_HOME=$TRIAL/demo in front of factory goal list to see the demo goals as a table.

A task's life in commands

Three walkthroughs with full output on the demo data: from a goal to a merged PR, handling a rejection, the digest and scorecard.

How it works

• Separation of roles. Each role has its own prompt and its own permission settings, enforced by hooks rather than by trust.
• Two orgs, one box. An org is a complete chain of command (boss, director, leads, workers) on one runtime and one model map: claude (Claude Code, the default) and cursor (Cursor Agent). Each goal belongs to one org, every spawn inherits it, and both orgs share one agent cap and one resource gate (docs/runtimes.md).
• Evidence over claims. A task is done when a reviewer and QA have checked the PR diff and a real test run, not when an agent says so.
• Resource-aware on a small box. A spawn gate watches RAM, load and the number of Claude processes, and queues new agents until there is room. The whole factory runs on one modest VM.
• Contained workers. A worker guard hook blocks actions outside a role's job. Opt-in extras: the worker sandbox (sandbox_roles), a worker GitHub token per role (worker_gh_roles) and a standalone clone per coder task instead of a worktree (task_clones, off by default; docs/git-hardening.md). The guard is Python by default; a Go port is available through guard_impl (docs/worker-guard-go.md).
• Everything auditable. Goals, plans, tasks, messages, verdicts and decisions are rows in SQLite with an append-only event log, exported to readable markdown every minute.

flowchart TB
    owner([owner]) <--> boss
    boss <--> director
    director <--> lead["team leads (lead)"]
    lead --> pm
    lead --> coder
    lead --> qa
    lead --> reviewer
    lead --> judge
    director --> cleaner

    subgraph infra [Infrastructure]
        direction LR
        tick["tick (systemd timer, every minute)"]
        herdr["herdr panes (one per agent)"]
        db[("SQLite DB + factory CLI")]
        web["web UI (read-only)"]
    end

    tick -->|"reap, spawn, nudge, export"| herdr
    herdr -->|"hosts every agent"| boss
    boss -.->|"factory CLI"| db
    director -.->|"factory CLI"| db
    lead -.->|"factory CLI"| db
    db --> web
    tick --> db

The merge gate, for every change:

flowchart LR
    coder["coder opens PR"] --> reviewer["reviewer: diff verdict"]
    coder --> qa["qa: test and acceptance verdict"]
    reviewer --> judge{"judge"}
    qa --> judge
    judge -->|"both pass"| merge["merge to main"]
    judge -->|"any fail"| retry["back to coder with findings"]
    merge --> cleaner["cleaner removes worktree and branch"]

Details: docs/lifecycle.md, docs/verdict-gates.md, docs/db-layout.md.

Features

Feature	What it does	Docs
Run it
Setup and operations	Install, boot units, reboot recovery, identity rules	SETUP, operations
Adopt with Claude	An instruction file your own Claude Code follows to install it	ADOPT
Ship safely
Verdict gates	The judge merges only on passing reviewer and QA verdicts	verdict-gates
Goal lifecycle	From request to goal to done, with plan and success criteria	goal-lifecycle
Contain agents
Worker guard	Hooks that block actions outside a role's job	worker-guard
Worker sandbox	Opt-in namespaced spawn and worker GitHub tokens, with known limits	worker-sandbox
Per-task clones	Optional standalone clone per coder task (task_clones)	git-hardening
Stopping a worker	Stop one agent cleanly without losing its work	stopping-a-worker
Two runtimes
Claude and Cursor orgs	Orgs, runtimes, model maps and message routing	runtimes
See it
Web UI	Read-only pages for goals, tasks, agents, throughput and quality	web-ui
State branch	Markdown exports and a DB dump pushed to the state branch	state-branch

Each feature has its own file under docs/ (all pages: docs/README.md). Also: tests and CI, lessons, per-role plugins, updating persistent agents, boss mail.

back to top

How it compares

	One Claude Code session	Hand-run subagents	Hivemill
Role separation	One agent plans, writes and judges its own work	You choose the roles each time	Fixed roles with their own prompts and permissions, enforced by hooks (worker-guard)
Independent review	The author reviews itself	Only if you start a reviewer	A separate reviewer and QA check every PR (verdict-gates)
Merge gate	You merge by hand	You merge by hand	The judge merges, gated on reviewer and QA (verdict-gates)
State and audit	The chat transcript	Whatever you wrote down	Goals, tasks, messages and verdicts in SQLite with an append-only event log (db-layout)
Resource gate	None	None	A spawn gate queues agents until RAM, load and Claude process count allow (spawn-queue)
Recovery after reboot	Start over	Start over	Boot units resume the headquarters and active teams (operations)

Works with: Claude Code, Cursor Agent, herdr, gh, systemd user units and the Moshi phone app.

The web UI

A read-only web UI shows goals, tasks, live agents, throughput and quality, in light and dark themes, with an org filter, a runtime chip per agent and cost, tokens and wall time per task. Start it with factory serve (docs/web-ui.md). The screenshots come from fictional demo data only (docs/demo-data.md); click one for the full-size light image.

Overview: agents, PRs, goals and usage	Goals: status and priority	Tasks: status, assignee and PR
Agents: live agents by role and team	Throughput: merged changes over time	Quality: rejections and retries per team
Goal detail: intent, plan, teams and tasks

Status and limits

• An agent is a Claude Code or a Cursor Agent session, depending on its org, so it uses your Claude or Cursor usage. Claude is the default.
• The hc (herdr-core) terminal backend is experimental and off by default (docs/terminal-backends.md).
• It is built for a single box, not a cluster. State is one SQLite file.
• Agent isolation is a tripwire, not a sandbox. Hooks and permission settings stop honest mistakes and make bypasses visible; they do not contain a determined adversary. Read SECURITY.md for the threat model and the known limits before you point it at anything you cannot afford to lose.
• The worker sandbox is opt-in (sandbox_roles, off by default) and a tripwire, not a boundary: it has no egress filter (docs/worker-sandbox.md).
• The web UI is read-only and has no authentication; bind it to an address you trust.

Not affiliated with Anthropic. Claude and Claude Code are products of Anthropic.

Use it from your phone

Install Moshi on your phone, connect to your box over SSH, and run herdr there to reach the boss's pane. Moshi is a third-party app, not part of Hivemill.

Resources

• What's new in v0.4.0: a short plain-English summary of this release.
• docs/examples/: three walkthroughs with real output.
• docs/README.md: index of every docs page. docs/SETUP.md: install and troubleshooting.
• docs/finishing-coders.md: how coders finish. Known gaps of the worker guard.
• docs/worker-sandbox.md: worker sandbox design, owner steps, rollout, rollback.
• docs/adopt/ADOPT.md: let your own Claude Code set it up.
• CHANGELOG.md, SECURITY.md, THIRD_PARTY.md, CODE_OF_CONDUCT.md.

Contributing

Read CONTRIBUTING.md first. A feature PR adds or edits its docs/.md page and does not edit this README. Small, well-scoped places to start are in docs/STARTER_ISSUES.md. Report vulnerabilities as described in SECURITY.md.

License

MIT. Third-party notices: THIRD_PARTY.md.

back to top