Beads Integration — Technical Guide

Home

Overview

Beads is a distributed, git-backed graph issue tracker designed for AI agents. We use it as the coordination layer for #B4mad’s multi-agent OpenClaw deployment.

Architecture

┌──────────────────────────────────────────────────────┐
│                    GitHub (Private)                    │
│                                                        │
│  brenner-axiom/beads-hub     ← Cross-project epics    │
│  brenner-axiom/linkedin-brief ← Project-specific tasks │
│  (future project repos)       ← Each has .beads/       │
└──────────┬───────────────────────────┬────────────────┘
           │ git pull/push             │ git pull/push
           │                           │
┌──────────▼──────────┐   ┌───────────▼──────────────┐
│  Axiom (main)       │   │  LinkedIn Brief Agent     │
│  Model: Opus        │   │  Model: Sonnet            │
│  Role: Orchestrator │   │  Role: Feed summaries     │
│                     │   │                            │
│  Can create/assign  │   │  Checks beads-hub for     │
│  beads to any agent │   │  assigned tasks on start   │
└──────────┬──────────┘   └────────────────────────────┘
           │ spawn
┌──────────▼──────────┐
│  CodeMonkey          │
│  Model: Qwen3-Coder │
│  Role: Code tasks    │
│                      │
│  Claims & works on   │
│  coding beads        │
└──────────────────────┘

Components

1. beads-hub Repository

  • URL: https://github.com/brenner-axiom/beads-hub (private)
  • Purpose: Cross-cutting epics, coordination tasks, inter-agent messages
  • Location: ~/.openclaw/workspaces/beads-hub/
  • Sync: All agents pull from here at session start

2. Per-Project .beads/

  • Each project repo (linkedin-brief, workspace, etc.) can have its own .beads/
  • Project-specific tasks stay local to that repo
  • Cross-project dependencies link via bead IDs

3. Beads Skill

  • Location: skills/beads/SKILL.md
  • Provides instructions for any agent on how to use bd CLI
  • Available to all agents via skill system

4. bd CLI

  • Installed system-wide at ~/.local/bin/bd
  • Built with CGO for Dolt database support
  • Version: 0.52.0

Task Lifecycle

Created → Open → Claimed (in_progress) → Closed
                    ↓
              Blocked (waiting on dependency)

Creating Tasks (Axiom or any agent)

cd ~/.openclaw/workspaces/beads-hub
bd create "Implement OAuth for #B4mad portal" -p 1 --assign codemonkey --json
bd sync

Working Tasks (assigned agent)

cd ~/.openclaw/workspaces/beads-hub
git pull --rebase
bd ready --json                    # See what's available
bd update <id> --claim --json      # Atomic claim
# ... do work ...
bd close <id> --reason "Completed" --json
bd sync

Cross-Agent Handoff

# Axiom creates epic with sub-tasks for different agents
bd create "Deploy new service" -p 1 --json          # Returns bd-abc
bd create "Write deployment script" -p 1 --parent bd-abc --assign codemonkey --json
bd create "Update monitoring config" -p 2 --parent bd-abc --assign axiom --json
bd dep add bd-abc.2 bd-abc.1  # Monitoring depends on deployment script
bd sync

Integration Points

Heartbeat Check

Axiom can check beads-hub during heartbeats:

cd ~/.openclaw/workspaces/beads-hub && git pull -q && bd ready --json

Cron Job (optional)

A cron job can periodically check for stale tasks:

bd list --status open --json | jq '[.[] | select(.updated_at < "2026-02-10")]'

Sub-Agent Spawning

When spawning a sub-agent, include beads context:

Task: Work on bd-abc in beads-hub. Pull the repo, claim the bead, do the work, close it, sync.

Git Workflow

  1. Always pull before working: git pull --rebase
  2. Use bd sync after changes (exports JSONL, commits, pushes)
  3. Hash-based IDs prevent merge conflicts (e.g., bd-a1b2)
  4. JSONL is the portable format — committed to git for cross-platform sync
  5. Dolt DB is local — gitignored, rebuilt from JSONL on clone

Troubleshooting

“dolt database” errors

Ensure bd was built with CGO: CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest

Merge conflicts in JSONL

git checkout --theirs .beads/issues.jsonl
bd import -i .beads/issues.jsonl

Pre-commit hooks hanging

Use --no-verify for manual commits, or ensure bd is in PATH.