hubd

hubd

O rastreador de projetos para equipes de humanos e agentes de IA — em arquivos simples.

Você executa duas, três, cinco sessões de agentes — ferramentas diferentes, fornecedores diferentes — em seus projetos. Cada uma é brilhante, e cada uma não faz ideia de que as outras existem. Você é a camada de coordenação: copiando e colando contexto, re-explicando estado, descobrindo na segunda-feira o que um agente fez na sexta.

hubd substitui você nessa função com a tecnologia mais entediante disponível: arquivos simples. Uma sede compartilhada para toda a sua equipe — agentes e humanos: um diário do que todos fizeram, filas de tarefas nas quais todo agente pode aguardar, tarefas entre projetos e um kanban somente leitura para acompanhar tudo. Tudo em markdown e JSONL, em uma pasta que é sua.

hub serve — o quadro é somente leitura e tem exatamente um botão (⚙ Regras, que abre AGENTS.md). Os cartões se movem porque os agentes os movem; a página apenas relê os arquivos.

Não é um orquestrador. Orquestradores iniciam seus agentes de codificação e transmitem sua saída — isso é tornar a codificação mais rápida. hubd gerencia o trabalho: quais projetos, o que vem a seguir, quem faz e quando, o que já aconteceu. Um orquestrador pode executar seus agentes; hubd executa seus projetos. Eles se complementam.

O par Unix

• hubd — o daemon: um servidor MCP (stdio, JSON-RPC 2.0) com o qual os agentes conversam.
• hub — a CLI: os mesmos dados para humanos, sem necessidade de LLM.

Como sshd e ssh. O daemon atende agentes; a CLI atende você.

Início rápido

Opção A — comece uma empresa (copie a pasta). Um comando coloca hubd-company/ em uma pasta de sua escolha:

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

Ou clone este repositório e copie a pasta — não precisa ser a raiz do seu repositório. Você obtém uma estrutura organizacional pronta: constituição (AGENTS.md), integrações de funções, cartões de projeto, um cartão de operador, filas, receitas e um chronicle/ semanal escrito por agentes (a camada narrativa). Contratar um agente = uma nova sessão lê um arquivo de função. Este modelo NÃO está incluído no pacote npm; ele vem do repositório.

Opção B — adicione os binários ao que você já tem:

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

O pacote npm inclui: hub/ (binários + lib), prompts/, docs/, README.md, LICENSE e HARVEST.md. Ele NÃO inclui hubd-company/.

Novo aqui? Dois guias: o início rápido percorre todo o caminho — instalação → pasta da equipe → primeiro agente → filas — e receitas fornece cenários completos (um trabalhador permanente, uma frota de orquestradores, botões de proprietário, colheita de um chat, topologia de infraestrutura).

Conecte seu agente (qualquer cliente MCP):

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

HUBD_AGENT vale a pena configurar no primeiro dia. Cada escrita nomeia seu autor — entradas de diário, tarefas, mensagens de fila — e o campo é obrigatório: um log somente anexação com uma escrita não atribuída permanece não atribuível para sempre. HUBD_AGENT é o piso: quando um chamador não diz quem é, a escrita é atribuída a esse nome mais um sufixo curto por sessão, em vez de falhar. Nomeie a função, não o modelo — dev-hubd, reviewer-bsdos — porque qual modelo você é já está no próprio transcript do seu cliente, enquanto muitas sessões o compartilham. Nomes de modelo e cliente (claude, gpt, cursor) e espaços reservados (unknown, cli, root) são recusados por esse motivo. Um chamador que conhece sua própria função pode sempre ser mais específico do que o piso.

Sem MCP? Sem problema — todo modelo que pode ler e escrever arquivos pode participar: cole o bloco correspondente de prompts/ (Claude Code, Cursor, Codex/AGENTS.md ou um chat MCP) — ele conecta o hubd e aponta para HUBD.md, o protocolo sempre atual.

Executando para uma equipe? hubd também fala MCP sobre HTTP — um hub compartilhado para o qual todos os seus agentes apontam, protegido por token e multi-tenant. Veja self-hosting.

Atualização e onde seus dados vivem

hubd é uma ferramenta, como git ou node: você instala o código, e seus dados são uma pasta que é sua. São duas coisas separadas — e esse é o ponto principal.

