Beads + Agent Mail: Multi-Agent Workflows

Beads provides shared memory and issue tracking for agents. MCP Agent Mail provides agent-to-agent messaging. Together they create an "Agent Village" where agents can coordinate autonomously.

Quick Start

1. Initialize Beads in Your Project

# Install Beads
go install github.com/steveyegge/beads/cmd/bd@latest

# Initialize in your project
bd init

# Run doctor to set up git hooks and configuration
bd doctor --fix

2. Configure Your Agent

Add to your CLAUDE.md or AGENTS.md:

## Issue Tracking

Use Beads (`bd`) for all work tracking. Run `bd quickstart` to get started.

- File issues for any work taking longer than 2 minutes
- Check `bd ready --json` to find unblocked work
- Update issue status as you work
- File discovered bugs/issues immediately rather than ignoring them

3. Set Up Agent Mail (Optional)

For multi-agent coordination, add MCP Agent Mail:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh" | bash -s -- --yes

Core Beads Commands

Command	Purpose
bd init	Initialize Beads in a project
bd doctor [--fix]	Diagnose and fix issues, run migrations
bd ready --json	List unblocked work items ready for execution
bd cleanup --days N	Remove issues older than N days
bd sync	Sync database and push to git
bd upgrade	Upgrade Beads to latest version

Best Practices

Keep the Database Small

Run bd cleanup every few days. Keep under 200-500 issues for best performance:

bd cleanup --days 2
bd sync

Use Short Issue Prefixes

Configure a 2-3 character prefix for readability:

# Examples: bd-, vc-, wy-, ef-
bd config prefix my-

Plan Outside, Execute Inside

1. Create your plan using your preferred planning tool
2. Iterate and refine the plan up to 5 times with the agent
3. Ask the agent to file Beads epics and issues from the plan, focusing on:
   • Dependencies between tasks
   • Detailed designs
   • Potential parallelization
4. Iterate and refine the Beads epics up to 5 times
5. Execute by having agents work through bd ready items

The agent will say "I don't think we can do much better than this" when iteration is complete.

Restart Agents Frequently

• Tackle one issue per agent session
• Kill the process after completing each issue
• Beads maintains context between sessions
• Saves money and improves model performance

File Issues Liberally

Agents should file issues for:

• Any work taking > 2 minutes
• Discovered bugs (even if "unrelated") - use --discovered-from to link to parent issue
• Code review findings
• Technical debt noticed during work

When doing code reviews, tell agents to file beads as they go - this produces more actionable findings.

# Link a discovered bug to the issue you were working on
bd create --title "Fix null check in auth" --discovered-from ISSUE-123

Multi-Agent Coordination

Agent Village Setup

Two approaches for multi-agent work:

Git Worktree Model (Recommended):

• Each agent works in its own git worktree/branch
• No file locking needed
• Use Agent Mail for coordination
• Merge work via git

Single Folder Model:

• All agents share one folder
• Use Agent Mail's file reservation system
• Agents negotiate file access via messaging

Agent Mail Integration

With Beads + Agent Mail, agents can:

• Share memory (Beads issues as shared state)
• Send messages to coordinate
• Self-organize leadership and task splitting
• Work autonomously with minimal setup

Just tell agents: "Go sort it out amongst yourselves" - they will:

1. Quickly decide on a leader
2. Split up the work
3. Coordinate via messaging
4. Track progress in Beads

Work Claiming

Agents claim work by setting status and assignee:

# Check what's available (filter by assignee if needed)
bd ready --json
bd ready --json --assignee=agent1

# Claim an issue
bd update ISSUE-123 --status in_progress --assignee agent1

# Other agents can see what's claimed
bd list --status in_progress

Multiple agents on different machines can query the same Beads database via git.

Troubleshooting

Merge Conflicts

Beads conflicts happen during rebases/merges. Ask your agent to:

• Clean up broken rebases
• Resolve conflicts intelligently
• Run bd doctor --fix after resolution

Large Database Issues

If issues.jsonl exceeds ~25k tokens:

• Run bd cleanup --days 2
• Issues remain in git history for reference
• Keep working set small for agent file reading

Daily Maintenance

Run daily:

bd doctor
bd upgrade  # weekly

Example Workflow

# Morning: Check what's ready
bd ready --json

# Claim an issue
bd update ISSUE-123 --status in_progress --assignee agent1

# During work: file discovered issues with link to parent
bd create --title "Fix flaky test in auth module" --discovered-from ISSUE-123

# Complete work
bd update ISSUE-123 --status done
bd sync

# End of session: cleanup
bd cleanup --days 2

Beads Viewer (bv)

A terminal UI for visualizing Beads issues and dependencies.

Installation

One-line installer:

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_viewer/main/install.sh?$(date +%s)" | bash

Or build from source (requires Go 1.21+):

git clone https://github.com/Dicklesworthstone/beads_viewer.git
cd beads_viewer
go install ./cmd/bv

Usage

