Hai cinque agenti AI di coding che lavorano su un'epic. L'Agent 1 sta costruendo il livello API. L'Agent 2 ha bisogno di quell'API per collegare il frontend. L'Agent 3 sta scrivendo test di integrazione che dipendono da entrambi. Gli Agent 4 e 5 gestiscono migrazioni e documentazione, ognuno bloccato su pezzi diversi.
Funziona per una ventina di minuti. Poi l'Agent 2 si blocca perché l'Agent 1 ha incontrato un problema di schema inaspettato. L'Agent 3 è ora bloccato dall'Agent 2, che è bloccato dall'Agent 1. Gli Agent 4 e 5 continuano a lavorare, ma il loro lavoro non può fare merge finché la catena non si risolve. Non lo scopri finché non ti chiedi perché nulla è stato rilasciato in un'ora e inizi a eseguire bd blocked su ogni issue.
L'informazione sulle dipendenze esiste. Vive nel tuo issue tracker. Ma quando la gestisci tramite CLI, stai ricostruendo il grafo a mente dall'output testuale piatto. Quella ricostruzione fallisce esattamente nel momento in cui conta di più: quando il grafo è complesso e le cose si stanno rompendo.
Come beads traccia le dipendenze
beads è un issue tracker basato su git costruito per il coordinamento di agenti AI. Salva tutto in un database Dolt locale dentro la directory .beads/ del tuo repository. Nessun servizio cloud, nessun account, nessun conflitto di sincronizzazione.
Gli agenti dichiarano le dipendenze con un singolo comando:
bd dep add ISSUE-42 ISSUE-37
Questo registra che ISSUE-42 dipende da ISSUE-37. ISSUE-42 non può procedere finché ISSUE-37 non viene chiusa. La query inversa è altrettanto semplice:
bd blocked
Restituisce ogni issue nel workspace attualmente bloccata da una dipendenza non risolta. E per una issue specifica:
bd dep list ISSUE-42
Mostra da cosa dipende ISSUE-42 e cosa dipende da ISSUE-42.
Il modello dati è pulito. Il problema non è registrare le dipendenze. Il problema è vederle. Quando hai 30 issue attive su cinque agenti, eseguire bd blocked ti dà una lista. Una lista non ti mostra che ISSUE-12 è un collo di bottiglia che blocca sette task a valle su tre agenti. Una lista non ti mostra che l'Agent 3 ha creato una catena di dipendenze circolare tra ISSUE-18 e ISSUE-22. Ti serve una vista spaziale del grafo, non sequenziale.
Cosa ti mostra Beadbox
Beadbox è un'app desktop nativa che avvolge la CLI beads con un'interfaccia visuale. Legge dallo stesso database .beads/ su cui scrivono i tuoi agenti e si aggiorna in tempo reale mentre lavorano.
Nella vista albero epic, ogni issue con dipendenze non risolte mostra un badge bloccato inline. Vedi l'intera struttura ad albero della tua epic, con le issue bloccate segnalate a colpo d'occhio. Nessun comando da eseguire, nessun output da analizzare.
La catena delle dipendenze è visibile spazialmente. Se ISSUE-42 dipende da ISSUE-37, e ISSUE-37 dipende da ISSUE-15, e ISSUE-15 è assegnata all'Agent 1 che è bloccato, puoi tracciare quella catena scansionando l'albero. Vedi la forma del collo di bottiglia senza ricostruirlo da query CLI separate.
La componente in tempo reale conta. Quando l'Agent 1 finalmente chiude ISSUE-15, la UI di Beadbox lo riflette entro un secondo. Il badge bloccato su ISSUE-37 scompare. Se ISSUE-37 era l'unica cosa che bloccava ISSUE-42, anche quel badge scompare. Guardi la catena di dipendenze collassare man mano che il lavoro viene completato, senza fare refresh o ri-query.
Sotto il cofano, funziona tramite una pipeline lineare: un server WebSocket monitora la directory .beads/ con fs.watch(). Quando un agente scrive nel database (chiude una issue, aggiunge una dipendenza, aggiorna uno stato), l'evento filesystem innesca un broadcast a tutti i client connessi. La UI React si ri-renderizza con dati freschi. Latenza sotto il secondo dall'azione dell'agente all'aggiornamento visivo.
Uno scenario concreto: individuare un collo di bottiglia
Cinque agenti stanno lavorando su un'epic con 24 issue. Apri Beadbox e guardi l'albero epic. Dodici issue sono in corso. Sei mostrano badge bloccati.
Questa è già informazione che non avevi. bd list ti mostrerebbe 12 issue in-progress, ma dovresti eseguire bd blocked separatamente e fare il riferimento incrociato per capire quali issue in corso sono effettivamente in stallo.
Scansioni i badge bloccati e noti qualcosa: quattro delle sei issue bloccate dipendono tutte da ISSUE-19, una migrazione dello schema del database assegnata all'Agent 4. L'Agent 4 ci sta ancora lavorando, ma ISSUE-19 è diventata un singolo punto di collo di bottiglia. Quattro agenti sono di fatto fermi, in attesa di un solo task.
Senza la vista visuale, potresti non accorgertene per un'altra ora. Con essa, puoi intervenire subito. Forse riassegni ISSUE-19 a un agente più veloce. Forse la suddividi in pezzi più piccoli che possono sbloccare alcuni dipendenti prima. Forse ti rendi conto che due di quelle quattro dipendenze erano state dichiarate in eccesso e le rimuovi con bd dep remove.
Il punto non è che l'informazione non fosse disponibile prima. Era sempre nel database. Il punto è che la rappresentazione visuale fa emergere pattern che il testo piatto oscura.
Anti-pattern comuni delle dipendenze
Gestire più agenti AI su un unico repository produce alcuni problemi ricorrenti di dipendenza. Tutti sono più facili da individuare visivamente che tramite query CLI.
Dichiarazione eccessiva. Gli agenti tendono a essere conservativi. Nel dubbio, dichiarano una dipendenza. Il risultato è un grafo delle dipendenze più denso del necessario, con issue bloccate su lavoro di cui non hanno realmente bisogno. In Beadbox, lo noti quando una issue mostra un badge bloccato ma la issue bloccante è in una parte completamente diversa del codebase. Un rapido bd dep remove risolve la cosa.
Catene circolari. L'Agent A dichiara una dipendenza sul lavoro dell'Agent B. L'Agent B, lavorando indipendentemente, dichiara una dipendenza sul lavoro dell'Agent A. Ora entrambi sono bloccati l'uno dall'altro e nessuno può procedere. La CLI beads intercetta le dipendenze circolari ovvie al momento della creazione, ma i cicli indiretti attraverso tre o più issue sono più difficili da rilevare. Nell'albero epic, li noti come gruppi di badge bloccati che non si risolvono mai, anche mentre altro lavoro viene completato intorno a loro.
Colli di bottiglia a singolo punto. Una issue accumula cinque, sei, sette dipendenti a valle. Succede naturalmente quando agenti che lavorano in parallelo hanno tutti bisogno dello stesso pezzo fondamentale. Lo scenario sopra illustra il pattern. In una vista lista, vedi sette issue bloccate. In una vista albero, vedi sette frecce che puntano allo stesso nodo. Il collo di bottiglia è ovvio.
Per iniziare
Beadbox funziona su macOS, Linux e Windows. Installalo con Homebrew:
brew tap beadbox/cask && brew install --cask beadbox
Puntalo a qualsiasi repository con una directory .beads/. Se stai già usando beads con la tua flotta di agenti, Beadbox prende il database esistente e inizia a renderizzare immediatamente. Nessun passaggio di importazione, nessuna configurazione, nessun account.
I tuoi agenti continuano a usare la CLI. Eseguono bd dep add, bd update, bd close come al solito. Beadbox monitora il database e riflette ogni modifica in tempo reale. Ottieni il livello visuale senza cambiare nulla nei workflow degli agenti.
Beadbox è gratis durante la beta.
Se stai coordinando più agenti AI su un singolo codebase, il grafo delle dipendenze è la prima cosa che romperà il tuo workflow. Puoi gestirlo alla cieca tramite la CLI, oppure puoi vederlo. Vederlo è più veloce.