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
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 git@github.com: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
