Beads Tracker

Beads Tracker

The Beads tracker integrates with Beads, a git-backed issue tracker. Issues are stored as JSONL in your repo and sync across team members via git.

Prerequisites

Install the Beads CLI from the Beads GitHub repo.

Initialize Beads in your project:

cd your-project
bd init

This creates a .beads/ directory with your issue tracker.

Basic Usage

bd create --title "User Authentication" --type epic
# Created: beads-abc123

bd create --title "Login form" --type task --parent beads-abc123
bd create --title "Auth API" --type task --parent beads-abc123

# Login form depends on Auth API being done first
bd dep add beads-login beads-api

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

Configuration

CLI Flags

Run with epic and tracker:

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

Config File

Set defaults in TOML:

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

Options Reference

Beads Concepts

Epics

Epics are top-level containers for related work:

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

Tasks

Tasks are individual work items, optionally under an epic:

# Create standalone task
bd create --title "Fix login bug" --type task
 
# Create task under epic
bd create --title "Add toggle switch" --type task --parent beads-xyz

Dependencies

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

# Add dependency: task-b depends on task-a
bd dep add beads-task-b beads-task-a
 
# View dependencies
bd show beads-task-b

Statuses

Priorities

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

Task Selection

The Beads tracker selects the next task by:

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

Git Sync

Beads stores issues in .beads/beads.jsonl. Sync with your team:

# Export tracker state to JSONL (safe, no git side effects)
bd sync --flush-only
 
# Then commit and push manually
git add .beads/ && git commit -m "Update beads" && git push

Ralph TUI calls bd sync --flush-only automatically when you run, which exports tracker state to JSONL without performing any git operations. This prevents data loss on branches that haven't been pushed to a remote.

Label Filtering (Optional)

You can optionally filter issues by labels to separate different types of work in the same beads repo.

Adding Labels to Issues

# Add label when creating
bd create --title "My task" --type task --label frontend
 
# Add label to existing issue
bd label add beads-xyz backend

Configuring the Label Filter

# .ralph-tui/config.toml
[trackerOptions]
labels = "frontend,backend"  # Only show issues with these labels
# labels = ""                # Empty (default) = show all issues

How It Works

When Ralph TUI runs with the Beads tracker:

1. Detect: Check for .beads/ directory and bd CLI
2. Query: Run bd list --json --parent <epic> to get tasks
3. Select: Find next task (ready, highest priority)
4. Update: Set task to in_progress via bd update
5. Execute: Run agent with task prompt
6. Complete: Set task to closed via bd update
7. Sync: Run bd sync --flush-only to export state to JSONL

bd Commands Used

Switching Epics

Change epics mid-session by pressing l in the TUI:

1. Press l to open epic selector
2. Choose from available epics
3. Task list updates to show new epic's tasks

Or restart with a different --epic flag.

Troubleshooting

"Beads directory not found"

Initialize Beads in your project:

bd init

"bd binary not available"

Install the Beads CLI from the Beads GitHub repo.

"No tasks available"

Check that:

1. Tasks are children of the epic: bd list --parent <epic> (create with --parent <epic>)
2. Tasks are open status: bd list --status open
3. Dependencies are met: bd show <task-id> (blocked tasks won't be selected)
4. Label filter matches (if configured): bd list --label <your-label>

"Tasks not syncing"

Run sync manually:

bd sync --flush-only
git add .beads/ && git commit -m "Sync beads"

Check for git conflicts in .beads/beads.jsonl.

Creating Tasks from PRDs

Convert a PRD to Beads issues:

# Create PRD
ralph-tui create-prd --chat
 
# When prompted, choose "Beads" format
# Or convert manually:
ralph-tui convert --to beads ./tasks/my-prd.md

Beads vs JSON Tracker

Choose JSON for quick experiments, Beads for team projects.

Next Steps

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