Navigate to any Beads-initialized project and run:

bv

The viewer automatically discovers .beads/beads.jsonl in your current directory.

Key Navigation

Key	Action
j/k	Navigate items
/	Fuzzy search
b	Kanban board view
i	Insights dashboard
g	Dependency graph
h	History (commit correlation)
?	Show all keyboard shortcuts
`	Built-in tutorial
q	Quit

Custom Directory

For monorepos or non-standard layouts:

BEADS_DIR=/path/to/shared/beads bv

Using Beads Viewer with Agents

bv is a graph-aware triage engine for Beads projects. Instead of parsing JSONL or hallucinating graph traversal, use robot flags for deterministic, dependency-aware outputs with precomputed metrics (PageRank, betweenness, critical path, cycles, HITS, eigenvector, k-core).

Scope boundary: bv handles what to work on (triage, priority, planning). For agent-to-agent coordination (messaging, work claiming, file reservations), use MCP Agent Mail.

CRITICAL: Use ONLY --robot-* flags. Bare bv launches an interactive TUI that blocks your session.

The Workflow: Start With Triage

bv --robot-triage is your single entry point. It returns everything you need in one call:

• quick_ref: at-a-glance counts + top 3 picks
• recommendations: ranked actionable items with scores, reasons, unblock info
• quick_wins: low-effort high-impact items
• blockers_to_clear: items that unblock the most downstream work
• project_health: status/type/priority distributions, graph metrics
• commands: copy-paste shell commands for next steps

bv --robot-triage        # THE MEGA-COMMAND: start here
bv --robot-next          # Minimal: just the single top pick + claim command

Planning Commands

Command	Returns
--robot-plan	Parallel execution tracks with unblocks lists
--robot-priority	Priority misalignment detection with confidence

Graph Analysis

Command	Returns
--robot-insights	Full metrics: PageRank, betweenness, HITS, eigenvector, critical path, cycles, k-core, articulation points, slack
--robot-label-health	Per-label health: health_level (healthy/warning/critical), velocity_score, staleness, blocked_count
--robot-label-flow	Cross-label dependency: flow_matrix, dependencies, bottleneck_labels
--robot-label-attention [--attention-limit=N]	Attention-ranked labels by: (pagerank × staleness × block_impact) / velocity

History & Change Tracking

Command	Returns
--robot-history	Bead-to-commit correlations: stats, histories (per-bead events/commits/milestones), commit_index
--robot-diff --diff-since <ref>	Changes since ref: new/closed/modified issues, cycles introduced/resolved

Other Robot Commands

Command	Returns
--robot-burndown <sprint>	Sprint burndown, scope changes, at-risk items
--robot-forecast <id|all>	ETA predictions with dependency-aware scheduling
--robot-alerts	Stale issues, blocking cascades, priority mismatches
--robot-suggest	Hygiene: duplicates, missing deps, label suggestions, cycle breaks
--robot-graph [--graph-format=json|dot|mermaid]	Dependency graph export
--export-graph <file.html>	Self-contained interactive HTML visualization

Scoping & Filtering

bv --robot-plan --label backend              # Scope to label's subgraph
bv --robot-insights --as-of HEAD~30          # Historical point-in-time
bv --recipe actionable --robot-plan          # Pre-filter: ready to work (no blockers)
bv --recipe high-impact --robot-triage       # Pre-filter: top PageRank scores
bv --robot-triage --robot-triage-by-track    # Group by parallel work streams
bv --robot-triage --robot-triage-by-label    # Group by domain

Understanding Robot Output

All robot JSON includes:

• data_hash — Fingerprint of source beads.jsonl (verify consistency across calls)
• status — Per-metric state: computed|approx|timeout|skipped + elapsed ms
• as_of / as_of_commit — Present when using --as-of; contains ref and resolved SHA

Two-phase analysis:

• Phase 1 (instant): degree, topo sort, density — always available immediately
• Phase 2 (async, 500ms timeout): PageRank, betweenness, HITS, eigenvector, cycles — check status flags

For large graphs (>500 nodes): Some metrics may be approximated or skipped. Always check status.

jq Quick Reference

bv --robot-triage | jq '.quick_ref'                        # At-a-glance summary
bv --robot-triage | jq '.recommendations[0]'               # Top recommendation
bv --robot-plan | jq '.plan.summary.highest_impact'        # Best unblock target
bv --robot-insights | jq '.status'                         # Check metric readiness
bv --robot-insights | jq '.Cycles'                         # Circular deps (must fix!)
bv --robot-label-health | jq '.results.labels[] | select(.health_level == "critical")'

Performance: Phase 1 instant, Phase 2 async (500ms timeout). Prefer --robot-plan over --robot-insights when speed matters. Results cached by data hash.

Use bv instead of parsing beads.jsonl—it computes PageRank, critical paths, cycles, and parallel tracks deterministically.

Resources

• Beads GitHub
• Beads Viewer
• MCP Agent Mail
• Vibe Coding Book