allbeads

AllBeads - Multi-Repo Agent Orchestration

AllBeads implements the "Boss Repository" pattern - a control plane that federates issue tracking (beads) across multiple git repositories, enabling AI agents to coordinate work across distributed microservices.

AllBeads vs bd (beads)

Decision test: "Does my work span multiple repositories?" → YES = allbeads

When to use allbeads:

• Work spans multiple microservices/repos
• Need unified view across polyrepo architecture
• Cross-repository dependencies exist
• Managing work across team contexts (@work, @personal)
• Enterprise integration (JIRA, GitHub Issues)

When to use bd:

• Single repository work
• Local issue tracking
• No cross-repo dependencies needed

Prerequisites

allbeads --version  # Requires v0.2.0+

• allbeads CLI installed (brew install thrashr888/allbeads/allbeads)
• bd CLI installed for underlying beads operations
• Contexts configured: allbeads context add .

Session Start Checklist

When starting a work session, check for handoffs from other agents:

ab mail inbox        # Check for messages from other agents
ab ready             # See what work is available
bd ready             # Local repo ready tasks

Why check mail? Other agents may have completed work and handed off follow-up tasks. The mail often contains context about what was done and what's expected next.

Core Commands

Viewing Aggregated Work

# Show statistics across all contexts
allbeads stats

# List all beads across contexts
allbeads list

# Filter by status
allbeads list --status open

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

# Show blocked beads
allbeads blocked

# Search across all contexts
allbeads search "query"

Context Management

# Add current repo as context
allbeads context add .

# Add with explicit name
allbeads context add /path/to/repo --name myproject

# List contexts
allbeads context list

# Remove context
allbeads context remove myproject

Synchronization

# Sync all contexts with remotes
allbeads sync --all

# Check sync status
allbeads sync --status

# Sync specific context
allbeads sync mycontext

Interactive Dashboard

# Launch TUI (Kanban + Mail views)
allbeads tui

# Keyboard shortcuts:
#   Tab           - Switch views
#   j/k or Up/Down - Navigate
#   Enter         - View details
#   q             - Quit

Key Concepts

Contexts

A context is a git repository that AllBeads tracks. Each context has its own .beads/ directory and can be filtered independently or viewed in aggregate.

Shadow Beads

When working with cross-repo Epics, AllBeads creates "Shadow Beads" in the Boss repository that point to native beads in member repositories, enabling dependency tracking across repo boundaries.

Federated Graph

AllBeads maintains a unified dependency graph across all contexts, allowing you to see how work in one repository blocks or enables work in another.

Cross-Repo Task Handoff

AllBeads enables seamless task handoff between repositories using beads (persistent tasks) and mail (real-time notifications).

Beads + Mail: The Complete Handoff

# 1. Create the persistent task (bead)
ab create --context=AllBeadsWeb --title="Add /api/beads/import endpoint" --type=feature

# 2. Send real-time notification (mail)
ab mail send --to AllBeadsWeb "New task: Add /api/beads/import endpoint. See bd ready."

# 3. Target agent picks up
# In AllBeadsWeb:
ab mail inbox    # Sees notification
bd ready         # Finds task

When to Use Each

Best practice: Create a bead AND send mail for important handoffs.

Common Handoff Targets

Agent Mail

Agent Mail enables real-time communication between agents across repositories.

# Send a message to another context/agent
ab mail send --to AllBeadsWeb "Feature ready for review"
ab mail send --to AllBeadsWeb --message-type request "Approve deployment?"

# Check your inbox
ab mail inbox

# Check unread count
ab mail unread

# Send test messages
ab mail test "Build completed for ab-123. Ready for review."

Mail in the Dashboard

View mail in multiple ways:

• CLI: ab mail inbox
• TUI: ab tui then Tab to Mail view
• Web: https://allbeads.co/dashboard/mail (when logged in)

Message Types

Managing Your Inbox

# Mark messages as read
ab mail read <message-id>    # Mark specific message
ab mail read --all           # Mark all as read

