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.

INFO

Beads is ideal for team projects - everyone sees the same issues, and changes are tracked in git history.

Prerequisites

Install the Beads CLI from the Beads GitHub repo.

Initialize Beads in your project:

Bash

cd your-project
bd init

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

Basic Usage

INFO

Important: By default, Ralph TUI only shows issues with the ralph label. Either add this label to your issues, or change the label filter during setup (leave blank to see all issues).

Create an Epic

Epics group related tasks. Add the ralph label so Ralph TUI can see it:

Bash

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

Add Tasks as Children of the Epic

Tasks must be children of the epic (using --parent) to appear when running with --epic. Also add the ralph label:

Bash

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

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
bd dep add beads-login beads-api

Run Ralph TUI

Run with the epic ID:

Bash

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

Configuration

CLI Flags

Run with epic and tracker:

Bash

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

Config File

Set defaults in TOML:

TOML

# .ralph-tui/config.toml
tracker = "beads"
 
[trackerOptions]
beadsDir = ".beads"
labels = "ralph"

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	`ralph`	Comma-separated label filter (issues must have these labels)
`workingDir`	string	`.`	Working directory for bd commands

INFO

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

Beads Concepts

Epics

Epics are top-level containers for related work:

Bash

# 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:

Bash

# 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:

Bash

# 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

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 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 stores issues in .beads/beads.jsonl. Sync with your team:

Bash

# Pull latest changes
bd sync
 
# Or manually
git pull

Ralph TUI calls bd sync automatically when you run.

Label Filtering

By default, Ralph TUI filters to issues with the ralph label. This lets you separate "Ralph-managed" work from other issues in the same beads repo.

Adding Labels to Issues

Bash

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

Changing the Label Filter

TOML

# .ralph-tui/config.toml
[trackerOptions]
labels = "ralph,frontend"  # Multiple labels (comma-separated)
# labels = ""              # Empty = show all issues (no filter)

INFO

If no tasks appear, check that your issues have the ralph label (or whatever labels you configured).

How It Works

When Ralph TUI runs with the Beads tracker:

Detect: Check for .beads/ directory and bd CLI
Query: Run bd list --json --parent <epic> to get tasks
Select: Find next task (ready, highest priority)
Update: Set task to in_progress via bd update
Execute: Run agent with task prompt
Complete: Set task to closed via bd update
Sync: Run bd sync to push changes

bd Commands Used

Action	Command
List tasks	`bd list --json --parent <epic>`
Get task	`bd show <id> --json`
Start task	`bd update <id> --status in_progress`
Complete task	`bd update <id> --status closed`
Sync	`bd sync`

Switching Epics

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

Press l to open epic selector
Choose from available epics
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:

Bash

bd init

"bd binary not available"

Install the Beads CLI from the Beads GitHub repo.

"No tasks available"

Check that:

Tasks have the ralph label: bd list --label ralph (or run bd label add <task> ralph)
Tasks are children of the epic: bd list --parent <epic> (create with --parent <epic>)
Tasks are open status: bd list --status open
Dependencies are met: bd show <task-id> (blocked tasks won't be selected)

"Tasks not syncing"

Run sync manually:

Bash

bd sync

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

Creating Tasks from PRDs

Convert a PRD to Beads issues:

Bash

# 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

Feature	JSON	Beads
Setup complexity	Lowest	Medium
External tools	None	`bd` CLI
Git sync	Manual	Automatic
Epic hierarchy	No	Yes
Team collaboration	Limited	Full
Offline support	Full	Full

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