minibeads

A minimal, markdown-based drop-in replacement for steveyegge/beads written in Rust.

Overview

minibeads (mb) is a dependency-aware issue tracker designed for AI agent workflows. Issues are stored as markdown files with YAML frontmatter, making them both human-readable and git-friendly. The tool emphasizes simplicity, with no database required—just markdown files in .beads/issues/.

Key Features

Markdown-only storage: No SQLite, no JSONL—just .md files
Dependency tracking: Issues can block each other, with automatic detection of ready work
AI-friendly: Full MCP (Model Context Protocol) integration for AI agents
Fast: Rust implementation with coarse-grained file locking
Drop-in replacement: Compatible with upstream beads MCP server (https://github.com/steveyegge/beads)

Installation

From crates.io

cargo install minibeads

This installs the mb binary (short for "minibeads"). To use minibeads as a drop-in replacement for upstream beads (e.g., with the beads MCP server), alias or symlink it to bd:

# Symlink approach
ln -s $(which mb) ~/.local/bin/bd

# Or shell alias
alias bd=mb

Build from source

# Clone the repository
git clone https://github.com/rrnewton/minibeads.git
cd minibeads

# Build in debug mode (recommended for development)
make build

# Or build release version
make release

# Install to ~/.local/bin
make install

The binary will be named mb (short for "minibeads").

Quick Start

# Initialize a beads database in your project
mb init

# Create your first issue
mb create "Fix login bug" -p 1 -t bug

# List all issues
mb list

# Show issue details
mb show mb-1

# Update issue status
mb update mb-1 --status in_progress

# Add dependencies (mb-2 blocks mb-1)
mb dep add mb-1 mb-2

# Find ready work (no blockers)
mb ready

# Get statistics
mb stats

Run mb quickstart for a comprehensive guide.

Storage Format

minibeads stores all data in .beads/issues/ as markdown files:

.beads/
├── config.yaml           # Contains issue-prefix
├── .gitignore           # Auto-managed (minibeads.lock, command_history.log)
└── issues/
    ├── myproject-1.md   # Issue files with YAML frontmatter
    └── myproject-2.md

Issue Format

Each issue is a markdown file with YAML frontmatter:

---
title: Fix authentication bug
status: in_progress
priority: 1
issue_type: bug
assignee: alice
depends_on:
  myproject-5: blocks
created_at: 2025-10-30T10:00:00Z
updated_at: 2025-10-30T11:00:00Z
---

# Description

User sessions expire too quickly. Need to extend timeout to 24 hours.

# Design

Update session middleware to use configurable timeout from environment variable.

# Acceptance Criteria

- [ ] Session timeout configurable via SESS_TIMEOUT env var
- [ ] Default remains 1 hour if not set
- [ ] Tests pass for various timeout values

MCP Integration

minibeads works seamlessly with AI agents via the beads MCP server. Agents can:

Create, update, and close issues
Query dependencies and find ready work
Track progress across sessions using the markdown history

Set BEADS_DB or MB_BEADS_DIR environment variables, or let the MCP server auto-discover .beads/ in your project.

Development

Running Tests

# Run all tests (unit + e2e)
make test

# Run full validation (test + fmt + clippy)
make validate

# Format code
make fmt

Project Structure

src/
├── main.rs      # CLI entry point and command handlers
├── storage.rs   # File-based storage operations
├── format.rs    # Markdown serialization/deserialization
├── types.rs     # Core data structures (Issue, Status, etc.)
└── lock.rs      # Coarse-grained file locking

tests/
├── e2e_tests.rs           # Test harness
└── basic_operations.sh    # Shell-based e2e tests

Design Philosophy

Why Markdown?

Human-readable: Issues are plain text files you can read, edit, and grep
Git-friendly: Diffs, merges, and history work naturally
Simple: No schema migrations, no database corruption, no SQL
Portable: Copy .beads/ anywhere, it just works

Why Rust?

Performance: Faster than Go for file operations
Safety: No null pointers, no data races
Zero-copy: Minimize allocations (see CLAUDE.md for patterns)
Small binary: Single ~23MB binary with no runtime dependencies

Locking Strategy

minibeads uses coarse-grained locking with .beads/minibeads.lock containing the process PID. Operations use exponential backoff (up to 5 seconds) when lock is held. This is simpler than upstream's per-issue locking and sufficient for AI agent workflows.

Command Reference

Core Commands

mb init [--prefix PREFIX] - Initialize beads database
mb create TITLE [OPTIONS] - Create new issue
mb list [FILTERS] - List issues with optional filters
mb show ISSUE_ID - Show detailed issue information
mb update ISSUE_ID [OPTIONS] - Update issue fields
mb close ISSUE_ID [--reason REASON] - Close (complete) an issue
mb reopen ISSUE_ID... - Reopen closed issues

Dependencies

mb dep add FROM TO [--type TYPE] - Add dependency
- Types: blocks (default), related, parent-child, discovered-from

Queries

mb ready [--assignee USER] [--priority N] - Find ready work (no blockers)
mb blocked - Show blocked issues and what blocks them
mb stats - Show statistics (total, open, blocked, average lead time)

Options

--db PATH - Path to .beads directory
--json - Output JSON format
--mb-validation MODE - Validation mode: silent, warn, error (default) [minibeads-specific]
--mb-no-cmd-logging - Disable command history logging [minibeads-specific]

Differences from Upstream Beads

What's the Same

All MCP operations work identically
Command-line interface is compatible
Issue semantics (status, priority, dependencies)

What's Different

No SQLite database: Markdown is the only storage
No issues.jsonl: Markdown files are the source of truth
Simpler locking: Coarse-grained lock instead of per-issue locks
No comments/events yet: Planned for future releases (see minibeads-9, minibeads-10)
Better markdown sanitization: Auto-escapes section headers in user content

Migration Path

To export for upstream beads compatibility, use mb export (planned in minibeads-11) to generate issues.jsonl. Bidirectional sync (minibeads-12) will enable hybrid workflows.

Roadmap

See .beads/issues/ for tracking:

minibeads-9: Comments data model
minibeads-10: Events/audit trail
minibeads-11: Export to issues.jsonl format
minibeads-12: Bidirectional jsonl/markdown sync
minibeads-7: Colorful CLI output

Environment Variables

MB_BEADS_DIR - Path to .beads directory [minibeads-specific]
BEADS_DB - Path to .beads database (supports .db extension for compatibility)
BEADS_WORKING_DIR - Working directory for MCP operations

Contributing

Read CLAUDE.md for coding conventions (strong types, zero-copy patterns)
Read OPTIMIZATION.md for performance guidelines
Use make validate before committing
Follow commit message format (see recent commits)

License

MIT License. See LICENSE for details.

minibeads 0.13.2