Visualizing Dependencies Between AI Agents in Real Time

You have five AI coding agents working a feature epic. Agent 1 is building the API layer. Agent 2 needs that API to wire up the frontend. Agent 3 is writing integration tests that depend on both. Agents 4 and 5 are handling migrations and docs, each blocked on different pieces.

This works for about twenty minutes. Then Agent 2 stalls because Agent 1 hit an unexpected schema problem. Agent 3 is now blocked on Agent 2, which is blocked on Agent 1. Agents 4 and 5 keep churning, but their work can't merge until the chain resolves. You don't find out until you wonder why nothing has shipped in an hour and start running bd blocked across every issue.

The dependency information exists. It lives in your issue tracker. But when you manage it through a CLI, you're reconstructing the graph in your head from flat text output. That reconstruction fails at exactly the moment it matters most: when the graph is complex and things are breaking.

How beads tracks dependencies

beads is a git-backed issue tracker built for AI agent coordination. It stores everything in a local Dolt database inside your repo's .beads/ directory. No cloud service, no accounts, no sync conflicts.

Agents declare dependencies with a single command:

bd dep add ISSUE-42 ISSUE-37

This records that ISSUE-42 depends on ISSUE-37. ISSUE-42 cannot proceed until ISSUE-37 closes. The inverse query is just as simple:

bd blocked

That returns every issue in the workspace currently blocked by an unresolved dependency. And for a specific issue:

bd dep list ISSUE-42

This shows what ISSUE-42 depends on and what depends on ISSUE-42.

The data model is clean. The problem isn't recording dependencies. The problem is seeing them. When you have 30 active issues across five agents, running bd blocked gives you a list. A list doesn't show you that ISSUE-12 is a bottleneck blocking seven downstream tasks across three agents. A list doesn't show you that Agent 3 created a circular dependency chain between ISSUE-18 and ISSUE-22. You need a spatial view of the graph, not a sequential one.

What Beadbox shows you

Beadbox is a native desktop app that wraps the beads CLI with a visual interface. It reads from the same .beads/ database your agents write to, and it updates in real time as they work.

In the epic tree view, every issue that has unresolved dependencies shows a blocked badge inline. You see the full tree structure of your epic, with blocked issues marked at a glance. No command to run, no output to parse.

The dependency chain is visible spatially. If ISSUE-42 depends on ISSUE-37, and ISSUE-37 depends on ISSUE-15, and ISSUE-15 is assigned to Agent 1 which is stuck, you can trace that chain by scanning the tree. You see the shape of the bottleneck without reconstructing it from separate CLI queries.

The real-time piece matters. When Agent 1 finally closes ISSUE-15, the Beadbox UI reflects it within a second. The blocked badge on ISSUE-37 drops. If ISSUE-37 was the only thing blocking ISSUE-42, that badge drops too. You watch the dependency chain collapse as work completes, without refreshing or re-querying.

Under the hood, this works through a straightforward pipeline: a WebSocket server watches the .beads/ directory with fs.watch(). When any agent writes to the database (closing an issue, adding a dependency, updating status), the filesystem event triggers a broadcast to all connected clients. The React UI re-renders with fresh data. Sub-second latency from agent action to visual update.

A concrete scenario: spotting a bottleneck

Five agents are working a feature epic with 24 issues. You open Beadbox and look at the epic tree. Twelve issues are in progress. Six show blocked badges.

That's already information you didn't have. bd list would show you 12 in-progress issues, but you'd need to run bd blocked separately and cross-reference to understand which in-progress issues are actually stalled.

You scan the blocked badges and notice something: four of the six blocked issues all depend on ISSUE-19, a database schema migration assigned to Agent 4. Agent 4 is still working it, but ISSUE-19 has become a single-point bottleneck. Four agents are effectively idle, waiting on one task.

Without the visual view, you might not catch this for another hour. With it, you can intervene immediately. Maybe you reassign ISSUE-19 to a faster agent. Maybe you split it into smaller pieces that can unblock some dependents early. Maybe you realize two of those four dependencies were over-declared and can be removed with bd dep remove.

The point isn't that the information was unavailable before. It was always in the database. The point is that the visual representation surfaces patterns that flat text obscures.

Common dependency anti-patterns

Running multiple AI agents on one repo produces a few recurring dependency problems. All of them are easier to catch visually than through CLI queries.

Over-declaration. Agents tend to be conservative. When in doubt, they declare a dependency. The result is a dependency graph that's denser than it needs to be, with issues blocked on work they don't actually need. In Beadbox, you spot this when an issue shows a blocked badge but the blocking issue is in a completely unrelated part of the codebase. A quick bd dep remove cleans it up.

Circular chains. Agent A declares a dependency on Agent B's work. Agent B, working independently, declares a dependency on Agent A's work. Now both are blocked on each other and neither can proceed. The beads CLI catches obvious circular dependencies at creation time, but indirect cycles through three or more issues are harder to detect. In the epic tree, you notice these as clusters of blocked badges that never resolve, even as other work completes around them.

Single-point bottlenecks. One issue accumulates five, six, seven downstream dependents. This happens naturally when agents working in parallel all need the same foundational piece. The scenario above illustrates the pattern. In a list view, you see seven blocked issues. In a tree view, you see seven arrows pointing at the same node. The bottleneck is obvious.

Getting started

Beadbox runs on macOS, Linux, and Windows. Install it with Homebrew:

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

Point it at any repository with a .beads/ directory. If you're already running beads with your agent fleet, Beadbox picks up the existing database and starts rendering immediately. No import step, no configuration, no account creation.

Your agents keep using the CLI. They run bd dep add, bd update, bd close as usual. Beadbox watches the database and reflects every change in real time. You get the visual layer without changing any agent workflows.

Beadbox is free while in beta.

If you're coordinating multiple AI agents on a single codebase, the dependency graph is the thing that will break your workflow first. You can manage it blind through the CLI, or you can see it. Seeing it is faster.