Multi-repo orchestration for AI agent workflows. Aggregate beads across repositories, manage contexts, and coordinate distributed work.

version
0.2.2
GitHub stars
9

Install

/plugin install allbeads@allbeads-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add thrashr888/AllBeads.

Contents

Discovered from source

Skills 1

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)

allbeads (multi-repo)bd (single-repo)
Aggregates across reposSingle repository
Context-based filteringLocal .beads only
Cross-repo dependenciesLocal dependencies
Federated dashboardSingle project view

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

Use BeadsUse Mail
Trackable tasksReal-time alerts
Work spanning sessionsImmediate attention needed
DependenciesStatus updates
Persistent recordCoordination messages

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

Common Handoff Targets

ContextPurpose
AllBeadsWebWeb UI, API endpoints, dashboard
AllBeadsAppmacOS native app, menu bar
AllBeadsCLI, core Rust library

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:

Message Types

TypeUse For
NOTIFYStatus updates, completions, FYIs
REQUESTApproval needed, input required
BROADCASTAnnouncements to all agents
LOCK/UNLOCKFile coordination
HEARTBEATAgent liveness signals

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:

AgentPurpose
task-agentAutonomous task completion across contexts
governance-agentPolicy enforcement and compliance
planning-agentProject planning without implementation
onboarding-agentRepository onboarding assistance

Commands Reference

CommandPurpose
/createCreate bead in any context (cross-repo handoff)
/mailAgent mail for real-time coordination
/readyShow unblocked work
/listList all beads
/showShow bead details
/statsAggregated statistics
/syncSync with remotes
/contextManage contexts
/context-newCreate new GitHub repo
/project-newPlan new project (no code)
/handoffHand off to implementation
/workflowWorkflow guide
/primePrime agent context
/scanScan GitHub for repos
/governanceCheck policies
/agentsManage AI agents
/onboard-repoOnboard repository
/blockedShow blocked work
/tuiLaunch dashboard

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

Commands 19

Detect AI agents and track adoption metrics.

Subcommands:

  • allbeads agents detect - Detect AI agents in current directory
  • allbeads agents track --context <name> --path <path> - Record scan to metrics
  • allbeads agents stats - View adoption statistics
  • allbeads agents stats --days <n> - Stats for specific time period
  • allbeads agents stats --json - Output as JSON

Detects 14 AI agent types via config files:

  • Claude Code (CLAUDE.md, .claude/)
  • GitHub Copilot (.github/copilot-instructions.md)
  • Cursor (.cursorrules, .cursor/)
  • Aider (.aider.conf.yml)
  • Kiro (.kiro/)
  • And more...

Detection confidence levels:

  • High: Primary config file found
  • Medium: Secondary indicators
  • Low: Indirect evidence

Usage tracking stores metrics in SQLite for trend analysis:

  • Adoption rate over time
  • Agent distribution across repos
  • Scan history per repository

Show beads that are blocked by dependencies across all AllBeads contexts.

Run allbeads blocked to find issues that cannot proceed due to blockers.

For each blocked issue, show:

  • Bead ID and title
  • What it's blocked by
  • Context (repository)

This helps identify:

  • Cross-repo blocking relationships
  • Bottlenecks in the workflow
  • Issues that need attention to unblock downstream work

Create a brand new GitHub repository and set it up with AllBeads from the start.

This command provides a streamlined workflow similar to GitHub's "New Repository" form but adds:

  • Automatic beads initialization
  • AI agent configuration (CLAUDE.md, .cursorrules, etc.)
  • Automatic addition to AllBeads contexts

Usage:

# Interactive mode (recommended for first-time use)
ab context new

# With arguments
ab context new myproject --private --description "My new project"

# Non-interactive mode
ab context new myproject --non-interactive --private

# Full specification
ab context new myproject \
  --private \
  --description "Project description" \
  --license MIT \
  --gitignore Rust \
  --init-agents claude,cursor

Options:

OptionDescription
--descriptionRepository description
--privateCreate as private repository
--org <ORG>Create in an organization
--gitignore <TEMPLATE>.gitignore template (Rust, Node, Python, Go, etc.)
--license <LICENSE>License (MIT, Apache-2.0, GPL-3.0, etc.)
--init-agents <LIST>Comma-separated agents to configure (default: claude)
--path <PATH>Custom local clone path
--no-cloneCreate on GitHub only, don't clone locally
--wizardUse interactive TUI wizard
--non-interactiveUse defaults without prompts

Workflow:

  1. Input Collection - Name, visibility, description via prompts or CLI args
  2. GitHub Creation - Creates repository using gh CLI
  3. Clone - Clones repository to local workspace
  4. Beads Init - Runs bd init to set up issue tracking
  5. Agent Config - Creates CLAUDE.md and other agent files
  6. Git Push - Commits and pushes configuration
  7. Context Add - Adds to AllBeads config

Requirements:

  • GitHub CLI (gh) must be installed and authenticated
  • Run gh auth login if not already authenticated
  • Token needs repo scope for repository creation

Example Session:

$ ab context new

Create a new repository

  Repository name: my-awesome-project
  Description (optional): A new project with AllBeads
  Private repository? [Y/n]: n
  Organization (leave empty for personal account):

Common .gitignore templates: Rust, Node, Python, Go, Java
  .gitignore template: Rust

