Você cria um épico com 15 subtarefas. Distribui entre um punhado de agentes ou colegas de equipe. Dois dias depois, alguém pergunta: "Quanto avançou a reescrita do auth?"

Você roda bd show bb-r4f. Isso te dá o épico em si. Título, descrição, prioridade. Não te diz quantos filhos estão completos. Então roda bd list --parent bb-r4f. Obtém uma lista plana de IDs e títulos. Para ver o status de cada um, passa por jq ou roda bd show em cada filho individualmente. Alguns desses filhos têm suas próprias subtarefas. Agora você está três níveis de profundidade, reconstruindo uma árvore na sua cabeça a partir da saída do terminal.

Isso funciona quando um épico tem três filhos. Desmorona com dez. E se você está coordenando agentes de IA que criam subtarefas, reportam bloqueadores e fecham issues em rápida sucessão, a saída da CLI fica obsoleta entre o momento em que você roda o comando e o momento em que termina de lê-lo.

O problema não é o beads. O CLI do beads é excelente para gestão estruturada e scriptável de issues. O problema é que progresso hierárquico é um conceito visual, e terminais renderizam texto em linhas.

Como uma árvore de épico se parece no Beadbox

Abra o Beadbox, clique em um épico, e você vê seus filhos em uma árvore colapsável. Cada filho mostra um badge de status (open, in_progress, ready_for_qa, closed), um indicador de prioridade e o responsável. O épico em si mostra uma barra de progresso: "9 de 14 completos (64%)." Esse número atualiza conforme filhos são fechados.

Expanda um filho que é ele mesmo um épico e você vê suas subtarefas aninhadas abaixo. O progresso do pai agrega de todos os descendentes, não apenas dos filhos diretos. Um épico de três níveis com 40 issues no total entre engenharia, QA e documentação mostra o percentual real de completude no topo, contando cada nó folha da árvore.

Issues bloqueados recebem um tratamento visual distinto. Se bb-m3q depende de bb-k7p e bb-k7p ainda está aberto, o badge de bloqueado aparece ao lado do status de bb-m3q. Não precisa rodar bd dep list para descobrir o gargalo. Está visível na árvore, no nível onde importa.

Compare com o workflow de CLI. Para responder "o que está bloqueando o progresso do épico de auth", você rodaria:

bd list --parent bb-r4f --status=open --json | \
  jq -r '.[].id' | \
  xargs -I{} bd show {} --json 2>/dev/null | \
  jq -r 'select(.blocked_by | length > 0) | "\(.id) blocked by \(.blocked_by | join(", "))"'

É um pipeline perfeitamente válido. Retorna a resposta certa. Mas você tem que escrevê-lo, lembrar dos flags, e re-rodar toda vez que quiser uma atualização. No Beadbox, a mesma informação está sempre visível na árvore. Sem query necessária.

Atualizações em tempo real: a árvore muda enquanto você observa

É aqui que o modelo visual prova seu valor. Quando um agente roda bd update bb-k7p --status=closed no terminal, o Beadbox capta a mudança no sistema de arquivos em milissegundos. O servidor WebSocket detecta a escrita no diretório .beads/, difunde a mudança, e a UI React re-renderiza.

Na árvore de épico, isso se parece com: bb-k7p muda de um badge laranja "in_progress" para um badge verde "closed". A barra de progresso do épico pai sobe de 64% para 71%. E bb-m3q, que estava bloqueado por bb-k7p, perde seu indicador de bloqueio e aparece como trabalho disponível.

Tudo isso acontece sem você rodar um comando ou clicar em um botão de refresh. Se você está supervisionando uma frota de agentes trabalhando em um épico de release, observa a árvore se preenchendo conforme tarefas se completam. Gargalos emergem no momento em que se formam porque badges de bloqueio aparecem em tempo real. Subárvores estagnadas (clusters de issues que param de mudar de status) ficam visualmente óbvias após alguns minutos de inatividade contra um fundo de progresso constante em outras partes.

O mecanismo subjacente é direto. Beadbox roda um servidor WebSocket que chama fs.watch() no seu diretório .beads/. Cada escrita no banco de dados dispara uma difusão. O hook do lado do cliente recebe o sinal e re-busca a server action relevante. Sem intervalo de polling, sem refresh manual. A latência do comando CLI até a atualização da UI é tipicamente menor que um segundo.

Navegação keyboard-first

Beadbox é um app desktop para desenvolvedores, e se comporta como tal. j e k percorrem a lista de issues (estilo vim). Enter abre o issue selecionado no painel de detalhes. / foca a barra de busca. Escape fecha o que estiver aberto. As setas expandem e colapsam nós da árvore de épico.

Você pode fazer triagem de um backlog inteiro sem tocar no mouse. Desça pela lista com j, abra um issue para ler sua descrição, pressione Escape para fechar, passe ao próximo. Se encontrar algo que precisa de mudança de status, desce ao terminal para mutações (bd update). Beadbox é uma interface pesada em leitura por design. O CLI lida com escritas. O GUI lida com compreensão.

Essa separação é intencional. Um GUI que tenta substituir o CLI para escritas acaba construindo formulários para cada combinação possível de flags. Um GUI que foca em leitura e navegação pode otimizar para o que terminais fazem pior: mostrar dados hierárquicos e com referências cruzadas de relance.

Múltiplos projetos, uma janela

Se você trabalha em mais de um codebase, cada um com seu próprio banco de dados .beads/, o seletor de workspace do Beadbox cuida disso. Um dropdown no header lista cada workspace detectado. Clique em um (ou encontre o workspace com a busca /), e toda a view recarrega do banco de dados daquele projeto. Filtros e posição de scroll persistem por workspace, então voltar não perde seu lugar.

A detecção é automática. Beadbox escaneia workspaces registrados na configuração do bd e diretórios contendo bancos de dados .beads/. Adicione um novo projeto, inicialize beads nele, e na próxima vez que abrir o Beadbox ele aparece no dropdown. Sem importação, sem tela de configuração.

Para desenvolvedores que mantêm vários serviços, ou para times onde cada agente trabalha em um repositório separado, isso transforma o Beadbox em um painel único de todos os projetos ativos. A alternativa é múltiplas janelas de terminal, cada uma rodando bd list contra um path --db diferente.

O que isso substitui

Beadbox não substitui o CLI. Se você scripta seus workflows, passa bd list por jq, ou tem agentes que criam e fecham issues programaticamente, tudo isso continua funcionando igual. Beadbox lê o mesmo banco de dados em que seus scripts escrevem.

O que ele substitui é o overhead mental de reconstruir o estado do projeto a partir de saída de texto plano. As perguntas que o Beadbox responde de relance, e que o CLI responde apenas por queries compostas:

Quanto realmente avançou esse épico?
O que está bloqueado agora, e por quê?
Quais subtarefas não foram tocadas há horas?
Os agentes estão progredindo, ou estagnaram?

São perguntas visuais. Merecem respostas visuais.

Para começar

Beadbox é gratuito durante o beta. Instale com Homebrew:

brew tap beadbox/cask && brew install --cask beadbox

Se você já usa beads, o Beadbox detecta seus workspaces .beads/ ao iniciar. Sem importação, sem conta. Abra o app, expanda um épico, e veja onde seu projeto realmente está.

Roda em macOS, Linux e Windows.