Hubd
About
The project tracker for teams of humans and AI agents — in plain files. MCP server + CLI, zero dependencies.
Details
- Author
- bzdOS
- Downloads
- 334
- Categories
- AI, Project Management, File Management, Communication, Automation, Other, Developer Tools
Jump to
- Journal (INBOX.md) – append‑only team log read and written by agents and humans.
- Per‑role message queues – agents block on wait until work arrives; one live consumer per role.
- Project cards and cross‑project tasks with owners and soft locks.
- Read‑only kanban – cards move by agent actions; humans only edit rules (AGENTS.md).
- Harvest – one pasted prompt converts any working dialog into project digests and tasks.
- Works with or without MCP – direct file access when MCP is unavailable.
- Zero dependencies; no AI inside – intelligence comes from agents, not the server.
- Multi‑machine sync via git; remote access over HTTP (token‑gated, multi‑tenant).
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
HubdCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install the binaries globally with npm i -g @bzdos/hubd (includes both hubd the MCP server and hub the CLI). Run hub init to scaffold a team folder, then hub doctor to check the setup. Connect an MCP client using claude mcp add --scope user hubd -- npx -y @bzdos/hubd. For agents without MCP, paste a prompt from the prompts/ folder. Use the CLI commands hub status, hub brief, and hub serve to interact with the data. The daemon (hubd) serves agents via JSON‑RPC 2.0 over stdio or optionally HTTP; the CLI serves humans.
hub_sync
Sync a project folder into the hub. Collects git facts automatically; pass digest (your own summary of state/next steps) and the card is rewritten.
hub_card_set
Create or update a project card from just a name and a digest — no folder needed (unlike hub_sync). Use it to capture a project that is not a local git checkout, e.g. when harvesting a dialog. Preserves any hand-written frontmatter and Facts.
hub_section_add
Append ONE line to ONE section of a project card, leaving everything around it untouched. This is how Gates / Metrics / Market and any hand-written section get written by a tool at all — hub_card_set only writes the digest, and the report router only reaches Decisions / Facts / Communication / Next step. For those four, a normal hub_report with DECIDE:/FACT:/COMM:/NEXT: is still the right call; use this for the rest. The section is created if missing (you get created:true back — check it, a typo is how a card grows two nearly identical headings).
hub_report
Append a session report to the shared journal: what was done / broken / blocked.
hub_status
Snapshot of every project at once: the latest digest of each, when it was last synced, and its open-task count, plus the most recent shared-journal entries. A project whose card has fallen behind its OWN journal carries digestStale {daysBehind, lastJournal} — the card still reads fresh while the work moved on. Best for orienting at the start of a session. For a deadline-sorted to-do list use hub_brief; for one project in depth use hub_get.
hub_get
Everything about ONE project: its full card (digest + facts), recent journal entries for it, and any active soft-locks. Use after hub_status or hub_search points you at a project.
hub_context
Auto-resolve which hub project YOUR working directory belongs to — call this at session start instead of hub_status/hub_get when you already know your cwd. Checks, most to least certain: a .hubd marker file (repo root, first line = project slug) · a project card's recorded sync path · the repo folder name as a last-resort guess (returned with guessed:true — never silently trust a name coincidence). Returns {project, via, root, guessed, digest, openTasks, activeClaims}; project is null with a hint if nothing matched.
hub_search
Full-text search across every project card and the entire journal, archived months included. Returns each matching line with its location. START HERE whenever you know a keyword, a task id or a name but not which project owns it — searching once beats guessing project × status against hub_task_list, which is how sessions have actually wasted calls. Also the way to find where something was discussed or decided.
hub_task_add
Add a task to the shared cross-project backlog.
hub_task_get
ONE task by id, plus what it is blocked by and what it blocks. Use this when you know the id — do NOT go guessing project × status combinations with hub_task_list. Know a keyword but not the id? hub_search first.
hub_task_list
List backlog tasks. Filter by project and/or status; page with limit/offset. `total` is always the full matching count, so a page never reads as the whole backlog. Looking for ONE task you can name? hub_task_get by id, or hub_search by keyword — both beat listing and scanning.
hub_task_update
Update a task: close it (status=done), reassign, reprioritise, edit text/deadline/cat.
hub_audit
Compare what the hub DECLARES with what actually happened, and turn each disagreement into an incident somebody owns. Checks: a money bet whose gate date passed with no decision since · a project whose share of the journal contradicts the MODE its card declares · owner buttons nobody pressed · a card that stopped following its own journal · tasks with no project. Read-only by default; `apply` files one incident task per finding and writes ONE report. Every finding quotes the rule it enforces with the date that rule was written (HUB/rules.json -> laws), because an engine's opinion carries no weight and your own past decision does. Findings are keyed, so a weekly run never files the same incident twice. NOT a dashboard: the numbers it prints (attention share, close rates) are a thermometer and are never filed as violations.
hub_lint
Every rule that CAN be checked, checked — the difference between a rule the hub enforces and one that is only written down somewhere. Reports a money bet whose gate has no date, and a human-owned communicative task with no prep it depends on (the owner would have to both prepare and decide). Each finding says whether the instance actually enforces it (HUB/rules.json -> strict, opt-in and empty by default) and quotes the local rule if one is declared. Read-only, never files anything.
hub_next
The ONE task to do now, and why it won — not a list. Picking from a list is work, and a session that has to pick tends to pick the easy one. A task whose dependencies are still open is never eligible, however loud it is. Says explicitly when the chosen one is the owner's to press rather than an agent's.
hub_agenda
The day split by WHO CAN ACT: agent work ready now, the owner's buttons (owner_kind human, or assigned to a role declared in HUB/owner-roles.json), what is blocked and on what, overdue and due-soon. Different question from hub_brief (everything that is going on) and hub_inbox (what needs a decision): this one answers "what can I actually start", which a mixed list hides.
hub_recall
What do we know about X — ranked across project cards, their sections, decisions, the journal and tasks, instead of hub_search's flat exact-substring list or hub_get's everything-about-one-project. Scoring is deterministic and readable: term coverage first, then where the line lives (a decision outranks a passing note), then recency. EVERY hit carries the date it was true as of and a stale flag — recall's real failure mode is handing over a two-month-old fact with this morning's confidence.
hub_usage_add
Record what only YOU can see about a piece of work: seconds, tokens, cost, model. The hub cannot observe any of these, so they arrive here explicitly and are reported back as SUPPLIED, never mixed with what the hub measured itself. At least one number is required — an empty entry would record a $0 session.
hub_usage
What the work cost, over a window, per project and per agent — with a hard line between SUPPLIED (seconds/tokens/money, reported by clients through hub_usage_add, since the hub cannot see them) and MEASURED (closed-task spans and journal events, the hub's own arithmetic). The split is the point: a cost number that mixes an observed span with a guessed rate gets quoted later as if someone had counted.
hub_rules
The team constitution (AGENTS.md) over MCP: read it, or append an amendment. hubd mechanics live in the generated HUBD.md — this is the file where the rules YOU set live. An amendment is APPENDED under one dated, attributed heading and never edits a line already there: rewriting a rule destroys the record of what it used to say, which is exactly what hub_audit needs to quote.
hub_operator
The operator card: facts and preferences about the HUMAN — rhythm, what framing works, and the Boundaries section listing what is never collected. Belongs to no project and changes slower than any of them. Agents READ Boundaries and never edit it. Returns a scaffold and how to create it if there is no card yet.
hub_brief
Morning brief across all projects: open tasks (deadlines first), journal since N hours, stale cards, cards whose digest trails their own journal (staleDigests — the misleading kind of stale), active claims, per-role queue depth with last-seen agent (broadcast roles are flagged fanout instead of a depth — their cursors are per-reader), and a buttons rollup ("N buttons waiting, oldest X days" — pending items in a human-owner queue, see HUB/owner-roles.json).
hub_kanban
The board as data: open tasks split into queued (unassigned) and in-progress (assigned), plus done-in-the-last-day and recent journal — the same view the read-only web kanban renders. Each task carries blocked and overdue flags.
hub_claim
Soft-lock a work area so other agents see it (e.g. area="public/index.html"). Not enforced — informational.
hub_release
Release a soft-lock. Pass id, or project+area+agent.
hub_heartbeat
Record that an agent is alive — call it each work cycle (right after hub_report, before the next hub_queue_wait) so MCP/headless agents show up in hub_presence the same way screen-scraped ones do, no human bridge needed. Overwrites this agent's one presence record; freshness is judged at read time from ttlMin (default 15min), the same pattern hub_claim uses.
hub_presence
The fleet roster: every agent that has called hub_heartbeat, each flagged alive/stale from its own ttlMin. hub_brief's queue section pairs with this ("N queued for role X, agent last-seen T") — visibility into delivery without screen-scraping to check who is even listening.
hub_resource_set
Create or update a resource — an infrastructure/topology entity: host, vm, service, endpoint, or provider. Structured attributes (type, address, os, provider, status) and typed relationships go in fields, NOT prose. Use this instead of describing infra inside a card digest.
hub_resource_list
List resource cards (hosts, vms, services, endpoints, providers). Optionally filter by type.
hub_resource_get
One resource card plus its inbound and outbound typed relationships.
hub_graph
The typed relationship graph across projects AND resources: who runs where, what depends on / deploys to / exposes what. Edges are frontmatter [[links]] keyed by relation (runs_on, depends_on, deploys_to, exposes, part_of, ...). Returns nodes, edges, and dangling links. Filter by project or type.
hub_onboarding
One-time orientation for an agent that has never worked with this hub before: what hubd is, which channel to use for what (claim vs task vs report vs queue — the #1 mistake), how to write a report. Call this FIRST, before anything else, the first time you connect.
hub_whatsnew
Personalized "what did I miss" — journal activity since YOUR OWN last hub_whatsnew call (tracked per agent name), not a fixed time window like hub_brief. Call this at the start of a session/sweep instead of re-reading hub_status/hub_brief from scratch; a never-seen agent gets a 24h window on its first call.
hub_inbox
What needs a DECISION right now, distilled from hubd data (not a time window like hub_brief): blocked reports, overdue open tasks, unassigned open tasks, and claim locks whose TTL expired but were never released. Returns {empty:true} when nothing needs attention — poll this instead of re-reading hub_status/hub_brief every cycle.
hub_trajectory
Deterministic dependency-graph plan over tasks' depends_on — the probable trajectory as a critical PATH, not an ML forecast. Returns: ready (doable now, no open deps), blocked (with waitingOn ids), layers (Kahn topo-order — what unlocks when), criticalPath (longest dependency chain = ordering bound), cycles (dependency loops to fix). Use to see "given deps, what is the actual order / what is the critical path to a milestone". Weight is task-count now; weighted by real durations once logd records them.
hub_queue_send
Append a message to a role's queue (queues/<role>.<node>.queue.md) for cross-agent/cross-node handoffs. Delivered to whoever calls hub_queue_wait (or `hub queue wait`) for that role, here or on a mesh-synced peer node.
hub_queue_wait
Block until new content lands in <role>'s queue (this node's file plus any mesh-synced peer files for that role), then return it — a real long-poll, not a snapshot you have to re-poll. Returns {changed:false} if nothing arrives within timeout. If a delivered block names a task (see hub_queue_send), the ids come back as `tasks` — report the outcome onto those tasks, or the message is the only place the blocker ever existed. Local/stdio only (not available on the shared HTTP server). Use this instead of a sleep-and-recheck loop when waiting on an agent to report back via hub_queue_send.
hub_queue_wait_all
Subscribe to EVERY role's queue at once and block until new content lands in ANY of them — for an orchestrator reacting to whichever agent reports first, instead of calling hub_queue_wait per role or ssh-ing into each host to poll. Returns {changed:true, events:[{role,node,text}, ...]} tagging which role/node each event came from, or {changed:false} on timeout. Uses its own offset bookkeeping — does NOT consume/steal messages from a role's own hub_queue_wait consumer, it only taps. Local/stdio only.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"hubd": {
"hubd": {
"command": "npx",
"args": [
"-y",
"@bzdos/hubd"
]
}
}
}
}McpServers
{
"hubd": {
"command": "npx",
"args": [
"-y",
"@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 — agentsandhumans: 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 thework: 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.
- 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.
Likesshdandssh. The daemon serves agents; the CLI serves you.
Option A — start a company (copy the folder).One command dropshubd-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-writtenchronicle/(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 doctor # check hub base, team root, locks, queues, ghost queues 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) 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, andHARVEST.md. It does NOT includehubd-company/.
New here? Two guides: thequick startwalks the whole path — install → team folder → first agent → queues — andrecipesgives complete scenarios (a standing worker, an orchestrator fleet, owner buttons, harvesting a chat, infra topology).
claude mcp add --scope user hubd --env HUBD_AGENT=dev-<yourproject> -- npx -y @bzdos/hubd
HUBD_AGENTis 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_AGENTis 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 thefunction, 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 fromprompts/(Claude Code, Cursor, Codex/AGENTS.md, or an MCP chat) — it wires hubd in and points atHUBD.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. Seeself-hosting.
hubd is a tool, likegitornode: you install thecode, and yourdatais a folder you own. They are two separate things — and that is the whole point.
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 — in any editor,grep, or a Markdown app like Obsidian. SeeReading your hub with any tool.
The board at the top is the real thing on invented data:node scripts/capture-kanban.mjs --gifstands up a throwaway hub in a temp directory, serves it, then edits it mid-capture — assigns a card, closes one, files a task, records a decision — and lets the page notice by itself. Nothing is staged and nobody's actual hub is ever filmed. Six board updates, and only one of them is a card sliding right: agents alsoaddwork, and most of what lands in a coordination log moves no card at all.
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 throughyouragent; hands — CLI; eyes — kanban).
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.
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.
Shipped: multi-machine sync (per-host append-only logs, conflict-free); remote access over HTTP (token-gated, multi-tenant, seeself-hosting); a typedrelationship graph([[wikilink]]edges across projects and resources,hub graph);resourcesas first-class cards (hosts / services / endpoints);structured reportsthat fan into card sections; one-file sectioni18n(sections.json); a per-nodeHUBD.mdprotocol that regenerates to match the installed version;harvestas an MCP prompt; cwd → project auto-bootstrap (hub_context: marker file / recorded sync path / folder-name guess, no manualhub_getneeded); apresence registry(hub_heartbeat/hub_presence, TTL freshness like claims) so MCP/headless agents show up next to screen-scraped ones, with queue depth surfaced inhub_brief; andbuttons— owner-decision queue items rolled up inhub_briefas "N buttons waiting (oldest X days)" (HUB/owner-roles.jsonnames the human roles).
Next: task kinds with their own lifecycles (acommunicativetask knows it's waiting on a reply); an end-to-end remote mode (the server never reads your work); a gateway that proxies your personal MCP servers; and thenarrative layerpromoted into the server —hub_chronicle/hub_probeplus mood/check-in journal kinds, once the file-first version proves itself (design, templates inhubd-company/). The file format is the stable contract; everything else is negotiable.
Keep teams & agents coordinated automatically
Official MCP server for Buildable AI-powered development platform. Enables AI assistants to manage tasks, track progress, get project context, and collaborate with humans on software projects.
Connect to the Taskade platform via MCP. Access tasks, projects, workflows, and AI agents in real-time through a unified workspace and API.
An MCP server for AI-to-AI collaboration, enabling autonomous workflows and role-based task management between different AI models.
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client, with persistent identity, real-time messaging with @mentions and threads, task handoffs, shared workspace context, semantic search, and replayable MCP App widgets.
The Outcome Backcasting MCP is a strategic planning tool that helps you work backwards from a desired future outcome to identify the specific steps, resources, and dependencies needed to achieve your goals. Unlike traditional forward planning, backcasting starts with your end goal and creates a reverse roadmap to get there.
Interact with the ClickUp API to manage tasks, lists, and spaces, automating project planning and workflows.
Apify-hosted MCP server for ClickUp with 20 tools. Tasks, spaces, folders, lists, views, docs, and custom fields. No local setup needed.
An MCP server for integrating ClickUp tasks with AI applications, featuring task dependency management and bug fixes.
多对象协作技术方案编排引擎。三个 AI Agent 并行提案、交叉审查、可行性收束，投票输出 Top 3 方案
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
