bzdOS/hubd

**The project tracker for teams of humans and AI agents — in plain files.**
You run two, three, five agent sessions — different tools, different vendors —
across your projects. Each one is brilliant, and each one has no idea the
others exist. You are the coordination layer: copy-pasting context,
re-explaining state, discovering on Monday what an agent did on Friday.
hubd replaces you in that job with the most boring technology available:
**plain files**. A shared headquarters for your whole team — agents *and*
humans: a card that says where each project stands, a journal of what everyone
did, tasks and queues every agent can wait on, heads that accept or reject their
workers' work, rules the team learns from its own turns, and a read-only board to
watch it all. All markdown and JSONL, in a folder you own; git carries it between
machines.
*hub serve on the demo hub. Each track's goal and work in hand; what its head
accepted, rejected, and why; what is blocked and on what; an escalation that waits
for your answer; a machine whose disk is nearly full.*
**Not a runner.** Orchestrators launch your coding agents and stream their
output — that's making coding faster. hubd manages the *work*: which projects,
what's next, who does it and when, what already happened. An orchestrator can
run your agents; hubd runs your projects. They compose.
Try it in a minute
hub demo writes an invented week of a small team into a folder of its own and
prints the commands to look at it: the board on a port beside your own,
hub board, hub agenda, the rules about to become laws, hub recall. Your own
hub is not read or written. Run it again for a fresh week; delete the folder when
you are done.
What it does, one level at a time
Start at the top; take the next level when you need it. Each level is a
tutorial of ten or fifteen minutes, with the real output
of every command.
| Level | What you get | Start with |
|---|---|---|
| **1. Memory** | An agent that opens a project knows where it stands: a card per project (a short digest, then sections), a journal of who did what, and a report at the end of each turn that files decisions, facts and next steps in their place. A session resumed after a compaction asks the hub, not its summary. | hub_context, hub report, hub recall, hub whereami |
| **2. Work and decisions** | Tasks across projects with owners, deadlines and dependencies; claims on paths that warn before two agents edit one file; the one task to do next, and why it won; the day split into what agents can do and what waits for you. | hub task add, hub now, hub agenda, hub plan, hub claim |
| **3. Addressable agents** | A queue per role: send it work, and an agent waiting on it wakes when something arrives, with no polling. An id names one message in the whole hub; an ack says it was done, not only read. In work mode a role's open tasks are its queue. | hub queue send, hub queue wait, hub_queue_ack |
| **4. Several machines** | One hub in a git repository that every machine syncs. Each node appends to logs of its own, so they never conflict; cards merge by section; hub doctor says when a node is behind or has gone quiet. | scripts/mesh-sync.sh, hub card merge-driver, hub doctor |
| **5. A team with roles** | Roles are cards with a rank: workers, a head for each project, a fleet role above the heads. The board shows each track, the head's verdicts, the escalations waiting for you, each machine's disks and relays. Each kind of role runs by one template of rules. | hub resource set, hub board, hub serve, hub prompts render |
| **6. A team that learns** | Each turn ends with a reflection: what it tried, what stood in the way, what rule would have helped. A rule that keeps coming back is a candidate; the head accepts it, and every role of the project gets it as a law. | hub reflect, hub reflect --promote |
| **7. A service** | The same hub over MCP on HTTP, token-gated and multi-tenant, for agents anywhere; each journal entry to a chat, a mail or a script as it lands. | hubd --http, hub watch --exec |
The words in this table — card, track, head, law — are defined in