• Código — o pacote npm. Atualize como qualquer CLI global: npm i -g @bzdos/hubd@latest (ou execute uma vez com npx -y @bzdos/hubd). Uma nova versão entrega o mecanismo (changelog); ela nunca toca seus dados.
• Dados — HUBD_DIR (padrão ~/.hubd): markdown simples + JSONL, seus para manter.
• Quem escreveu — HUBD_AGENT: o autor padrão para chamadas que o omitem, por configuração do servidor. Defina-o em cada cliente e em cada host; um campo obrigatório sem piso transforma um argumento esquecido em uma chamada falha.
• Várias máquinas? Torne HUBD_DIR um repositório git e sincronize-o como quiser — um remoto privado via SSH funciona, sem necessidade de GitHub. Cada máquina instala o código do npm; seus dados viajam no seu próprio git. Duas trilhas separadas: código do pacote, dados na sua pasta. Atualizar o código nunca migra ou exclui seus dados — os logs de eventos são somente anexação e mais ricos do que o esquema de qualquer versão.
• O que uma atualização exige de você — às vezes uma nova versão quer algo fora do código: uma variável na configuração de um cliente, uma função declarada no hub, uma seção de protocolo que vale reler. hubd descobre isso e informa os agentes por conta própria: hub_whatsnew retorna uma lista de environment, cada item dizendo o que está errado, o que corrige e quem pode — o agente, o agente mais um reinício do cliente, ou você. Uma mudança de protocolo nomeia as seções que realmente mudaram, para que ninguém releia o manual inteiro. hub doctor mostra a mesma lista para um humano. Nada bloqueia uma chamada, nada precisa de confirmação: um item desaparece quando a condição desaparece. Estado por nó em .env-state.json, nunca sincronizado em malha — três máquinas têm três ambientes.

Como funciona

• Diário e relatórios estruturados — log de equipe somente anexação (INBOX.md) que você lê com seus olhos. No final da sessão, um agente arquiva um hub report de linhas com tags de prefixo (DECIDE: … | why, FACT:, COMM:, NEXT:, DONE: ids) que se distribuem nas seções do cartão do projeto — estrutura em campos, não em um bloco de prosa. "O que mudou" é lido do git, não redigitado. Os cabeçalhos das seções do cartão (em qualquer idioma) vêm de um arquivo, HUB/sections.json, que impulsiona tanto o scaffold do cartão quanto o roteador de relatórios — para que nunca divirjam.
• Filas — filas de mensagens por função. Envie trabalho; um agente bloqueia em wait até algo chegar, então volta a aguardar. Sem consultas a você, sem cutucadas neles. Uma fila tem um consumidor ativo por padrão — execute uma única sessão de espera por função. Funções listadas em <team>/subscriber-roles.json fazem fan-out: cada sessão em espera obtém seu próprio cursor e vê cada mensagem.
• Projetos e tarefas — um cartão por projeto; tarefas entre projetos com proprietários (agente ou humano) e reivindicações como bloqueios suaves, para que dois agentes não atropelem um ao outro.
• Recursos e relacionamentos — infraestrutura também é um cartão: hosts, VMs, serviços, endpoints, provedores sob resources/, com frontmatter estruturado (tipo, endereço, SO, provedor, status) e arestas [[wikilink]] tipadas (runs_on, depends_on, deploys_to, exposes, part_of, ...). O mesmo mecanismo de arestas lê cartões de projeto, então hub graph renderiza uma topologia entre projetos ↔ recursos; uma tarefa se vincula ao que toca com --resource. Fatos vão em campos, não em prosa.
• Kanban (somente leitura) — cartões se movem porque agentes os movem. O único botão é ⚙ Regras, e ele abre AGENTS.md. Você não gerencia os agentes — você gerencia as regras.
• Colheita — um prompt transforma qualquer diálogo de trabalho em resumos de projeto, tarefas e decisões registradas. Servido como um prompt MCP (harvest) e hub harvest, então você o invoca direto do seu cliente — sem buscar o arquivo. Veja HARVEST.md.
• MCP + arquivos, dois níveis de compatibilidade — clientes inteligentes conectam via MCP; todo o resto usa os arquivos diretamente. Se o hubd estiver fora do ar, seus dados ainda são apenas markdown.
• Instruções que permanecem atuais — suas regras de equipe vivem em AGENTS.md (suas para escrever); a mecânica do próprio hubd vive em HUBD.md, regenerada por nó a partir da versão instalada (ignorada pelo git, nunca sincronizada). Atualize o código → a próxima execução de hub (ou hub upgrade) atualiza HUBD.md, então até agentes que apenas leem os arquivos nunca seguem instruções desatualizadas.

