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

npx beads-village --setup

The setup wizard will:

1. Install a beads backend (br or bd)
2. Configure your IDE (Claude Code or OpenCode)
3. Install the beads-village workflow skill
4. Initialize your workspace

Manual Setup

# Option A: Beads Rust (recommended)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh" | bash
# or: cargo install --git https://github.com/Dicklesworthstone/beads_rust.git

# Option B: Beads Go
npm install -g @beads/bd
# or: go install github.com/steveyegge/beads/cmd/bd@latest

Project-level (.mcp.json in project root):

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

Or via CLI:

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

Edit ~/.config/opencode/config.json:

{
  "mcp": {
    "beads-village": {
      "type": "local",
      "command": ["npx", "-y", "beads-village"]
    }
  }
}

See Full Setup Guide for all supported IDEs.

Workflow

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

| Step | Description | |------|-------------| | init() | Join workspace (call FIRST) | | claim() | Get next task | | reserve() | Lock files before editing | | done() | Complete task, release locks | | RESTART | New session for next task |

📖 Detailed Workflow Guide - Patterns, examples, best practices

Documentation Guide

Choose the right documentation for your AI model:

| Document | Best For | Size | |----------|----------|------| | AGENTS-LITE.md | High-capability models (Claude 3.5+, GPT-4+, Gemini Pro) with limited context | ~1.5KB | | AGENTS.md | All models, comprehensive reference with examples | ~16KB | | docs/SETUP.md | Setup instructions for all IDEs/agents | ~6KB | | docs/WORKFLOW.md | Workflow patterns and best practices | ~5KB |

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

| Category | Tools | Description | |----------|-------|-------------| | Lifecycle | init, claim, done | Task workflow | | Issues | add, assign, ls, show | Task management (ls supports status="ready") | | Files | reserve, release, reservations | Conflict prevention (shared/exclusive locks, region hints) | | Messages | msg, inbox, search_messages, ack_message | SQLite-backed messaging with FTS5 search and ack tracking | | Status | status | Team visibility (use include_agents=true for discovery) | | Maintenance | sync, cleanup, doctor | Housekeeping | | Graph Analysis | bv_insights, bv_plan, bv_priority, bv_diff | Requires optional bv binary | | Dashboard | village_tui | Launch visual TUI dashboard |

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)

| Panel | Description | |-------|-------------| | Teams | Click to filter agents by team | | Agents | Shows online/offline status, current task | | Tasks Board | Kanban view (Open/In Progress/Blocked/Closed) | | Task Detail | Click any task for full details + activity | | File Locks | Active file reservations with TTL | | Messages | Recent broadcasts and done notifications | | Filter Recipes | Quick filters: All, Actionable, Blocked, High Impact, Stale |

Graph Insights (Requires bv)

| Feature | Without bv | With bv | |---------|------------|---------| | Keystones, Bottlenecks | ❌ | ✅ | | PageRank, Betweenness | ❌ | ✅ | | Cycle Detection | ❌ | ✅ | | Parallel Execution Plan | ❌ | ✅ |

Launch Dashboard

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

# Run dashboard for specific workspace
python -m beads_village.dashboard /path/to/workspace

Keyboard Shortcuts

| Key | Action | |-----|--------| | 1-8 | Focus different panels | | Tab | Navigate between panels | | j/k | Scroll up/down | | r | Refresh data | | t | Toggle dark/light theme | | q | Quit |

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)

| Tool | Description | |------|-------------| | bv_insights | Graph analysis (PageRank, Betweenness, bottlenecks, cycles) | | bv_plan | Parallel execution tracks for multi-agent work | | bv_priority | Priority recommendations based on graph metrics | | bv_diff | Compare changes between git revisions |

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()

# 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              │  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)  │
   └─────────┘    └──────────┘      └────────────┘
        │               │                  │
        └───────────┬────┘─────────────────┘
                    ▼
     ┌──────────────────────────────┐
     │   CLI Backend (auto-detect)  │
     │  ┌──────────┐ ┌───────────┐ │
     │  │ bd (Go)  │ │ br (Rust) │ │
     │  └──────────┘ └───────────┘ │
     └──────────────────────────────┘

Configuration Summary

| Client | Config Location | Config Key | |--------|-----------------|------------| | Claude Desktop | claude_desktop_config.json | mcpServers | | Claude Code | .mcp.json | mcpServers | | Cursor | .cursor/mcp.json | mcpServers | | GitHub Copilot | settings.json | github.copilot.chat.mcp.servers | | Amp Code | .amp/settings.json | amp.mcpServers | | Kilo Code | settings.json | kilocode.mcpServers | | Windsurf | ~/.windsurf/mcp.json | mcpServers | | OpenCode | opencode.json | mcpServers | | Cline | Cline settings | mcpServers | | Roo Code | Roo settings | mcpServers | | Zed | Zed settings | context_servers | | Continue | config.yaml | mcpServers |

