A minimal, markdown-based drop-in replacement for steveyegge/beads written in Rust.
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 .minibeads/issues/.
- Markdown-only storage: No SQLite, no JSONL—just
.mdfiles - 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)
cargo install minibeadsThis 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=mbUse Rust 1.87 or newer (required by the build-time metadata helper).
# 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 installThe binary will be named mb (short for "minibeads").
# 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 statsRun mb quickstart for a comprehensive guide.
minibeads stores all data in .minibeads/issues/ as markdown files. Existing
projects with .beads/ continue to work as a legacy fallback until you move the
directory.
.minibeads/
├── 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
├── comments/ # Optional per-issue comment JSON files
├── github-sync-state.json # Comment pairings and legacy content hashes
└── sync_ancestors/ # Git-ignored common synchronization history
└── github/ # Versioned, content-keyed per-issue checkpoints
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 valuesminibeads 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 .minibeads/ in your project.
# Run all tests (unit + e2e)
make test
# Run full validation (Rust tests + e2e + fmt + clippy)
make validate
# Run longer randomized/stress suites
make stress-test
# Format code
make fmtsrc/
├── 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
└── merge_driver.rs, issue_merge.rs, diff3.rs # Git merge driver (see src/README.md)
tests/
├── e2e_tests.rs # Test harness
└── basic_operations.sh # Shell-based e2e tests
- 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
.minibeads/anywhere, it just works
- 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
minibeads uses coarse-grained locking with .minibeads/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.
mb init [--prefix PREFIX]- Initialize beads databasemb create TITLE [OPTIONS]- Create new issuemb list [FILTERS]- List issues with optional filtersmb show ISSUE_ID- Show detailed issue informationmb update ISSUE_ID [OPTIONS]- Update issue fields--search TEXT --replace TEXT [--field FIELD] [--replace-all]- targeted, aider-style edit of a text field (defaultdescription) instead of overwriting it wholesale. By default the search text must match exactly once; a missing or ambiguous match is an error and the issue is left untouched. This is the recommended way for agents to revise a long description — far safer than rewriting the whole field. (minibeads-specific)--append TEXT [--field FIELD]- appendTEXTto the end of a text field (defaultdescription), inserting a blank line before it when the field is non-empty so it becomes its own paragraph. Simpler than a search/replace when you only want to add to the end. (minibeads-specific)
mb close ISSUE_ID [--reason REASON]- Close (complete) an issuemb reopen ISSUE_ID...- Reopen closed issuesmb comments add ISSUE_ID --body TEXT- Add a local issue commentmb comments list ISSUE_ID- List local issue commentsmb comments delete ISSUE_ID COMMENT_ID...- Delete local issue comment(s) by ID (minibeads-specific)
mb dep add FROM TO [--type TYPE]- Add dependency- Types:
blocks(default),related,parent-child,discovered-from
- Types:
mb ready [--assignee USER] [--priority N]- Find ready work (no blockers)mb blocked- Show blocked issues and what blocks themmb stats- Show statistics (total, open, blocked, average lead time)mb list --github- Show only issues linked to GitHub Issues
minibeads can sync a subset of issues with GitHub Issues using the authenticated
gh CLI. Linked issues store the GitHub issue URL in external_ref; unlinked
issues are ignored.
mb github link ISSUE_ID GITHUB_ISSUE [-R owner/repo]- Link to an existing GitHub issuemb github list- Show current minibeads-to-GitHub issue linksmb github import [-R owner/repo] [--state open|closed|all] [--label LABEL] [--assignee USER] [--author USER] [--mention USER] [--milestone M] [--app APP] [--search QUERY] [--limit N] [--dry-run] [--quiet|--verbose]- Import matching GitHub issues that are not already linked to minibeads issuesmb github publish ISSUE_ID [-R owner/repo]- Create a GitHub issue and link itmb github sync [ISSUE_ID...] [--label LABEL...] [-R owner/repo] [--since CUTOFF] [--dry-run] [--pull-only] [--force] [--quiet|--verbose]- Sync selected linked issuesmb github stress-test -R owner/repo [-n N] [--steps N] [--seed N] [--adversarial] [--verbose]- Create real temporary GitHub issues in a disposable repo and run seeded randomized sync stress tests
Synced issue fields are title, description/body, and GitHub's open/closed state.
minibeads stores their last common contents in versioned per-issue records under
.minibeads/sync_ancestors/github/ (or the selected legacy .beads directory).
It performs content-based three-way reconciliation rather than choosing the
newest timestamp. Independent field and prose changes merge; incompatible edits
remain conflicts. Local workflow states such as in_progress survive while the
GitHub issue remains open. Labels, priority, assignee, dependencies, and other
minibeads-specific metadata remain local.
Repeat --label to require every supplied local label. Labels, explicit IDs,
and --since intersect. A selection matching nothing performs no GitHub calls
and does not become a full sync. --since examines local timestamps only; omit
it when remote-only changes must be discovered.
When no common content checkpoint exists, matching copies establish one.
Divergent copies require manual reconciliation; minibeads will not silently pick
a side from timestamps or visit order. --pull-only --force is the explicit
escape hatch for choosing GitHub and discarding the synchronized local fields.
Ordinary bidirectional --force does not hide merge conflicts.
The prose merger preserves independent paragraphs from both replicas, uses stable content-derived ordering for additions at the same boundary, and refines plain-prose overlap to words and whitespace. Competing word edits, delete/edit, ambiguous repeated text, overlapping structured Markdown, and bounded-work exhaustion are reported distinctly and leave all inputs unchanged.
Mutating syncs serialize per GitHub issue, and the common ancestor plus comment
ancestry commit in one recoverable local transaction. Remote contents are
refreshed before a write, verified afterward, and racing changes receive bounded
reconciliation retries. GitHub's issue API does not provide a compare-and-swap
operation for this workflow, so a small remote race remains possible and is documented in
ai_docs/github-sync-design.md.
Comment ancestry remains in github-sync-state.json as a separate protocol.
Deleting a local comment (for example with mb comments delete) deletes its
GitHub counterpart on the next bidirectional sync. A missing remote counterpart
requires --force before deleting the local comment. Pull-only never writes or
deletes comments on GitHub. Comment bodies do not use the prose merger.
Linked GitHub issues get a marker comment containing MB_DO_NOT_SYNC so people
viewing the GitHub issue can see which local minibeads issue owns the sync. That
marker comment is ignored by comment sync and is not imported into minibeads.
mb github import only creates local issues for GitHub issues whose URL is not
already present in any local issue's external_ref; already linked issues remain
the responsibility of mb github sync.
By default, mb github sync prints one informative line per linked issue plus a
summary. Use --quiet for only the summary line, or --verbose to include
field/comment details under each issue and print each underlying gh CLI call
with elapsed time to stderr.
Design note: upstream Beads has an external_ref field and import/collision
logic around it, but does not provide this exact GitHub sync workflow in the
vendored version. minibeads uses the same external_ref idea for the URL and
keeps synchronization history outside issue Markdown to avoid churning normal
issue fields. Local Markdown/JSONL mb sync is a separate timestamp-based
protocol; the GitHub common-content archive does not change that behavior.
Issue files and comment files are ordinary files under version control, so two
branches that touch the same issue meet in git merge. Git's line merge handles
them poorly: both sides always change updated_at:, two appended comments
collide at the end of the JSON array, and two edits to one long prose line
conflict. mb merge-driver replaces it with a field-aware three-way merge that
uses the merge base git already computed.
Install it once per clone (or with --global once per machine):
mb merge-driver install # git config merge.mb.* + .gitattributes lines
mb merge-driver install --command /path/to/mb # pin an executable instead of PATH lookup
mb merge-driver show # print the config and attributes without changing anythinginstall writes merge.mb.name and merge.mb.driver into the local git config
and appends any missing routing lines to the repository's .gitattributes
(commit that file so every clone routes the same paths; each clone still needs
the git config part, because git never runs drivers named by the repository
alone). The equivalent manual setup is:
git config merge.mb.name "minibeads three-way issue and comment merge"
git config merge.mb.driver "mb merge-driver run %O %A %B --marker-size %L --path %P"
cat >> .gitattributes <<'ATTRS'
**/.minibeads/issues/**/*.md merge=mb
**/.minibeads/comments/*.json merge=mb
**/.beads/issues/**/*.md merge=mb
**/.beads/comments/*.json merge=mb
ATTRSMerge rules:
- Scalar fields (title, status, priority, type, assignee, external ref, claim window) take the side that changed; two different changes conflict.
- Labels merge as a set (additions and removals from both sides). Dependencies merge per target issue; changing a dependency's type on one side while removing it on the other conflicts.
- Timestamps never conflict:
created_atkeeps the earliest,updated_atthe latest, andclosed_atfollows the merged status. - Prose sections (Description, Design, Acceptance Criteria, Notes) use the same bounded paragraph/word merger as GitHub sync. Edits to different paragraphs merge; competing edits conflict. A side that already contains the other side's whole change is taken as it stands. The merger is conservative: when repeated text makes the alignment of two edits ambiguous it reports a conflict rather than guess.
- Comments merge as a three-way set keyed by comment ID: comments added on
either side are all kept, exactly once, in
created_atorder. A comment deleted on one side is deleted, as git would delete its lines, unless the other side edited it: then the edited comment is kept, with aNOTICEon stderr. A GitHub-imported comment edited on both sides takes the newer GitHub revision; a local comment edited on both sides merges its body as prose or conflicts. - Files with no merge base (both branches created the same ID) merge only when identical; otherwise the whole file is one conflict.
- Input that is not exactly what
mbwrites (hand-edited YAML, unknown keys) is never re-serialized: if only one side changed it is taken byte for byte, otherwise the file falls back to a plain line merge.
Conflicts are written as standard diff3 hunks with fixed labels, confined to the lines of the conflicting field, paragraph, or comment:
<<<<<<< ours
title: Main title
||||||| base
title: Original title
=======
title: Feature title
>>>>>>> theirs
Everything outside the hunks is already merged, so a tool can resolve a file
by keeping one section of each hunk: keeping the same side everywhere
reproduces exactly that side's value of every conflicting field. Markers are
made longer than any content line that looks like one (such as a setext
======= underline), so they are never ambiguous. Git's own tools assume
markers of exactly conflict-marker-size (default 7), so git diff --check
and rerere do not recognize a grown hunk; resolve such a file by hand or with
a resolver that reads the marker length from the <<<<<<< line. The driver
also prints one mb merge-driver: CONFLICT <path>: <field or comment>: <reason> line per conflict. mb refuses to read an issue file that still
contains a hunk outside a code fence, so a hunk accidentally committed is
reported instead of silently parsed as prose. (Text that quotes a conflict outside fenced code is
stored with its <<<<<<< line escaped as \<<<<<<< and reads back
unchanged; fenced code is stored as it is.)
mb merge-driver run BASE OURS THEIRS --path REPO/PATH --stdout previews a
merge without writing any file.
--db PATH- Path to .minibeads 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]
- All MCP operations work identically
- Command-line interface is compatible
- Issue semantics (status, priority, dependencies)
- 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
- File-backed comments: Comments are stored separately from issue markdown
- Better markdown sanitization: Auto-escapes section headers in user content
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.
See .minibeads/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
MB_BEADS_DIR- Path to .minibeads directory [minibeads-specific]BEADS_DB- Path to .beads database (supports.dbextension for compatibility)BEADS_WORKING_DIR- Working directory for MCP operations
- Read
CLAUDE.mdfor coding conventions (strong types, zero-copy patterns) - Read
OPTIMIZATION.mdfor performance guidelines - Use
make validatebefore committing - Follow commit message format (see recent commits)
MIT License. See LICENSE for details.
- Upstream beads: https://github.com/steveyegge/beads
- MCP specification: https://modelcontextprotocol.io