Princípios (violar estes = não é este produto)

Arquivos primeiro. Servidor burro, agentes inteligentes — sem IA interna: hubd armazena e serve, a inteligência vem dos seus agentes. Tudo legível por humanos. Zero dependências. Somente leitura para o humano; acesso de escrita flui através de regras. Degradação graciosa: sem MCP → arquivos; sem hubd → arquivos ainda legíveis como estão — em qualquer editor, grep ou um aplicativo de Markdown como Obsidian. Veja Lendo seu hub com qualquer ferramenta.

Sobre aquela gravação

O quadro no topo é a coisa real com dados inventados: node scripts/capture-kanban.mjs --gif monta um hub descartável em um diretório temporário, o serve e então o edita durante a captura — atribui um cartão, fecha um, arquiva uma tarefa, registra uma decisão — e deixa a página perceber por conta própria. Nada é encenado e o hub real de ninguém é jamais filmado. Seis atualizações de quadro, e apenas uma delas é um cartão deslizando para a direita: agentes também adicionam trabalho, e a maior parte do que chega a um log de coordenação não move cartão algum.

O que hubd não é

Não é um orquestrador (não inicia agentes nem transmite saída). Não é memória vetorial (o diário armazena fatos que você pode ler, não embeddings). Não é um Jira para humanos (o humano aqui é um espectador e um legislador, não um designado). Não é outro chat (fale com o hubd através do seu agente; mãos — CLI; olhos — kanban).

Construído pela equipe que ele coordena

O próprio desenvolvimento do hubd passa pelo hubd: um humano e alguns agentes em modelos de fornecedores diferentes, coordenando-se através de nada além dos arquivos acima. É nosso dogfood diário — e a ilustração mais honesta que podemos oferecer do protocolo em uso real, incluindo a noite em que uma falha de ferramenta forçou tudo de volta a arquivos simples e o trabalho simplesmente continuou. A história de uma equipe, levemente anonimizada e autorrelatada, não um benchmark: o estudo de caso.

A principal função do humano era editar as regras.

Preços

O núcleo é MIT, para sempre. Uso pessoal é gratuito, para sempre. Se um plano de equipe hospedado existir, a linha é simples: agentes são gratuitos, humanos são cobrados.

Roadmap

Entregue: sincronização multi-máquina (logs somente anexação por host, sem conflitos); acesso remoto via HTTP (protegido por token, multi-tenant, veja self-hosting); um grafo de relacionamentos tipado ([[wikilink]] arestas entre projetos e recursos, hub graph); recursos como cartões de primeira classe (hosts / serviços / endpoints); relatórios estruturados que se distribuem em seções de cartão; i18n de seções em um arquivo (sections.json); um protocolo HUBD.md por nó que se regenera para corresponder à versão instalada; colheita como um prompt MCP; cwd → auto-bootstrap de projeto (hub_context: arquivo marcador / caminho de sincronização registrado / suposição de nome de pasta, sem hub_get manual necessário); um registro de presença (hub_heartbeat/hub_presence, frescura TTL como reivindicações) para que agentes MCP/headless apareçam ao lado de agentes capturados por tela, com profundidade de fila exibida em hub_brief; e botões — itens de fila de decisão de proprietário resumidos em hub_brief como "N botões aguardando (mais antigo X dias)" (HUB/owner-roles.json nomeia as funções humanas). Próximo: tipos de tarefas com seus próprios ciclos de vida (uma tarefa comunicativa sabe que está aguardando uma resposta); um modo remoto de ponta a ponta (o servidor nunca lê seu trabalho); um gateway que faz proxy de seus servidores MCP pessoais; e a camada narrativa promovida ao servidor — hub_chronicle / hub_probe além de tipos de diário de humor/check-in, uma vez que a versão baseada em arquivos se prove (design, modelos em hubd-company/). O formato de arquivo é o contrato estável; todo o resto é negociável.

Licença

MIT.