Common licenses: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause
  License: MIT

AllBeads Configuration
  Initialize beads? [Y/n]: y

Available agents: claude, cursor, copilot, aider
  Agents to configure (comma-separated) [claude]: claude,cursor

Summary
  Name:        my-awesome-project
  Visibility:  Public
  .gitignore:  Rust
  License:     MIT
  Beads:       Yes
  Agents:      claude, cursor

  Create repository? [Y/n]: y

Creating repository on GitHub...
✓ Created https://github.com/thrashr888/my-awesome-project
→ Cloning to /Users/me/Workspace/my-awesome-project...
✓ Cloned to /Users/me/Workspace/my-awesome-project
→ Initializing beads...
✓ Beads initialized
→ Configuring agents...
✓ Configured: claude, cursor
→ Committing configuration...
✓ Pushed to GitHub

✓ Added context 'my-awesome-project' to AllBeads config

Repository Created Successfully
  Name:   my-awesome-project
  URL:    https://github.com/thrashr888/my-awesome-project
  Path:   /Users/me/Workspace/my-awesome-project
  Beads:  initialized
  Agents: claude, cursor

Compared to ab onboard:

Featureab context newab onboard
Creates GitHub repo✓✗
Clones existing repo✓ (after creating)✓
Initializes beads✓✓
Configures agents✓✓
Adds to contexts✓✓

Use ab context new for brand new projects. Use ab onboard for existing repositories.

See also:

  • /onboard - Onboard an existing repository
  • /context - Manage AllBeads contexts
  • /agents - Detect and configure AI agents

Manage the repositories (contexts) that AllBeads tracks.

Subcommands:

  • allbeads context list - Show all configured contexts
  • allbeads context add <path> - Add a repository as a context
  • allbeads context add <path> --name <name> - Add with explicit name
  • allbeads context remove <name> - Remove a context
  • allbeads context new <name> - Create a new GitHub repository with AllBeads pre-configured
  • allbeads context onboarding - Show onboarding status for all contexts

When adding a context, AllBeads will:

  1. Detect the repository name from the folder
  2. Find the git remote URL
  3. Determine the authentication strategy (SSH or PAT)

After adding, run allbeads sync <name> to fetch beads from the remote.

Creating New Repositories

Use allbeads context new to create a brand new GitHub repository:

# Interactive mode
ab context new

# With arguments
ab context new myproject --private --description "My project"

This creates the GitHub repo, clones it locally, initializes beads, configures AI agents, and adds it to AllBeads contexts.

See /context-new for detailed usage.

Create a new bead (issue/task) in any AllBeads context. This enables cross-repository task handoff - creating work items in other repos for other agents to pick up.

Usage

# Create in a specific context
ab create --context=<context-name> --title="<title>" --type=<type> --priority=<priority>

# Examples
ab create --context=AllBeadsWeb --title="Add new API endpoint" --type=feature --priority=2
ab create --context=AllBeadsApp --title="Fix menu bar icon" --type=bug --priority=1
ab create --context=QDOS --title="Implement parser" --type=task

Parameters

ParameterRequiredDescription
--contextYesTarget context name (e.g., AllBeadsWeb, AllBeadsApp)
--titleYesTitle of the bead
--typeNoType: bug, feature, task, epic, chore (default: task)
--priorityNoPriority: P0-P4 or 0-4 (default: P2)

Cross-Repo Task Handoff

This is the primary mechanism for distributing work across the AllBeads ecosystem:

  1. Identify work for another repo: While working, discover something that belongs elsewhere
  2. Create the bead: ab create --context=AllBeadsWeb --title="..." --type=feature
  3. Agent in target repo picks it up: They run bd ready and see the task
  4. Work flows naturally: Each repo's agent handles its own work

Common Handoff Targets

ContextWhat goes there
AllBeadsWebWeb UI features, API endpoints, dashboard work
AllBeadsAppmacOS app features, native UI, menu bar items
AllBeadsCLI features, core library, Rust code

Workflow Example

# Working in AllBeads CLI, realize we need a web endpoint
ab create --context=AllBeadsWeb \
  --title="Add /api/beads/import endpoint" \
  --type=feature \
  --priority=2

# The bead appears in AllBeadsWeb
ab list -C AllBeadsWeb

# Agent in AllBeadsWeb picks it up
cd ../AllBeadsWeb
bd ready
bd update abw-xxx --status=in_progress
# ... implement ...
bd close abw-xxx

See Also

  • /allbeads:ready - Find work across all contexts
  • /allbeads:list - List beads with context filtering
  • /allbeads:handoff - Hand off bead to an agent

Manage governance policies for AI agent adoption across repositories.

Subcommands:

  • allbeads governance check - Run policy checks against current repository
  • allbeads governance status - View loaded policies and exemptions
  • allbeads governance violations - List all policy violations
  • allbeads governance exempt <repo> <policy> --reason "..." - Exempt a repo
  • allbeads governance unexempt <repo> <policy> - Remove exemption

Policy enforcement levels (HCP Terraform-inspired):

  • Advisory: Warn but don't block
  • SoftMandatory: Block unless exempted
  • HardMandatory: Always block, no exemptions

Built-in policy checks:

  • FileExists - Required files (README, LICENSE, etc.)
  • FileExistsAny - At least one of several files
  • OnboardingScore - Minimum onboarding completeness
  • AgentAllowlist - Permitted/denied agent types
  • PatternAbsent - Ensure patterns don't exist in files

Configure policies in .beads/policies.yaml or ~/.config/allbeads/policies.yaml.

Fire-and-forget delegation to AI agents. Launches the agent with full bead context (title, description, dependencies) and moves on.

Usage

# Hand off a specific bead to Claude (default agent)
ab handoff <bead-id>

# Hand off to a specific agent
ab handoff <bead-id> --agent <agent>

# Hand off in an isolated worktree
ab handoff <bead-id> --worktree

# Queue work for a running agent via Agent Mail (instead of spawning new)
ab handoff <bead-id> --queue
ab handoff <bead-id> --queue --agent claude

# Show beads that have been handed off
ab handoff --list

# Show ready beads that could be handed off
ab handoff --ready

# Dry run - see what would happen without launching
ab handoff <bead-id> --dry-run

# Show available agents (detected on system)
ab handoff --agents

Agent Preferences

On first use, you'll be prompted to select your preferred agent from the detected installed agents. Your choice is saved to .beads/config.yaml and used for subsequent handoffs.

To override the saved preference, use --agent:

ab handoff ab-xyz --agent gemini    # Use Gemini instead of preferred

Supported Agents

Terminal Agents (CLI)

  • claude - Claude Code (default)
  • opencode - OpenCode
  • codex - OpenAI Codex
  • gemini - Gemini CLI
  • aider - Aider
  • cody - Sourcegraph Cody

IDE Agents

  • cursor - Cursor
  • kiro - Kiro (AWS)
  • antigravity - Antigravity
  • copilot - VS Code Copilot

Web Agents

  • jules - Jules (Google) - opens browser
  • chatgpt-codex - ChatGPT Codex - opens browser

What Happens

  1. Bead context is loaded (title, description, dependencies, labels)
  2. A prompt is generated from the bead content with workflow instructions
  3. Bead status is updated to in_progress
  4. Handoff is recorded (comment + handed-off label)
  5. If --worktree is used, a git worktree is created in .worktrees/
  6. Agent is launched with the prompt
    • CLI agents: launched with prompt argument (use codex exec --full-auto for non-interactive)
    • IDE agents: launched with chat command
    • Web agents: browser opened with deep-link URL

Agent Workflow (What the Agent Does)

The handoff prompt instructs the agent to:

  1. Create a branch for the work: git checkout -b bead/<id>
  2. Do the work described in the bead
  3. Commit changes: git add -A && git commit -m "feat(<id>): <description>"
  4. Close the bead: bd close <id> (use --force if blocked by an epic)
  5. Sync and push: bd sync && git push -u origin bead/<id>

This ensures clean git history and proper bead tracking.

Sandboxed Agents (Codex)

Some agents run in sandboxes that prevent git operations (e.g., OpenAI Codex with workspace-write sandbox). AllBeads handles this automatically:

  1. Pre-creates the branch before launching (git checkout -b bead/<id>)
  2. Provides simplified workflow prompt (skip git operations)
  3. User handles commit/push after agent completes

The sandboxed prompt tells the agent:

  • Focus on the work, not git operations
  • The branch already exists
  • Just close the bead when done

After a sandboxed agent completes:

# Commit the agent's work
git add -A
git commit -m "feat(<bead-id>): <description>"

# Sync and push
bd sync
git push -u origin bead/<bead-id>

Queue Mode (--queue)

Use --queue to send work to a running agent via Agent Mail instead of spawning a new process:

ab handoff ab-xyz --queue
ab handoff ab-xyz --queue --agent claude

This is ideal when:

  • An agent is already running (e.g., in another terminal)
  • You want to batch multiple tasks to the same agent
  • The agent supports runtime task intake via mail

What happens:

  1. Bead context is loaded
  2. A NOTIFY message is sent via Agent Mail to {agent}@{context}
  3. Bead status is updated to in_progress
  4. queued label is added to the bead
  5. A comment records the queue action

The running agent checks its mail (either manually via ab mail inbox or automatically if running with --mail-poll) and picks up the task.

Difference from normal handoff:

NormalQueue Mode
Spawns new agent processSends mail to existing agent
Agent starts immediatelyAgent picks up when ready
One agent per beadBatched to running agent

Worktrees

Use --worktree for isolated development:

ab handoff ab-xyz --worktree

This creates a git worktree at .worktrees/ab-xyz/ with a branch ab/ab-xyz. The agent runs in the worktree, keeping your main branch clean. Useful for:

  • Parallel work on multiple beads
  • Risky changes that might need to be discarded
  • Keeping main stable while experimenting

Environment

The AB_ACTIVE_BEAD environment variable is set to the bead ID when launching CLI agents, allowing the agent to know which bead it's working on.

Workflow

Starting Work

ab handoff --ready              # See what's available
ab handoff ab-xyz               # Hand off to Claude
ab handoff ab-xyz --agent gemini  # Hand off to Gemini

Tracking Handed-off Work

ab handoff --list               # See what's in progress
ab show ab-xyz                  # View bead details + handoff info
bd show ab-xyz                  # View raw bead details and comments

Handoff info (agent, time, task URL) is automatically shown when viewing a handed-off bead with ab show.

Completing Work

After the agent finishes:

bd close ab-xyz --reason="Implemented feature X"
bd sync
git push

Philosophy

"Hand-off, not ownership" - We fire and forget. The agent takes over and works asynchronously. We don't poll for status. The work will get done.

See Also

  • ab ready - Show unblocked work
  • ab list --status=in_progress - All in-progress work
  • /release - Ship a new version
  • specs/SPEC-handoff.md - Full specification

List beads aggregated from all configured AllBeads contexts.

Run allbeads list to show all beads. Supports filtering:

  • allbeads list --status open - Filter by status
  • allbeads list --priority P1 - Filter by priority
  • allbeads list --context myproject - Filter by context

Present results grouped by context when showing multiple repositories.

Agent Mail provides real-time messaging between agents. Use it alongside beads for coordinating work handoffs.

When to Use Mail vs Beads

Use MailUse Beads
Real-time notificationsPersistent tasks
Request immediate inputWork that spans sessions
Announce status changesTrackable deliverables
Coordinate handoffsDependencies between work

Best practice: Create a bead for the work AND send mail to notify the receiving agent.

Commands

# Send a message to a context or actor
ab mail send --to AllBeadsWeb "New feature ready for review"
ab mail send --to agent@AllBeadsWeb "Task completed"

# Send different message types
ab mail send --to AllBeadsWeb --message-type notify "Build completed"
ab mail send --to AllBeadsWeb --message-type request "Please approve deployment"
ab mail send --to AllBeadsWeb --message-type broadcast "System maintenance at 5pm"

# Specify sender
ab mail send --to AllBeadsWeb --from "build-bot" "CI passed"

# Check inbox
ab mail inbox

# Check unread count
ab mail unread

# Send test messages (for verification)
ab mail test "Your message here"

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

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

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

Agent Handoff Workflow

When handing off work to another agent or repo:

1. Create the Bead (Persistent Task)

ab create --context=AllBeadsWeb --title="Implement /api/beads/import" --type=feature --priority=2

2. Send Mail Notification (Real-time Alert)

ab mail test "New task created: Implement /api/beads/import endpoint for CLI sync. See abw-079."

3. Receiving Agent Picks Up

The agent in the target repo:

ab mail inbox          # Sees the notification
bd ready               # Finds the task
bd update abw-079 --status=in_progress

Viewing Mail

When logged in (ab login), mail syncs to the web dashboard:

Message Types

TypePurposeExample
NOTIFYInform about events"Build completed successfully"
REQUESTAsk for input/approval"Approve deployment to production?"
BROADCASTAnnounce to all agents"API rate limit reached, pausing"
LOCK/UNLOCKFile coordination"Locking src/auth.rs for refactor"
HEARTBEATAgent status"Status: working on ab-123"

Managing Your Inbox

Keep your inbox clean with this workflow:

# 1. Check inbox at session start
ab mail inbox

# 2. Process messages, then mark as read
ab mail read --all

# 3. Archive when done
ab mail archive --all

Best Practices

  1. Always create a bead for trackable work - mail is ephemeral
  2. Reference bead IDs in mail messages for context
  3. Use mail for urgency - immediate attention needed
  4. Check inbox regularly when starting work sessions
  5. Send completion notifications when finishing handed-off work
  6. Clean up regularly - archive processed messages to reduce noise

Integration with TUI

The TUI dashboard shows both Kanban (beads) and Mail views:

ab tui
# Tab - switch between Kanban and Mail
# j/k - navigate messages
# Enter - view details
# q - quit

See Also

  • /allbeads:create - Create beads for cross-repo handoff
  • /allbeads:handoff - Full handoff workflow
  • /allbeads:tui - Dashboard with mail view

Onboard the current repository (or a specified repository) into the AllBeads ecosystem.

This command runs an interactive workflow that:

  1. Initializes beads tracking (bd init)
  2. Creates a CLAUDE.md file with project guidance
  3. Adds the repository to AllBeads contexts
  4. Optionally runs janitor to discover existing issues
  5. Sets up CI/CD recommendations

Usage:

# Onboard current directory
allbeads onboard-repo

# Onboard specific directory
allbeads onboard-repo /path/to/repo

# Non-interactive mode (use defaults)
allbeads onboard-repo --yes

# Skip specific steps
allbeads onboard-repo --skip-init      # Skip bd init
allbeads onboard-repo --skip-claude    # Skip CLAUDE.md creation
allbeads onboard-repo --skip-context   # Skip adding to contexts

What gets set up:

1. Beads Tracking (.beads/ directory)

  • Runs bd init to create the .beads/ directory
  • Initializes issues.jsonl for issue tracking
  • Sets up local SQLite database

2. CLAUDE.md

  • Creates a template CLAUDE.md file
  • Includes project overview section
  • Pre-fills common development commands
  • Documents the project structure
  • Provides guidance for AI agents

3. AllBeads Context

  • Adds the repository to ~/.config/allbeads/config.yaml
  • Detects git remote URL automatically
  • Auto-configures authentication strategy (SSH vs HTTPS)
  • Makes the repo visible in ab context list

4. Optional: Janitor Analysis

  • Scans codebase for potential issues
  • Creates beads for TODO comments
  • Identifies security concerns
  • Detects code smells and technical debt

After onboarding:

The repository will be ready for:

  • Issue tracking with bd create/list/update/close
  • Multi-context aggregation via ab list/stats
  • TUI visualization with ab tui
  • Agent coordination with AllBeads Mail
  • Cross-repository dependency tracking

Check onboarding status:

ab context onboarding

Example session:

$ cd ~/projects/my-app
$ allbeads onboard-repo

🚀 AllBeads Repository Onboarding

Repository: my-app
Path: /Users/me/projects/my-app
Remote: git@github.com:me/my-app.git

📦 Step 1: Initialize Beads Tracking
  Initialize beads tracking in this repository? [Y/n]: y
  Running: bd init
  ✓ Beads initialized successfully

📝 Step 2: Setup CLAUDE.md
  Create a starter CLAUDE.md file? [Y/n]: y
  ✓ Created CLAUDE.md
  ℹ  Edit CLAUDE.md to add project-specific guidance

🔗 Step 3: Add to AllBeads Contexts
  Add this repository to AllBeads contexts? [Y/n]: y
  ✓ Added to AllBeads contexts as 'my-app'

📚 Next Steps:

1. Create your first issue:
   cd /Users/me/projects/my-app
   bd create --title="Initial setup" --type=task --priority=2

2. View your issues in the TUI:
   ab tui

3. Check onboarding status:
   ab context onboarding

✅ Onboarding complete!

Safety Checks

Before onboarding existing repositories, AllBeads verifies:

  1. Clean working directory - No uncommitted changes (excludes .beads/ and .claude/)
  2. Main branch - Must be on main or master branch

If either check fails, onboarding is refused with a clear error message:

Error: Repository has uncommitted changes:
  M src/main.rs
  ?? new-file.txt

Please commit or stash changes before onboarding.
Error: Repository is on branch 'feature-x', not main/master.

Please switch to the main branch before onboarding:
  git checkout main

Dependency Direction

When onboarding creates beads (epic + tasks):

  • Epic depends on tasks: bd dep add <epic> <task>
  • Tasks appear as "ready" for agents to pick up
  • Epic appears as "blocked" until all tasks are done

Anti-pattern: Don't make tasks depend on epic (this blocks the tasks!)

Plugin Configuration

Onboarding auto-enables only core plugins:

  • beads@beads-marketplace
  • allbeads@allbeads-marketplace

An informational bead is created suggesting other available marketplace plugins for the user to review and enable manually.

See also:

  • /context - Manage AllBeads contexts
  • /stats - View aggregated statistics
  • /tui - Launch the AllBeads dashboard
  • /handoff - Hand off onboarding tasks to agents

Load project context into agent memory for effective work.

Usage

ab prime                    # Prime with all contexts
ab prime -C <context>       # Prime specific context

What Gets Loaded

  1. Project Overview

    • Active contexts and paths
    • Repository status (beads, agents)
  2. Ready Work

    • Unblocked beads ready to implement
    • Priority-sorted task list
  3. Recent Activity

    • Recently modified beads
    • Recent commits
  4. Statistics

    • Open/closed/blocked counts
    • Work distribution

When to Use

  • Start of new session
  • After conversation compaction
  • Switching between contexts
  • Before starting complex work

Output

# AllBeads Context Priming

## Active Contexts
- AllBeads: /Users/me/Workspace/AllBeads (174 beads)
- rookery: /Users/me/Workspace/rookery (23 beads)

## Ready Work (5 tasks)
1. ab-xyz [P1] - Implement feature X
2. rk-123 [P2] - Fix bug in auth

## Recent Activity
- 3 beads closed today
- 2 beads created today

## Statistics
- Open: 45, In Progress: 3, Blocked: 2, Closed: 124

See Also

  • /ready - Just show ready work
  • /stats - Just show statistics
  • /list - Full bead listing

Create a new GitHub repository with AllBeads and plan the work using beads issues. Does not write code - just sets up the project structure and creates the implementation plan.

Workflow

  1. Gather Requirements - Discuss the project idea with the user
  2. Create Spec - Write a detailed specification document
  3. Create Repo - Use ab context new to create GitHub repo
  4. Create README - Add README.md with project overview and status
  5. Create Beads - Create epic issues with specs embedded in descriptions
  6. STOP - Do not write implementation code

The implementation will be handled later by:

  • User manually starting work
  • /handoff workflow (ab-vlq) triggering agent work
  • Another session picking up from bd ready

Why This Workflow?

  • Separation of Concerns - Planning and implementation are distinct phases
  • Better Handoffs - Beads contain all context needed for implementation
  • Interruptible - Work can be picked up across sessions
  • Agent-Friendly - Any agent can implement from the beads

Usage

When the user describes a new project idea:

  1. Ask clarifying questions about requirements
  2. Write a spec document (can be in AllBeads/specs/ or in the new repo)
  3. Create the repo:
    ab context new <project-name> --private --gitignore <lang> --license <license>
    
  4. Create README.md with:
    • Project overview
    • Status: "Planning Phase"
    • Planned features table
    • Example usage (planned)
  5. Create beads epics for each phase:
    bd create --title="[Phase 1] ..." --type=epic --priority=1
    
  6. Add detailed descriptions to beads (specs, requirements, acceptance criteria)

What NOT to Do

  • Do NOT create source code files
  • Do NOT set up build/test infrastructure
  • Do NOT create CI/CD pipelines
  • Do NOT implement any features

All implementation should wait for the handoff workflow or explicit user request.

Example Session

User: I want to build a CLI tool that converts markdown to PDF

Agent: Great idea! Let me ask some questions:
- What language? (Go, Rust, Python?)
- Should it support themes/styles?
- Any specific PDF features (TOC, headers/footers)?

User: Go, yes to themes, and TOC would be nice

Agent: Perfect. Let me plan this project...

1. Creating spec document...
2. Creating repo with `ab context new md2pdf --private --gitignore Go --license MIT`
3. Adding README.md with project overview
4. Creating beads:
   - [Phase 1] Core CLI structure
   - [Phase 2] Markdown parsing
   - [Phase 3] PDF generation
   - [Phase 4] Theme support
   - [Phase 5] TOC generation

Project planned! The beads contain full specs. Implementation can begin via:
- `bd ready` to see available work
- `/handoff` to trigger agent implementation
- Or start manually: `bd update md2pdf-xxx --status=in_progress`

See Also

  • /context-new - Just create a repo (no planning)
  • /handoff - Trigger agent to work on planned beads
  • bd ready - See what's ready to implement

Find beads that are ready to work on (no blocking dependencies) across all AllBeads contexts.

Run allbeads ready to get a list of unblocked issues from all repositories. Present them showing:

  • Bead ID
  • Title
  • Priority
  • Context (repository)

If there are ready tasks, ask the user which one they'd like to work on.

If there are no ready tasks, suggest:

  • Check /allbeads:blocked to see what's blocking work
  • Check individual repos with bd ready

Scan GitHub user or organization repositories to identify onboarding opportunities.

Subcommands:

  • allbeads scan user <username> - Scan a user's repositories
  • allbeads scan org <org-name> - Scan an organization's repositories
  • allbeads scan compare - Compare scanned repos with managed contexts

Options:

  • --language <lang> - Filter by programming language
  • --min-stars <n> - Minimum star count
  • --include-archived - Include archived repositories
  • --include-forks - Include forked repositories

The scanner detects 14 AI agent types:

  • Claude Code, GitHub Copilot, Cursor, Aider, Kiro
  • OpenAI Codex, Google Gemini, Amazon CodeWhisperer
  • Tabnine, Codeium, Sourcegraph Cody, Replit AI
  • JetBrains AI, Windsurf

Each repo is assigned an onboarding priority (High, Medium, Low, Skip) based on:

  • Number of stars and recent activity
  • Existing agent configurations
  • Language and project type

Requires GITHUB_TOKEN environment variable for API access.

Show detailed information about a specific bead.

Run allbeads show <bead-id> to display:

  • Full title and description
  • Status and priority
  • Context (repository)
  • Dependencies (blocks/blocked-by)
  • Creation and update timestamps
  • Comments (if any)

This provides complete context for understanding a piece of work, including cross-repo relationships.

Display statistics aggregated across all AllBeads contexts.

Run allbeads stats to retrieve project metrics and present them clearly:

  • Total beads by status (open, in_progress, blocked, closed)
  • Breakdown by context (repository)
  • Ready-to-work count
  • Cache status

Suggest actions based on the stats:

  • High number of blocked issues? Run /allbeads:blocked to investigate
  • No in_progress work? Run /allbeads:ready to find tasks
  • Stale cache? Run allbeads sync --all to refresh

Synchronize AllBeads contexts with their git remotes.

Commands:

  • allbeads sync - Sync the AllBeads config (if in git)
  • allbeads sync --all - Sync all context beads
  • allbeads sync <context> - Sync a specific context
  • allbeads sync --status - Check sync status without syncing

This fetches the latest beads from each repository's remote and updates the local cache.

Run this:

  • At the start of a session to get latest state
  • After making changes in multiple repos
  • Before generating cross-repo reports

Launch the AllBeads terminal user interface for interactive navigation.

Run allbeads tui to open the dashboard with:

  • Kanban view: Visual board with Open, In Progress, and Closed columns
  • Mail view: Agent messages and notifications

Keyboard shortcuts:

  • Tab - Switch between Kanban and Mail views
  • j/k or Up/Down - Move up/down
  • h/l or Left/Right - Switch columns (Kanban)
  • Enter - View details
  • Esc - Back
  • q - Quit

This provides a visual overview of work across all contexts.

AllBeads Workflow Guide

The Big Picture

[GitHub Repos] → [ab scan] → [ab onboard] → [AllBeads Contexts]
                                                    ↓
[ab context new] → [New Repo] → [bd init] → [Managed Context]
                                                    ↓
[Planning] → [bd create epics] → [Add specs] → [Ready for work]
                                                    ↓
[ab ready] → [Claim task] → [Implement] → [ab close] → [Push]

Workflow Phases

1. Discovery

Find repos to manage:

ab scan github <username>      # Your repos
ab scan github <org>           # Org repos
ab context list               # Already managed

2. Onboarding

Bring repos into AllBeads:

# Existing repo
ab onboard <repo-url>

# New repo
ab context new <name> --private

3. Planning

Create work items with specs:

bd create --title="..." --type=epic
bd comments add <id> "<spec>"

4. Execution

Complete the work:

ab ready                      # Find work
ab update <id> --status=in_progress
# ... implement ...
ab close <id>
git push

5. Governance

Maintain quality:

ab governance check           # Policy compliance
ab agents list               # Agent coverage
ab stats                     # Health metrics

Key Commands by Phase

PhaseCommandPurpose
Discoveryab scan githubFind repos
Onboardingab onboardAdd to AllBeads
Planningab context newCreate new repo
Planningbd createCreate work items
Executionab readyFind work
Executionab closeComplete work
Governanceab governance checkVerify policies

Session Protocol

Every session should:

  1. ab prime - Load context
  2. ab ready - Find work
  3. Work on tasks
  4. bd sync - Save beads
  5. git push - Push changes

See Also

  • AGENTS.md - Quick agent reference
  • CLAUDE.md - Full project guide
  • /prime - Context priming
  • /ready - Ready work

Agents 4

Governance Agent

Scans and enforces governance policies across AllBeads-managed repositories.

Workflow

  1. Scan Repositories

    ab governance check            # Check all managed repos
    ab governance check --repo=X   # Check specific repo
    
  2. Review Violations

    • Policy violations are reported with severity levels
    • Advisory: Recommendations, no blocking
    • Soft Mandatory: Should fix, can override with reason
    • Hard Mandatory: Must fix, blocks operations
  3. Create Remediation Issues For each violation:

    bd create --title="Policy: <violation>" --type=task --priority=2
    bd comments add <id> "Violation details and remediation steps"
    
  4. Track Agent Coverage

    ab agents list                 # List agents across contexts
    ab agents summary              # Adoption statistics
    ab scan github <user>          # Find unmanaged repos
    
  5. Onboard Unmanaged Repos For repos without AllBeads:

    ab onboard <repo-url>          # Full onboarding
    # Or just scan:
    ab scan github <user> --all
    

Governance Policies

Agent Configuration

  • All managed repos should have AI agent configs
  • CLAUDE.md required for Claude Code
  • .cursorrules for Cursor
  • Check with ab agents detect

Beads Tracking

  • All repos should have .beads/ initialized
  • Regular sync with remote
  • No stale in_progress issues

Security

  • No secrets in committed files
  • .env files in .gitignore
  • License file present

Reporting

Generate governance reports:

ab governance status           # Summary across all repos
ab governance violations       # List all violations
ab governance audit            # Audit log

Exemptions

Some repos may be exempt:

ab governance exempt <repo> <policy> --reason="..."
ab governance unexempt <repo> <policy>

Important Guidelines

  • Run governance checks regularly
  • Create issues for violations, don't just report them
  • Track remediation progress through beads
  • Respect exemptions with valid reasons
  • Focus on high-value policies first

Onboarding Agent

Helps onboard new and existing repositories into the AllBeads ecosystem.

Workflow

For Existing Repositories

  1. Identify Target

    # Scan user's GitHub for unmanaged repos
    ab scan github <username> --all
    
    # Or specify a repo directly
    ab scan repo github.com/user/repo
    
  2. Assess Onboarding Priority Consider:

    • Recent activity (last push date)
    • Stars / usage
    • Language match with other managed repos
    • Existing agent configurations
  3. Run Onboarding

    ab onboard <repo-url>
    # Or for local:
    ab onboard /path/to/repo
    
  4. Verify Configuration

    ab agents detect /path/to/repo
    ab context list | grep <repo>
    

For New Repositories

  1. Create with Full Setup

    ab context new <name> \
      --private \
      --gitignore <lang> \
      --license MIT \
      --init-agents claude,cursor
    
  2. Verify Creation

    • Check GitHub for repo
    • Verify local clone
    • Confirm beads initialized
    • Check agent configs created

Batch Onboarding

For multiple repos:

# Scan first
ab scan github <user> --all

# Then use TUI picker
ab tui  # Tab to GitHub picker, select repos

Onboarding Checklist

For each repo:

  • Beads initialized (.beads/ exists)
  • CLAUDE.md created with project guidance
  • Added to AllBeads contexts
  • Git hooks installed (optional)
  • Initial sync completed
  • README updated if needed

Incremental Onboarding

Repos can be partially onboarded. Check status:

ab context onboarding

To complete partial onboarding:

ab onboard <path> --skip-clone  # Already cloned

Troubleshooting

Clone Failures

# Check SSH keys
ssh -T git@github.com

# Try HTTPS instead
ab onboard https://github.com/user/repo

Beads Init Failures

# Run manually
cd /path/to/repo
bd init

Context Add Failures

# Add manually
ab context add /path/to/repo --name <name>

Important Guidelines

  • Start with high-priority repos (active, important)
  • Verify each step before proceeding
  • Create beads for any issues discovered
  • Don't force onboarding on archived repos
  • Respect private repo visibility

Safety Checks

AllBeads enforces safety checks before onboarding existing repositories:

  1. Clean Working Directory: Refuses to onboard if there are uncommitted changes (excluding .beads/ and .claude/ directories)
  2. Main Branch: Refuses to onboard if not on main or master branch

These prevent accidental commits of unrelated work during onboarding.

# If you see safety check errors:
git stash                    # Stash uncommitted changes
git checkout main            # Switch to main branch
ab onboard .                 # Now onboard
git stash pop                # Restore changes after

Batch Onboarding Best Practices

When onboarding multiple repos:

  1. Filter for git repos with GitHub remotes - Skip non-git folders and repos without remotes
  2. Run onboarding in parallel where possible
  3. Create issues for repos that fail safety checks - Don't skip silently
  4. The epic depends on tasks - Use bd dep add <epic> <task> so tasks are ready, epic is blocked

Dependency Direction

When onboarding creates an epic with tasks:

  • Correct: Epic depends on tasks (bd dep add epic-id task-id)
  • Incorrect: Tasks depend on epic (this blocks the tasks!)

The tasks should appear as "ready" for agents to pick up.

Planning Agent

Plans new projects by creating repositories and beads, but does NOT write implementation code.

Workflow

  1. Gather Requirements

    • Discuss the project idea with the user
    • Ask clarifying questions about:
      • Language/framework preferences
      • Key features needed
      • Scope and priorities
  2. Create Specification

    • Write a detailed spec document
    • Include:
      • Project overview
      • Use cases
      • Technical approach
      • Data sources/APIs
      • Implementation phases
    • Save to specs/<project>-spec.md in AllBeads
  3. Create Repository

    ab context new <project-name> \
      --private \
      --description "..." \
      --gitignore <lang> \
      --license <license>
    
  4. Create README Write README.md with:

    • Project overview
    • Status: "Planning Phase"
    • Planned features table
    • Example usage (planned)
  5. Create Phase Epics

    bd create --title="[Phase 1] ..." --type=epic --priority=1
    bd create --title="[Phase 2] ..." --type=epic --priority=2
    # etc.
    
  6. Add Specs to Beads For each epic:

    bd comments add <id> "<detailed spec>"
    

    Include:

    • Goals
    • Deliverables
    • API endpoints / interfaces
    • Acceptance criteria
  7. STOP

    • Do NOT create source code files
    • Do NOT set up build infrastructure
    • Do NOT implement any features

What Gets Created

<project>/
├── README.md           # Project overview, planning status
├── CLAUDE.md           # Agent guidance (from ab context new)
├── .beads/             # Issue tracking (from bd init)
├── specs/              # Copy of spec document
└── (no source code!)

Handoff

After planning, implementation can begin via:

  • User manually starting: bd update <id> --status=in_progress
  • Handoff workflow: /handoff command
  • Another agent: Task Agent picks up from bd ready

Important Guidelines

  • NEVER write source code in this phase
  • Focus on clear, detailed specifications
  • Break work into logical phases
  • Each bead should be independently implementable
  • Include acceptance criteria so completion is clear
  • Copy spec to both AllBeads and the new repo

Example Session

User: I want a CLI that converts markdown to PDF

Agent: Let me plan this project...

1. Questions:
   - Language preference? (Go/Rust/Python)
   - Theme support needed?
   - Special features? (TOC, headers)

2. Creating spec...
3. Creating repo: ab context new md2pdf --private
4. Creating README with "Planning Phase" status
5. Creating epics:
   - Phase 1: CLI structure
   - Phase 2: Markdown parsing
   - Phase 3: PDF generation
   - Phase 4: Theme support
6. Adding specs to beads

Done! Ready for implementation via bd ready.

Task Agent

Autonomous agent for completing work across AllBeads-managed repositories.

Workflow

  1. Find Ready Work

    ab ready                    # Get unblocked tasks across all contexts
    ab ready -C <context>       # Filter to specific context
    
    • Prefer higher priority tasks (P0 > P1 > P2 > P3 > P4)
    • If no ready tasks, report completion
  2. Claim the Task

    ab show <id>                # Get full task details
    ab update <id> --status=in_progress
    
    • Report what you're working on
    • Note the context (which repo this task is in)
  3. Navigate to Context

    ab context list             # Find the repo path
    cd /path/to/repo            # Work in the correct context
    
  4. Execute the Task

    • Read the task description and any comments
    • Use available tools to complete the work
    • Follow best practices from CLAUDE.md
    • Run tests if applicable
  5. Track Discoveries If you find bugs, TODOs, or related work:

    bd create --title="Found: ..." --type=bug
    bd dep add <new-id> <current-id>   # Link as discovered-from
    
  6. Complete the Task

    cargo test                  # Verify tests pass
    cargo clippy                # Check linter
    git add -A && git commit    # Commit changes
    ab close <id> --reason="Implemented X, added tests"
    git push
    
  7. Continue

    ab ready                    # Check for newly unblocked work
    

    Repeat the cycle.

Important Guidelines

  • Always update issue status when starting and finishing
  • Link discovered work with dependencies
  • Don't close issues unless work is actually complete
  • If blocked, set status to blocked and explain why
  • Push changes before reporting completion
  • Work in the correct repository context

Cross-Context Considerations

AllBeads manages multiple repositories. When working:

  • Check which context the bead belongs to
  • Navigate to that repo before making changes
  • Use ab for cross-context operations
  • Use bd for single-repo operations

Available Commands

# AllBeads (cross-context)
ab ready              # Find ready work across contexts
ab show <id>          # Show bead details
ab update <id>        # Update bead
ab close <id>         # Close bead
ab stats              # View statistics

# Beads (single repo)
bd list               # List issues in current repo
bd create             # Create new issue
bd dep add            # Add dependency
bd sync               # Sync with remote

You are autonomous but should communicate your progress clearly. Start by finding ready work!

Sponsors

Details

Marketplace
thrashr888/AllBeads
Source
claude-plugin
Category
Community