
allbeads
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-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add thrashr888/AllBeads.
Contents
Discovered from sourceSkills 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 repos | Single repository |
| Context-based filtering | Local .beads only |
| Cross-repo dependencies | Local dependencies |
| Federated dashboard | Single 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 Beads | Use Mail |
|---|---|
| Trackable tasks | Real-time alerts |
| Work spanning sessions | Immediate attention needed |
| Dependencies | Status updates |
| Persistent record | Coordination messages |
Best practice: Create a bead AND send mail for important handoffs.
Common Handoff Targets
| Context | Purpose |
|---|---|
AllBeadsWeb | Web UI, API endpoints, dashboard |
AllBeadsApp | macOS native app, menu bar |
AllBeads | CLI, 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:
- CLI:
ab mail inbox - TUI:
ab tuithen Tab to Mail view - Web: https://allbeads.co/dashboard/mail (when logged in)
Message Types
| Type | Use For |
|---|---|
| NOTIFY | Status updates, completions, FYIs |
| REQUEST | Approval needed, input required |
| BROADCAST | Announcements to all agents |
| LOCK/UNLOCK | File coordination |
| HEARTBEAT | Agent 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
- Reference bead IDs in messages for context
- Check inbox when starting work sessions
- Send completion notices after finishing handed-off work
- Use mail for urgency, beads for tracking
- 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:
- Creates branch (or uses pre-created for sandboxed agents)
- Does the work
- 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-autofor 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:
| Agent | Purpose |
|---|---|
| task-agent | Autonomous task completion across contexts |
| governance-agent | Policy enforcement and compliance |
| planning-agent | Project planning without implementation |
| onboarding-agent | Repository onboarding assistance |
Commands Reference
| Command | Purpose |
|---|---|
/create | Create bead in any context (cross-repo handoff) |
/mail | Agent mail for real-time coordination |
/ready | Show unblocked work |
/list | List all beads |
/show | Show bead details |
/stats | Aggregated statistics |
/sync | Sync with remotes |
/context | Manage contexts |
/context-new | Create new GitHub repo |
/project-new | Plan new project (no code) |
/handoff | Hand off to implementation |
/workflow | Workflow guide |
/prime | Prime agent context |
/scan | Scan GitHub for repos |
/governance | Check policies |
/agents | Manage AI agents |
/onboard-repo | Onboard repository |
/blocked | Show blocked work |
/tui | Launch 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 agentsCLAUDE.md- Full project guidespecs/PRD-00.md- Architecture specification
Commands 19
Detect AI agents and track adoption metrics.
Subcommands:
allbeads agents detect- Detect AI agents in current directoryallbeads agents track --context <name> --path <path>- Record scan to metricsallbeads agents stats- View adoption statisticsallbeads agents stats --days <n>- Stats for specific time periodallbeads 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:
| Option | Description |
|---|---|
--description | Repository description |
--private | Create 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-clone | Create on GitHub only, don't clone locally |
--wizard | Use interactive TUI wizard |
--non-interactive | Use defaults without prompts |
Workflow:
- Input Collection - Name, visibility, description via prompts or CLI args
- GitHub Creation - Creates repository using
ghCLI - Clone - Clones repository to local workspace
- Beads Init - Runs
bd initto set up issue tracking - Agent Config - Creates CLAUDE.md and other agent files
- Git Push - Commits and pushes configuration
- Context Add - Adds to AllBeads config
Requirements:
- GitHub CLI (
gh) must be installed and authenticated - Run
gh auth loginif not already authenticated - Token needs
reposcope 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:
| Feature | ab context new | ab 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 contextsallbeads context add <path>- Add a repository as a contextallbeads context add <path> --name <name>- Add with explicit nameallbeads context remove <name>- Remove a contextallbeads context new <name>- Create a new GitHub repository with AllBeads pre-configuredallbeads context onboarding- Show onboarding status for all contexts
When adding a context, AllBeads will:
- Detect the repository name from the folder
- Find the git remote URL
- 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
| Parameter | Required | Description |
|---|---|---|
--context | Yes | Target context name (e.g., AllBeadsWeb, AllBeadsApp) |
--title | Yes | Title of the bead |
--type | No | Type: bug, feature, task, epic, chore (default: task) |
--priority | No | Priority: P0-P4 or 0-4 (default: P2) |
Cross-Repo Task Handoff
This is the primary mechanism for distributing work across the AllBeads ecosystem:
- Identify work for another repo: While working, discover something that belongs elsewhere
- Create the bead:
ab create --context=AllBeadsWeb --title="..." --type=feature - Agent in target repo picks it up: They run
bd readyand see the task - Work flows naturally: Each repo's agent handles its own work
Common Handoff Targets
| Context | What goes there |
|---|---|
AllBeadsWeb | Web UI features, API endpoints, dashboard work |
AllBeadsApp | macOS app features, native UI, menu bar items |
AllBeads | CLI 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 repositoryallbeads governance status- View loaded policies and exemptionsallbeads governance violations- List all policy violationsallbeads governance exempt <repo> <policy> --reason "..."- Exempt a repoallbeads 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 filesOnboardingScore- Minimum onboarding completenessAgentAllowlist- Permitted/denied agent typesPatternAbsent- 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- OpenCodecodex- OpenAI Codexgemini- Gemini CLIaider- Aidercody- Sourcegraph Cody
IDE Agents
cursor- Cursorkiro- Kiro (AWS)antigravity- Antigravitycopilot- VS Code Copilot
Web Agents
jules- Jules (Google) - opens browserchatgpt-codex- ChatGPT Codex - opens browser
What Happens
- Bead context is loaded (title, description, dependencies, labels)
- A prompt is generated from the bead content with workflow instructions
- Bead status is updated to
in_progress - Handoff is recorded (comment +
handed-offlabel) - If
--worktreeis used, a git worktree is created in.worktrees/ - Agent is launched with the prompt
- CLI agents: launched with prompt argument (use
codex exec --full-autofor non-interactive) - IDE agents: launched with chat command
- Web agents: browser opened with deep-link URL
- CLI agents: launched with prompt argument (use
Agent Workflow (What the Agent Does)
The handoff prompt instructs the agent to:
- Create a branch for the work:
git checkout -b bead/<id> - Do the work described in the bead
- Commit changes:
git add -A && git commit -m "feat(<id>): <description>" - Close the bead:
bd close <id>(use--forceif blocked by an epic) - 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:
- Pre-creates the branch before launching (
git checkout -b bead/<id>) - Provides simplified workflow prompt (skip git operations)
- 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:
- Bead context is loaded
- A NOTIFY message is sent via Agent Mail to
{agent}@{context} - Bead status is updated to
in_progress queuedlabel is added to the bead- 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:
| Normal | Queue Mode |
|---|---|
| Spawns new agent process | Sends mail to existing agent |
| Agent starts immediately | Agent picks up when ready |
| One agent per bead | Batched 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 workab list --status=in_progress- All in-progress work/release- Ship a new versionspecs/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 statusallbeads list --priority P1- Filter by priorityallbeads 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 Mail | Use Beads |
|---|---|
| Real-time notifications | Persistent tasks |
| Request immediate input | Work that spans sessions |
| Announce status changes | Trackable deliverables |
| Coordinate handoffs | Dependencies 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:
- CLI:
ab mail inbox - Web: https://allbeads.co/dashboard/mail
- TUI:
ab tui(Tab to Mail view)
Message Types
| Type | Purpose | Example |
|---|---|---|
| NOTIFY | Inform about events | "Build completed successfully" |
| REQUEST | Ask for input/approval | "Approve deployment to production?" |
| BROADCAST | Announce to all agents | "API rate limit reached, pausing" |
| LOCK/UNLOCK | File coordination | "Locking src/auth.rs for refactor" |
| HEARTBEAT | Agent 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
- Always create a bead for trackable work - mail is ephemeral
- Reference bead IDs in mail messages for context
- Use mail for urgency - immediate attention needed
- Check inbox regularly when starting work sessions
- Send completion notifications when finishing handed-off work
- 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:
- Initializes beads tracking (
bd init) - Creates a CLAUDE.md file with project guidance
- Adds the repository to AllBeads contexts
- Optionally runs janitor to discover existing issues
- 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 initto create the.beads/directory - Initializes
issues.jsonlfor 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:
- Clean working directory - No uncommitted changes (excludes
.beads/and.claude/) - Main branch - Must be on
mainormasterbranch
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-marketplaceallbeads@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
-
Project Overview
- Active contexts and paths
- Repository status (beads, agents)
-
Ready Work
- Unblocked beads ready to implement
- Priority-sorted task list
-
Recent Activity
- Recently modified beads
- Recent commits
-
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
- Gather Requirements - Discuss the project idea with the user
- Create Spec - Write a detailed specification document
- Create Repo - Use
ab context newto create GitHub repo - Create README - Add README.md with project overview and status
- Create Beads - Create epic issues with specs embedded in descriptions
- STOP - Do not write implementation code
The implementation will be handled later by:
- User manually starting work
/handoffworkflow (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:
- Ask clarifying questions about requirements
- Write a spec document (can be in AllBeads/specs/ or in the new repo)
- Create the repo:
ab context new <project-name> --private --gitignore <lang> --license <license> - Create README.md with:
- Project overview
- Status: "Planning Phase"
- Planned features table
- Example usage (planned)
- Create beads epics for each phase:
bd create --title="[Phase 1] ..." --type=epic --priority=1 - 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 beadsbd 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:blockedto 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 repositoriesallbeads scan org <org-name>- Scan an organization's repositoriesallbeads 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:blockedto investigate - No in_progress work? Run
/allbeads:readyto find tasks - Stale cache? Run
allbeads sync --allto refresh
Synchronize AllBeads contexts with their git remotes.
Commands:
allbeads sync- Sync the AllBeads config (if in git)allbeads sync --all- Sync all context beadsallbeads sync <context>- Sync a specific contextallbeads 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 viewsj/korUp/Down- Move up/downh/lorLeft/Right- Switch columns (Kanban)Enter- View detailsEsc- Backq- 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
| Phase | Command | Purpose |
|---|---|---|
| Discovery | ab scan github | Find repos |
| Onboarding | ab onboard | Add to AllBeads |
| Planning | ab context new | Create new repo |
| Planning | bd create | Create work items |
| Execution | ab ready | Find work |
| Execution | ab close | Complete work |
| Governance | ab governance check | Verify policies |
Session Protocol
Every session should:
ab prime- Load contextab ready- Find work- Work on tasks
bd sync- Save beadsgit push- Push changes
See Also
AGENTS.md- Quick agent referenceCLAUDE.md- Full project guide/prime- Context priming/ready- Ready work
Agents 4
Governance Agent
Scans and enforces governance policies across AllBeads-managed repositories.
Workflow
-
Scan Repositories
ab governance check # Check all managed repos ab governance check --repo=X # Check specific repo -
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
-
Create Remediation Issues For each violation:
bd create --title="Policy: <violation>" --type=task --priority=2 bd comments add <id> "Violation details and remediation steps" -
Track Agent Coverage
ab agents list # List agents across contexts ab agents summary # Adoption statistics ab scan github <user> # Find unmanaged repos -
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
-
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 -
Assess Onboarding Priority Consider:
- Recent activity (last push date)
- Stars / usage
- Language match with other managed repos
- Existing agent configurations
-
Run Onboarding
ab onboard <repo-url> # Or for local: ab onboard /path/to/repo -
Verify Configuration
ab agents detect /path/to/repo ab context list | grep <repo>
For New Repositories
-
Create with Full Setup
ab context new <name> \ --private \ --gitignore <lang> \ --license MIT \ --init-agents claude,cursor -
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:
- Clean Working Directory: Refuses to onboard if there are uncommitted changes (excluding
.beads/and.claude/directories) - Main Branch: Refuses to onboard if not on
mainormasterbranch
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:
- Filter for git repos with GitHub remotes - Skip non-git folders and repos without remotes
- Run onboarding in parallel where possible
- Create issues for repos that fail safety checks - Don't skip silently
- 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
-
Gather Requirements
- Discuss the project idea with the user
- Ask clarifying questions about:
- Language/framework preferences
- Key features needed
- Scope and priorities
-
Create Specification
- Write a detailed spec document
- Include:
- Project overview
- Use cases
- Technical approach
- Data sources/APIs
- Implementation phases
- Save to
specs/<project>-spec.mdin AllBeads
-
Create Repository
ab context new <project-name> \ --private \ --description "..." \ --gitignore <lang> \ --license <license> -
Create README Write README.md with:
- Project overview
- Status: "Planning Phase"
- Planned features table
- Example usage (planned)
-
Create Phase Epics
bd create --title="[Phase 1] ..." --type=epic --priority=1 bd create --title="[Phase 2] ..." --type=epic --priority=2 # etc. -
Add Specs to Beads For each epic:
bd comments add <id> "<detailed spec>"Include:
- Goals
- Deliverables
- API endpoints / interfaces
- Acceptance criteria
-
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:
/handoffcommand - 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
-
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
-
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)
-
Navigate to Context
ab context list # Find the repo path cd /path/to/repo # Work in the correct context -
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
-
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 -
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 -
Continue
ab ready # Check for newly unblocked workRepeat 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
blockedand 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
abfor cross-context operations - Use
bdfor 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!
Hooks 1
Sponsors
Details
- Marketplace
- thrashr888/AllBeads
- Source
- claude-plugin
- Category
- Community