iflow-mcp_lns2905-beads-village 1.3.0

MCP server for multi-agent workflow with Beads + Agent Mail

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

Claude Desktop

Edit claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

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

Claude Code (CLI)

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

Or create .mcp.json in project root:

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

Cursor

Create .cursor/mcp.json:

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

GitHub Copilot (VS Code)

Add to VS Code settings.json:

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

More IDEs (OpenCode, Cline, Roo Code, Zed, Continue...)

See 📖 Full Setup Guide for complete configuration instructions for all supported IDEs and agents.

---

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
Messages	msg, inbox	Agent communication (msg with global=true for broadcast)
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 "C:\path\to\workspace"

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

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

# 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

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_USE_DAEMON	1	Use daemon if available

---

Troubleshooting

Issue	Solution
bd: command not found	pip install beads
MCP server not starting	Check Node.js 16+
Tools not appearing	Restart IDE after config

# 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

v1.3.2 - Dashboard Launch Fix (Windows)

Bug Fixes:

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

v1.3.1 - CLI Flag Fix

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 daemon fallback detection for --labels and --add-label flags

v1.3.0 - Tool Consolidation & Dashboard Enhancements

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)

v1.2.0 - Textual Dashboard & Optimizations

• Built-in Textual Dashboard - python -m beads_village.dashboard for monitoring
• Auto-start TUI - init(leader=true, start_tui=true) launches dashboard automatically
• 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

v1.1.2 - Role-Based Task Assignment

• 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

v1.1.1 - Token Optimization

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

---

License

MIT