
hivemill
A self-hosted software factory of Claude Code agents with review, QA and a judge merge gate.
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up hivemill (claude-plugin project) into my current project. Found on https://claudeers.com/hivemill Repo: https://github.com/volekerb/hivemill Homepage/docs: https://github.com/volekerb/hivemill#readme Detected install method: claude-plugin → /plugin install hivemill@volekerb/hivemill Category: automation. Platforms: cli, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: unknown; community-verified: false. Confirm the source before running anything.
⚠ Unverified / not recently updated — review before pasting a run-this config.
/plugin marketplace add volekerb/hivemill /plugin install hivemill@volekerb/hivemill
git clone https://github.com/volekerb/hivemill
// compatibility
| Platforms | cli, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | Python |
Hivemill is a self-hosted software factory of Claude Code agents,
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. | A read-only web UI Goals, agents, throughput and quality, in light and dark. |
One change, five steps
- You ask. Describe what you want to the boss. It becomes a goal with success criteria.
- A team forms. A director staffs a lead, who plans tasks. Each task gets its own worktree and branch.
- A coder builds. It opens a pull request and stops. It cannot merge or review.
- Two others check. A reviewer reads the diff. QA runs the tests against the acceptance criteria.
- 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. 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.
- 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.
- 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 | Namespaced spawn for workers, with its known limits | worker-sandbox |
| Stopping a worker | Stop one agent cleanly without losing its work | stopping-a-worker |
| 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.
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, 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. 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
- Every agent is a Claude Code session, so it uses your Claude usage.
- 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, which would add real containment, is in progress.
- 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
- 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.
// faq
What is hivemill?
A self-hosted software factory of Claude Code agents with review, QA and a judge merge gate.. It is open-source on GitHub.
Is hivemill free to use?
hivemill is open-source under the MIT license, so it is free to use.
What category does hivemill belong to?
hivemill is listed under automation in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/hivemill)
// retro hit counter
[](https://claudeers.com/hivemill)
// reviews
// guestbook
// related in Automation & Workflows
The API to search, scrape, and interact with the web at scale. 🔥
🌐 Make websites accessible for AI agents. Automate tasks online with ease.
Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop