# minibeads
A minimal, markdown-based drop-in replacement for [steveyegge/beads](https://github.com/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
```bash
cargo install minibeads
```
This installs the `mb` binary (short for "minibeads"). To use minibeads as a
drop-in replacement for upstream [beads](https://github.com/steveyegge/beads)
(e.g., with the beads MCP server), alias or symlink it to `bd`:
```bash
# Symlink approach
ln -s $(which mb) ~/.local/bin/bd
# Or shell alias
alias bd=mb
```
### Build from source
```bash
# 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
```bash
# 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:
```markdown
---
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
```bash
# 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
1. Read `CLAUDE.md` for coding conventions (strong types, zero-copy patterns)
2. Read `OPTIMIZATION.md` for performance guidelines
3. Use `make validate` before committing
4. Follow commit message format (see recent commits)
## License
MIT License. See [LICENSE](LICENSE) for details.
## Links
- Upstream beads: https://github.com/steveyegge/beads
- MCP specification: https://modelcontextprotocol.io