hubd

The project tracker for teams of humans and AI agents — in plain files.

A tool for agents rarely fails by crashing. It fails by answering — confidently, and wrong. A list that ended early without saying so. A count that turns out to be mostly duplicates. A task close that lands on somebody else's id. A person would stop at "wait, fifteen hundred tasks? I didn't create fifteen hundred tasks." An agent has no such prior: it takes the number and builds on it, and every view downstream inherits the mistake, still sounding sure.

hubd is built against that failure mode, and it shows in the boring parts. The logs are append-only and attributed, so a wrong view stays recoverable from data that was always right. Every truncation announces itself. Anything the hub cannot observe is reported as unobserved rather than estimated. Much of this codebase is not features — it is refusals to sound certain.

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 journal of what everyone did, task queues every agent can wait on, cross-project tasks, and a read-only kanban to watch it all. All markdown and JSONL, in a folder you own.

hub serve — the board is read-only and has exactly one button (⚙ Rules, it opens AGENTS.md). Cards move because agents move them; the page just re-reads the files.

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.

The Unix pair

• hubd — the daemon: an MCP server (stdio, JSON-RPC 2.0) that agents talk to.
• hub — the CLI: the same data for humans, no LLM required.

Like sshd and ssh. The daemon serves agents; the CLI serves you.

Quick start

Option A — start a company (copy the folder). One command drops hubd-company/ into a folder of your own:

npx degit bzdOS/hubd/hubd-company my-company   # then: cd my-company && git init

Or clone this repo and copy the folder — it doesn't have to be your repo root. You get a ready org structure: constitution (AGENTS.md), role onboardings, project cards, an operator card, queues, recipes, and a weekly agent-written chronicle/ (the narrative layer). Hiring an agent = a fresh session reads a role file. This template is NOT included in the npm package; it comes from the repo.

Option B — add the binaries to what you have:

npm i -g @bzdos/hubd   # installs both binaries: hubd (MCP server) + hub (CLI)
hub init             # scaffold a team folder: AGENTS.md, INBOX.md, queues/
hub version          # which hubd, and which copy of it is answering
hub doctor           # hub base, team root, locks, queues, ghost queues, writer versions
hub status           # every project at a glance (⚠ marks a card behind its journal)
hub brief            # morning brief: tasks, journal, locks
hub queue gc         # list queues nobody ever consumed (--apply archives them)
                     # doctor also flags: work dispatched to a role with nobody
                     # home, and queues trimmed outside hubd (which used to
                     # re-deliver everything that survived the trim)
hub now              # the ONE task to do next, and why it won
hub agenda           # the day split by who can act: agent work vs owner buttons
hub recall "<q>"     # ranked memory, every hit dated and flagged if stale
hub usage --days 7   # what the work cost: supplied vs measured, never mixed
hub audit            # what the cards declare vs what happened (--apply files incidents)
hub lint             # which of your rules are checks, not just prose
hub serve            # read-only kanban on localhost
# one-off, without install: npx -p @bzdos/hubd hub status

The npm package ships: hub/ (binaries + lib), prompts/, docs/, README.md, LICENSE, and HARVEST.md. It does NOT include hubd-company/.

New here? Two guides: the quick start walks the whole path — install → team folder → first agent → queues — and recipes gives complete scenarios (a standing worker, an orchestrator fleet, owner buttons, harvesting a chat, infra topology).

Connect your agent (any MCP client):

claude mcp add --scope user hubd --env HUBD_AGENT=dev-<yourproject> -- npx -y @bzdos/hubd

HUBD_AGENT is worth setting on day one. Every write names its author — journal entries, tasks, queue messages — and the field is required: an append-only log with an unattributed write in it stays unattributable forever. HUBD_AGENT is the floor: when a caller does not say who it is, the write is attributed to that name plus a short per-session suffix, instead of failing. Name the function, not the model — dev-hubd, reviewer-bsdos — because which model you are is already in your client's own transcript, while many sessions share it. Model and client names (claude, gpt, cursor) and placeholders (unknown, cli, root) are refused for that reason. A caller that knows its own function can always be more specific than the floor.

No MCP? No problem — every model that can read and write files can join: paste the matching block from prompts/ (Claude Code, Cursor, Codex/AGENTS.md, or an MCP chat) — it wires hubd in and points at HUBD.md, the always-current protocol.

Running it for a team? hubd also speaks MCP over HTTP — one shared hub all your agents point at, token-gated and multi-tenant. See self-hosting.

Updating, and where your data lives

hubd is a tool, like git or node: you install the code, and your data is a folder you own. They are two separate things — and that is the whole point.