📖 Complete Setup Instructions

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | BEADS_AGENT | agent-{pid} | Agent name | | BEADS_WS | Current dir | Workspace path | | BEADS_TEAM | default | Team name | | BEADS_BACKEND | auto-detect | Force backend: bd or br |

Troubleshooting

| Issue | Solution | |-------|----------| | bd: command not found | pip install beads or use br alternative | | br: command not found | cargo install --git https://github.com/Dicklesworthstone/beads_rust | | MCP server not starting | Check Node.js 16+ | | Tools not appearing | Restart IDE after config |

# Verify installation
bd --version   # or: br --version
node --version
npx beads-village --help

Links

• Beads CLI - Git-native issue tracker (Go)
• Beads Rust - Alternative Rust implementation
• Beads Best Practices
• MCP Agent Mail - Inspiration for messaging concept
• Model Context Protocol

Changelog

Setup Wizard:

• npx beads-village --setup — interactive one-command setup
• Installs backend (br or bd), configures IDE, initializes workspace
• Supports Claude Code (project/global) and OpenCode
• Bundled beads-village workflow skill auto-installed

Cleanup:

• Removed hive-agent bridge code, tests, and documentation
• Fixed package.json files glob to include Python subpackages

Dual Backend Support:

• Added Beads Rust (br) as alternative backend alongside Beads Go (bd)
• Auto-detection of available backend at runtime (BEADS_BACKEND env var to override)
• Backend-aware command translation for sync and cleanup operations

Architecture Refactor:

• Removed legacy daemon client (bd_daemon_client.py) - daemon was removed in Beads Go v0.51+
• Extracted tool functions into beads_village/tools/ package (6 modules)
• Extracted helpers and state into separate modules (helpers.py, state.py)
• Server.py reduced from ~1200 lines to ~150 lines

Bug Fixes:

• Fixed TOCTOU race condition in file reservations (atomic O_CREAT|O_EXCL)
• Fixed sync command (now uses dolt push/pull for bd, br sync for br)
• Fixed cleanup command (now uses admin cleanup subcommand)
• Fixed bv version detection to support v2+ and future versions
• Fixed version mismatch between pyproject.toml and package.json

Messaging Enhancements:

• Added cc (carbon copy) support to msg tool
• Added thread parameter for threaded conversations
• Added ack_required flag for read acknowledgements
• Added thread filter to inbox tool
• Message cleanup utility for old messages

Testing:

• Added comprehensive test suite (64 tests covering server, tools, and modules)

Bug Fixes:

• Fixed village_tui tool not launching dashboard correctly on Windows
• Improved command escaping for paths with spaces

Bug Fixes:

• Fixed --tag flag error in add tool - now uses correct --labels flag for bd create
• Fixed --tag flag error in assign tool - now uses correct --add-label flag for bd update
• Fixed CLI fallback detection for --labels and --add-label flags

Tool Consolidation (26 → 21 tools):

• broadcast merged into msg(global=true, to="all")
• discover merged into status(include_agents=true)
• ready merged into ls(status="ready")
• bv_status merged into status(include_bv=true)
• bv_tui merged into village_tui

Dashboard Enhancements:

• Added Graph Insights panel (Keystones, Influencers, Cycles)
• Added Filter Recipes panel (All, Actionable, Blocked, High Impact, Stale)
• Dashboard works without bv binary (graph insights require bv)
• Improved scrollbar and alignment
• Status icons for issues (○ open, ◐ in_progress, ✕ blocked, ✓ closed)

• Built-in Textual Dashboard - python -m beads_village.dashboard for monitoring
• Stateless team discovery - Dashboard reads agents from .mail messages (no registry file needed)
• Cross-workspace task lookup - Task details fetched from correct workspace
• I/O optimization - Mail messages cached, reducing disk reads by 80%
• UX improvements - Click navigation: Teams → Agents → Tasks → Task Detail

• Leader/Worker agents - init(leader=true) for leaders, init(role="fe") for workers
• Role tags on tasks - add(tags=["fe"]) to assign tasks to specific roles
• Auto-filtered claim - Workers only see tasks matching their role
• assign() tool - Leaders can explicitly assign tasks to roles

• Tool descriptions reduced by ~50%
• Instructions reduced by ~80%
• Added AGENTS-LITE.md - 1.3KB quick reference

License

MIT