⚠️ SUPERSEDED — The intercom/Beads coordination system has been removed from b4arena. The b4arena/intercom repo is archived. This document is retained for historical context only.

Beads

Beads is a distributed, git-backed graph issue tracker optimized for AI agents. It provides persistent, structured memory via a dependency-aware graph backed by Dolt (version-controlled SQL) and JSONL (git portability).

How Beads Works in #B4arena

All agents share a single Dolt database via the Intercom — a shared clone of b4arena/intercom bind-mounted into every agent container:

Host (ludus host):
/home/openclaw/b4arena/intercom/     ← single git clone
└── .beads/                          ← shared Dolt database

Container (any agent):
/workspace/intercom/.beads/          ← bind mount (same database)

When one agent writes a bead, the next agent sees it immediately. No sync delay.

Core Concepts

Dependencies

Beads form a directed acyclic graph (DAG) through dependencies:

Type	Blocking?	Use Case
blocks	Yes	B cannot start until A closes
parent-child	Yes (transitive)	Epic → subtask hierarchy
related	No	Soft "see also" link
discovered-from	No	Found during other work

Only blocking dependencies affect the bd ready queue.

Labels and Routing

Labels serve double duty:

1. Routing — the watcher uses labels to route work to the right agent (bd ready --label dev)
2. State caching — <dimension>:<value> labels (e.g., patrol:active) cache operational state for fast queries

Agent Identity

Each agent has two identity mechanisms:

• BD_ACTOR — who performed the action (audit trail)
• Labels — what kind of work the agent handles (routing)

Key Constraints

• Dolt is not concurrent-safe — the watcher serializes agent execution (one agent active at a time)
• Hash-based IDs — bead IDs like ws-3o9 are hash-derived, never sequential
• No auto-sync with GitHub — Beads and GitHub Issues are separate systems

Source: Beads Protocol · bd CLI Reference · Intercom