Beads Village

Multi-agent MCP server for task coordination and file locking between AI agents.

Combines Beads (issue tracking) + built-in Agent Mail (messaging) to enable multiple agents to work on the same codebase without conflicts.

💡 Note: Messaging is built-in. No external mail server required. Inspired by MCP Agent Mail concept.

Use Cases

• Multi-agent development: Multiple AI agents working on different parts of a codebase
• Task queue management: Agents claim and complete tasks from a shared queue
• File conflict prevention: Lock files before editing to prevent merge conflicts
• Cross-agent communication: Send messages between agents for coordination

Quick Start

1. Install Prerequisites

pip install beads    # Required: Beads CLI
node --version       # Required: Node.js 16+

2. Install Beads Village

npx beads-village    # Recommended
# or: npm install -g beads-village
# or: pip install beads-village

3. Configure Your IDE/Agent

{
  "mcpServers": {
    "beads-village": {
      "command": "npx",
      "args": ["beads-village"]
    }
  }
}

claude mcp add beads-village -- npx beads-village

{
  "mcpServers": {
    "beads-village": {
      "command": "npx",
      "args": ["beads-village"]
    }
  }
}

{
  "mcpServers": {
    "beads-village": {
      "command": "npx",
      "args": ["beads-village"]
    }
  }
}

{
  "github.copilot.chat.mcp.servers": {
    "beads-village": {
      "command": "npx",
      "args": ["beads-village"]
    }
  }
}

Workflow

init() → claim() → reserve() → [work] → done() → RESTART

📖 Detailed Workflow Guide - Patterns, examples, best practices

Documentation Guide

Choose the right documentation for your AI model:

When to Use Which

┌─────────────────────────────────────────────────────────────┐
│                    Model Capability                          │
├─────────────────────────────────────────────────────────────┤
│  HIGH (Claude 3.5+, GPT-4o, Gemini 1.5 Pro)                 │
│  └─→ Use AGENTS-LITE.md (minimal tokens, maximum signal)    │
│                                                              │
│  MEDIUM (Claude 3 Haiku, GPT-4o-mini, smaller models)       │
│  └─→ Use AGENTS.md (detailed examples needed)               │
│                                                              │
│  LARGE CONTEXT (128K+ tokens available)                      │
│  └─→ Use AGENTS.md (comprehensive reference)                │
│                                                              │
│  LIMITED CONTEXT (<32K tokens)                               │
│  └─→ Use AGENTS-LITE.md (save tokens for code)              │
└─────────────────────────────────────────────────────────────┘

Tools Overview

Beads Viewer Integration (Optional)

The dashboard works without bv. Install bv only if you need advanced graph analysis.

Dashboard Features (Built-in, no bv needed)

Graph Insights (Requires bv)

Launch Dashboard

# Run dashboard for current directory
python -m beads_village.dashboard

# Run dashboard for specific workspace
python -m beads_village.dashboard "C:\path\to\workspace"

# Auto-start when leader inits
init(leader=True, start_tui=True)

Keyboard Shortcuts

Alternative: bv Binary (Go)

For advanced graph analysis, install the optional bv binary:

Installation

# Option 1: Go install (recommended)
go install github.com/Dicklesworthstone/beads_viewer/cmd/bv@latest

# Option 2: Download binary from releases
# https://github.com/Dicklesworthstone/beads_viewer/releases

New Tools (when bv available)

Note: bv_tui and bv_status have been merged into village_tui and status(include_bv=true)

Usage Examples

# Get graph insights for AI decision making
bv_insights()

# Get priority recommendations
bv_priority(limit=5)

# Launch unified TUI dashboard
village_tui()

# Auto-start TUI when leader inits
init(leader=True, start_tui=True)

# Check bv availability via status
status(include_bv=True)

Architecture with bv

┌─────────────────────────────────────────────────────────────┐
│                     MCP Beads Village                        │
├─────────────────────────────────────────────────────────────┤
│  Core Tools              │  bv Tools (optional)             │
│  ──────────              │  ─────────────────               │
│  init, claim, done       │  bv_insights (graph metrics)     │
│  reserve, release        │  bv_plan (execution tracks)      │
│  msg, inbox, broadcast   │  bv_priority (recommendations)   │
│  ls, show, add           │  bv_tui (dashboard)              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     bv Binary (Go)                           │
│  - 9 Graph algorithms: PageRank, Betweenness, HITS, etc.    │
│  - Robot mode: Pre-computed JSON for AI agents              │
│  - TUI mode: Kanban, graph viz, insights dashboard          │
└─────────────────────────────────────────────────────────────┘

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Shared via Git                          │
│  .beads/        .mail/           .reservations/             │
│  (tasks)        (messages)       (file locks)               │
└─────────────────────────────────────────────────────────────┘
        ▲               ▲                  ▲
        │               │                  │
   ┌────┴────┐    ┌─────┴────┐      ┌──────┴─────┐
   │ Agent 1 │    │ Agent 2  │      │  Agent 3   │
   │ (FE)    │    │ (BE)     │      │  (Mobile)  │
   └─────────┘    └──────────┘      └────────────┘

Configuration Summary

📖 Complete Setup Instructions

Environment Variables

Troubleshooting

# Verify installation
bd --version
node --version
npx beads-village --help

Links

• Beads CLI - Git-native issue tracker
• Beads Best Practices
• MCP Agent Mail - Inspiration for messaging concept
• Model Context Protocol

Changelog

License

MIT