allbeads

AllBeads

A Boss Repository Architecture for Multi-Repo AI Agent Orchestration

AllBeads is a meta-orchestration system that federates issue tracking (beads) across multiple git repositories, enabling AI agents to coordinate work across distributed microservices with unified dependency management and enterprise integration.

What is AllBeads?

AllBeads implements the "Boss Repository" pattern - a control plane that:

• Federates beads from multiple repositories into a unified dependency graph
• Synchronizes state bi-directionally with JIRA and GitHub Issues
• Visualizes cross-repo work through a terminal-based dashboard
• Enables strategic coordination between AI agents working across distributed codebases
• Provides agent-to-agent messaging for distributed coordination
• Governs AI adoption with policy enforcement, scanning, and onboarding workflows

Think of it as a "meta-issue-tracker" that sits above your microservices, giving agents and architects a coherent view of work spanning 10, 20, or 50+ repositories.

Architecture

AllBeads consists of five core components:

1. Sheriff Daemon

Background synchronization service that:

• Polls member repositories for beads updates
• Creates "Shadow Beads" in the Boss repo for Epic-level work
• Syncs state with JIRA and GitHub Issues
• Manages the federated dependency graph
• Runs in foreground or background mode

2. Boss Board TUI

Terminal-based dashboard providing:

• Multi-view visualization (Kanban, Mail views)
• Real-time updates from the Sheriff daemon
• Interactive navigation and filtering
• Cross-repository dependency visualization

3. Agent Mail System

Distributed messaging protocol:

• Message types: LOCK, UNLOCK, NOTIFY, REQUEST, BROADCAST, HEARTBEAT
• Postmaster daemon for message routing
• Resource locking for coordination
• SQLite-backed persistence

4. Federated Graph

Data structure representing:

• Shadow Beads pointing to native beads in member repositories
• Cross-repo dependencies (bead://repo-name/bead-id URIs)
• Rig configurations (member repository metadata)
• Aggregated work state across the entire organization

5. Enterprise Integration

External system adapters:

• JIRA: REST API adapter with JQL search and status sync
• GitHub: GraphQL + REST API for issue management
• Plugin Architecture: Extensible for Linear, Asana, etc.

6. Governance Framework

AI adoption management:

• Agent Detection: Identifies 14 AI agent types (Claude, Copilot, Cursor, Aider, Kiro, etc.)
• Policy Engine: HCP Terraform-inspired enforcement (Advisory, SoftMandatory, HardMandatory)
• GitHub Scanner: Efficiently scan user/org repos for onboarding opportunities
• Usage Tracking: SQLite-based metrics for adoption trends
• Onboarding Workflow: Guided setup for new repositories
• Health Checks: Monitors repo setup status (Beads, Skills, Integration, CI/CD, Hooks)
• Agent Tooling Detection: Collects MCP servers, Cursor rules, and Copilot instructions across repos

See DEMO.md for usage examples.

Getting Started

Prerequisites

• bd (beads CLI) - Installation instructions
• Git

Installation

Homebrew (macOS/Linux)

brew tap thrashr888/tap
brew install allbeads

Pre-built Binaries

Download the latest release for your platform from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/thrashr888/AllBeads/releases/latest/download/allbeads-macos-aarch64 -o ab
chmod +x ab && sudo mv ab /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/thrashr888/AllBeads/releases/latest/download/allbeads-macos-x86_64 -o ab
chmod +x ab && sudo mv ab /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/thrashr888/AllBeads/releases/latest/download/allbeads-linux-x86_64 -o ab
chmod +x ab && sudo mv ab /usr/local/bin/

# Verify installation
ab --version

From Source

# Clone and build (requires Rust toolchain)
git clone https://github.com/thrashr888/AllBeads.git
cd AllBeads && cargo build --release

# Add to PATH or create alias
alias ab='./target/release/allbeads'

Initialize

# Initialize AllBeads (creates config directory and file)
ab init

Quick Start

# Add the current repository (auto-detects name, URL, and auth)
cd /path/to/your-repo
ab context add .

# Or add with explicit URL (SSH or HTTPS)
ab context add . --url [email protected]:org/repo.git

# View aggregated statistics
ab stats

# List all beads
ab list

# Filter by status
ab list --status open

# Show ready-to-work beads (no blockers)
ab ready

# Launch TUI (Kanban + Mail)
ab tui

# Run Sheriff daemon in foreground
ab sheriff --foreground

# Check JIRA/GitHub integration status
ab jira status
ab github status

See DEMO.md for more examples.

CLI Reference