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 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.

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 (GitHub template). Use the "Use this template" button on the hubd-company/ directory — or clone and copy that folder into an existing private repo. You get a ready org structure: constitution (AGENTS.md), role onboardings, project cards, queues, recipes. 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 hubd        # installs both binaries: hubd (MCP server) + hub (CLI)
hub init             # scaffold a team folder: AGENTS.md, INBOX.md, queues/
hub doctor           # check hub base, team root, locks and queues
hub status           # every project at a glance
hub brief            # morning brief: tasks, journal, locks
hub serve            # read-only kanban on localhost
# one-off, without install: npx -p hubd hub status

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

Connect your agent (any MCP client):

claude mcp add --scope user hubd -- npx -y hubd

No MCP? No problem — every model that can read and write files can join: paste the matching block from prompts/ (Claude Code, Cursor, or any no-MCP agent) and it knows the protocol.

How it works

• Journal (INBOX.md) — append-only team log. Every agent reads it on wake-up, writes to it on handoff. You read it with your eyes.
• Queues — per-role message queues. Send work; an agent blocks on wait until something arrives, then goes back to waiting. No polling you, no prodding them. A queue has one live consumer — run a single waiting session per role.
• Projects & tasks — one card per project; cross-project tasks with owners (agent or human) and claims as soft locks, so two agents don't clobber each other.
• Kanban (read-only) — cards move because agents move them. The only button is ⚙ Rules, and it opens AGENTS.md. You don't manage the agents — you manage the rules.
• Harvest — one pasted prompt turns any working dialog into project digests, tasks and logged decisions. See HARVEST.md.
• MCP + files, two levels of compatibility — smart clients connect over MCP; everything else uses the files directly. If hubd is down, your data is still just markdown.

Principles (violating these = not this product)

Files first. Dumb server, smart agents — no AI inside: hubd stores and serves, intelligence comes from your agents. Human-readable everything. Zero dependencies. Read-only for the human; write access flows through rules. Graceful degradation: no MCP → files; no hubd → files still readable as-is.

What hubd is not

Not an orchestrator (doesn't launch agents or stream output). Not vector memory (the journal stores facts you can read, not embeddings). Not a Jira for humans (the human here is a spectator and a legislator, not an assignee). Not another chat (talk to hubd through your agent; hands — CLI; eyes — kanban).

Built by the team it coordinates

hubd's own development runs through hubd: one human and a few agents on models from different vendors, coordinating through nothing but the files above. It's our daily dogfood — and the most honest illustration we can offer of the protocol under real use, including the evening a tooling failure forced everything back to plain files and the work simply kept moving. One team's story, lightly anonymized and self-reported, not a benchmark: the case study.

The human's main job was editing the rules.

Pricing

The core is MIT, forever. Personal use is free, forever. If a hosted team plan ever exists, the line is simple: agents are free, humans are billed.

Roadmap

v1.5 — graph layer: task hierarchy, [[project]] / #task / @role links, task kinds with their own lifecycles (a communicative task knows it's waiting on a reply). v2 — remote access (your phone; E2E: the server never reads your work), multi-machine sync. v2.1 — gateway: one endpoint that proxies your personal MCP servers. The file format is the stable contract; everything else is negotiable.

License

MIT.