Beads-Rust Tracker

The Beads-Rust tracker integrates with beads-rust, a high-performance Rust rewrite of the Beads issue tracker. It offers the same features as Beads with improved performance and SQLite-based storage.

INFO

Beads-Rust (br) is a drop-in replacement for Beads (bd) with better performance. If you're starting fresh, consider using Beads-Rust.

Prerequisites

Install the Beads-Rust CLI (br) from the beads-rust releases.

Initialize Beads in your project:

Bash

cd your-project
br init

This creates a .beads/ directory with your issue tracker (SQLite database + JSONL export).

Basic Usage

Create an Epic

Epics group related tasks:

Bash

br create --title "User Authentication" --type epic
# Created: ralph-tui-abc123

Add Tasks as Children of the Epic

Tasks must be children of the epic (using --parent) to appear when running with --epic:

Bash

br create --title "Login form" --type task --parent ralph-tui-abc123
br create --title "Auth API" --type task --parent ralph-tui-abc123

INFO

The --parent flag creates a parent-child relationship. Without it, tasks won't appear when filtering by epic.

Add Dependencies (Optional)

If tasks depend on each other, add dependencies so Ralph works on them in the right order:

Bash

# Login form depends on Auth API being done first
br dep add ralph-tui-login ralph-tui-api

Run Ralph TUI

Run with the epic ID:

Bash

ralph-tui run --tracker beads-rust --epic ralph-tui-abc123

Configuration

CLI Flags

Run with epic and tracker:

Bash

ralph-tui run --tracker beads-rust --epic ralph-tui-abc123

Config File

Set defaults in TOML:

TOML

# .ralph-tui/config.toml
tracker = "beads-rust"
 
[trackerOptions]
beadsDir = ".beads"
# labels = "frontend,backend"  # Optional: filter by labels

Options Reference

Option	Type	Default	Description
`beadsDir`	string	`.beads`	Path to .beads directory
`epicId`	string	-	Epic ID to filter tasks (set via `--epic` flag)
`labels`	string	(empty)	Optional comma-separated label filter
`workingDir`	string	`.`	Working directory for br commands

INFO

The epicId should be set via --epic flag rather than config, since you'll likely work on different epics.

PRD Context Injection

INFO

New in Beads-Rust: When an epic has a PRD reference, the PRD content is automatically injected into the agent's context for better task understanding.

Link a PRD to your epic using --external-ref:

Bash

br create --type epic \
  --title "Authentication Feature" \
  --external-ref "prd:./docs/auth-prd.md"

When working on tasks under this epic, Ralph TUI will:

Read the PRD file
Include it in the agent's context
Show progress (completed vs total tasks)

Beads Concepts

Epics

Epics are top-level containers for related work:

Bash

# Create an epic
br create --title "Feature: Dark Mode" --type epic
 
# List epics
br list --type epic

Tasks

Tasks are individual work items, optionally under an epic:

Bash

# Create standalone task
br create --title "Fix login bug" --type task
 
# Create task under epic
br create --title "Add toggle switch" --type task --parent ralph-tui-xyz

Dependencies

Tasks can depend on (be blocked by) other tasks:

Bash

# Add dependency: task-b depends on task-a
br dep add ralph-tui-task-b ralph-tui-task-a
 
# View dependencies
br show ralph-tui-task-b

Statuses

Beads Status	Ralph TUI Status	Description
`open`	`open`	Ready to work
`in_progress`	`in_progress`	Currently being worked on
`closed`	`completed`	Finished
`cancelled`	`cancelled`	Won't do

Priorities

Beads uses 0-4 priority scale (0 = critical):

Priority	Meaning
0	Critical
1	High
2	Medium (default)
3	Low
4	Backlog

Task Selection

The Beads-Rust tracker selects the next task by:

Filter to tasks under the specified epic
Filter to tasks with status open
Filter to tasks with no unresolved dependencies
Sort by priority (lowest number first)
Return the first matching task

Git Sync

Beads-Rust stores issues in SQLite and exports to JSONL for git tracking:

Bash

# Export to JSONL for git
br sync --flush-only
 
# Commit the JSONL
git add .beads/
git commit -m "Update issues"

Ralph TUI calls br sync automatically when completing tasks.

Creating Tasks from PRDs

Use the ralph-tui-create-beads-rust skill (via Claude Code):

Bash

# In Claude Code
/ralph-tui-create-beads-rust

This converts a PRD into:

An epic with PRD reference (--external-ref prd:./path/to/prd.md)
Child tasks for each user story
Dependencies between tasks

Beads-Rust vs Beads (Go)

Feature	Beads (`bd`)	Beads-Rust (`br`)
Performance	Good	Better (Rust)
Storage	JSONL only	SQLite + JSONL
Daemon mode	Yes	No (direct mode)
PRD injection	No	Yes
Plugin name	`beads`	`beads-rust`
Command	`bd`	`br`

INFO

If you have both bd and br installed, use --tracker beads for bd or --tracker beads-rust for br.

br init

"No tasks available"

Check that:

Tasks are children of the epic: br list --parent <epic>
Tasks are open status: br list --status open
Dependencies are met: br show <task-id>
Label filter matches (if configured): br list --label <your-label>

"Tasks not syncing"

Export to JSONL manually:

Bash

br sync --flush-only

Next Steps

Beads Tracker - Original Go-based tracker
Beads-BV Tracker - Smart task selection with graph analysis
JSON Tracker - Simple file-based tracking
Configuration - Full options reference

Beads-Rust Tracker