# Archive old messages
ab mail archive <message-id> # Archive specific message
ab mail archive --all        # Archive all read messages

# Delete messages
ab mail delete <message-id>  # Permanently delete

Workflow: Check inbox → Process messages → Mark read → Archive when done.

Mail Best Practices

1. Reference bead IDs in messages for context
2. Check inbox when starting work sessions
3. Send completion notices after finishing handed-off work
4. Use mail for urgency, beads for tracking
5. Clean up regularly with ab mail read --all && ab mail archive --all

Common Workflows

Starting cross-repo work:

allbeads ready           # Find available work across all repos
allbeads show <id>       # Review issue details
bd update <id> --status=in_progress  # Claim it (in the local repo)

Checking project health:

allbeads stats           # Overview across all contexts
allbeads blocked         # Find blocked issues
allbeads sync --status   # Check sync state

Adding a new repository:

cd /path/to/new-repo
allbeads context add . --name new-project
allbeads sync new-project

Creating a brand new project:

ab context new myproject --private --gitignore Go --license MIT

This creates GitHub repo, clones locally, initializes beads, and adds to AllBeads.

Planning a project (no code yet):

ab context new myproject --private
bd create --title="[Phase 1] ..." --type=epic
bd comments add <id> "<spec details>"
# STOP - let handoff workflow implement

Golden Workflow: Onboard → Handoff → Complete

The recommended workflow for managing work across repositories:

1. Onboard Repositories

# Onboard existing repo (safety checks: clean git, main branch)
ab onboard /path/to/repo

# Creates: .beads/, .claude/settings.json, adds to AllBeads config
# Creates: Epic + task beads for onboarding work

2. Find Ready Work

ab ready                 # Show unblocked tasks across all repos
ab show <bead-id>        # Review task details

3. Hand Off to Agent

# Hand off to your preferred agent (spawns new process)
ab handoff <bead-id>

# Or specify agent explicitly
ab handoff <bead-id> --agent codex
ab handoff <bead-id> --agent gemini

# Queue to a running agent via Agent Mail (no new process)
ab handoff <bead-id> --queue
ab handoff <bead-id> --queue --agent claude

4. Agent Completes Work

The agent:

1. Creates branch (or uses pre-created for sandboxed agents)
2. Does the work
3. Closes the bead: bd close <bead-id>

5. Commit and Push (if sandboxed agent)

For sandboxed agents like Codex that can't do git operations:

git add -A
git commit -m "feat(<bead-id>): <description>"
bd sync
git push -u origin bead/<bead-id>

6. Repeat

ab ready                 # Find next task
ab handoff <bead-id>     # Hand off

Key Learnings

Onboarding

• Safety checks: Clean git workspace, main/master branch required
• Dependency direction: Epic depends on tasks (tasks ready, epic blocked)
• Plugins: Only beads + allbeads auto-enabled

Handoff

• Sandboxed agents: Codex can't write to .git/ - branch pre-created
• Codex command: Uses codex exec --full-auto for non-interactive mode
• After sandboxed agent: User commits and pushes the work
• Queue mode (--queue): Sends work via Agent Mail to a running agent instead of spawning new process

Agents

AllBeads provides specialized agents:

Commands Reference

Quick Reference

# Discovery
ab scan github <user>         # Find repos

# Onboarding
ab onboard <url>              # Onboard existing
ab context new <name>         # Create new

# Work
ab ready                      # Find work
ab update <id> --status=...   # Update status
ab close <id>                 # Complete

# Cross-Repo Handoff
ab create --context=AllBeadsWeb --title="..." --type=feature
ab mail send --to AllBeadsWeb "New task: see bd ready"

# Mail
ab mail send --to <context> "message"  # Send to context/agent
ab mail inbox                 # Check messages
ab mail unread                # Unread count

# Sync
ab sync --all                 # Sync everything
bd sync                       # Sync current repo

# Governance
ab governance check           # Check policies
ab agents list               # List agents

See Also

• AGENTS.md - Quick reference for agents
• CLAUDE.md - Full project guide
• specs/PRD-00.md - Architecture specification