ba

Simple task tracking for LLM sessions.

ba - because sometimes you need to go back before bd

A spiritual fork of beads (bd), keeping the simplicity of v0.9.6 with added session-based claiming for multi-agent coordination.

Philosophy

• Dead simple: Single binary, minimal dependencies
• Plain text: JSONL files, human-readable, git-friendly
• Multi-agent: Sessions claim issues, obvious ownership
• Zero infrastructure: No SQLite, no daemon - just files

Installation

cargo install ba
# or build from source
cargo build --release

Quick Start

# Show quick start guide for LLMs
ba quickstart

# Initialize in your project
ba init

# Create issues
ba create "Fix auth bug" -t bug -p 1
ba create "Add feature" -t feature -d "Description here"

# List issues (excludes closed by default)
ba list
ba list --all              # Include closed
ba list --status open      # Filter by status

# Show issue details
ba show ab-x7k2

Ownership-Based Workflow

Status is a side-effect of ownership transitions, not set directly:

# Take ownership (open/closed → in_progress)
ba claim ab-x7k2 --session claude-abc123

# Abandon work (in_progress → open)
ba release ab-x7k2

# Complete work (in_progress → closed)
ba finish ab-x7k2

# Close unclaimed issue (escape hatch)
ba close ab-x7k2

This ensures every in-progress issue has an owner. Claiming a closed issue cleanly reopens it.

Modifying Issues

# Change priority
ba priority ab-x7k2 0      # 0 = critical

# Add/remove labels
ba label ab-x7k2 add urgent
ba label ab-x7k2 remove urgent

# Add comments
ba comment ab-x7k2 "Found root cause" --author claude

Dependencies

Track blocking relationships between issues:

# Add a blocking dependency (blocker blocks id)
ba block ab-x7k2 ab-y8m3    # ab-x7k2 is now blocked by ab-y8m3

# Remove a blocking dependency
ba unblock ab-x7k2 ab-y8m3

# Visualize dependency tree
ba tree ab-x7k2
# Output:
# ab-x7k2: Fix auth bug [OPEN]
# └── ab-y8m3: Add user model [IN_PROGRESS]

# Detect circular dependencies
ba cycles

Ready Queue

Show issues ready to work on (open + not blocked):

ba ready
# Output:
#   ID        P  TYPE     TITLE
#   ------------------------------------------------------------
#   ab-x7k2   0  bug      Fix critical auth bug
#   ab-z9n4   1  feature  Add dashboard
#   ab-a1b2   2  task     Write tests
#
# 3 issue(s) ready

An issue is "ready" when:

• Status is open (not in_progress or closed)
• All blocking issues are closed (or has no blockers)

Multi-Agent Coordination

When multiple LLM agents work on the same codebase:

# Claim an issue (caller provides their session ID)
ba claim ab-x7k2 --session claude-abc123

# See what you've claimed
ba mine --session claude-abc123

# Complete work
ba finish ab-x7k2

# Or release back to pool
ba release ab-x7k2

The ownership model ensures no two agents work on the same issue. See Ownership-Based Workflow above.

Importing from Beads

Migrate issues from a beads (bd) export file:

# Import with new IDs (uses project prefix)
ba import .beads/issues.jsonl

# Keep original beads IDs
ba import .beads/issues.jsonl --keep-ids

The import handles dependencies automatically and provides clear error messages:

Imported 112 issues (0 skipped, 1 errors)

Errors:
  Line 46: Issue 'as-9q7' - issue_type: Unknown type 'merge-request', expected bug/feature/task/epic/chore/refactor/spike

Only blocks dependencies are imported (other types like related, parent-child, discovered-from are skipped).

Issue Types

• task - Default, general work item
• epic - Container for grouping related issues
• refactor - Improving existing code (no new behavior)
• spike - Research/investigation (may not produce code)

Priorities

• 0 - Critical (security, data loss, broken builds)
• 1 - High (major features, important bugs)
• 2 - Medium (default - nice-to-have features, minor bugs)
• 3 - Low (polish, optimization)
• 4 - Backlog (future ideas)

Storage

Data stored in .ba/ directory:

• config.json - Project config (version, ID prefix)
• issues.jsonl - One issue per line, sorted by ID

Why JSONL?

• Git-friendly: One issue per line = conflicts are per-issue
• Human-readable: Easy to inspect with standard tools
• Grep-able: grep ab-x7k2 .ba/issues.jsonl

IDs

Format: {prefix}-{random} (e.g., ab-x7k2)

• prefix: 2 chars derived from project path hash
• random: 4 chars lowercase alphanumeric

Same project always gets same prefix, different projects get different prefixes.

JSON Output

All commands support --json for programmatic use:

ba --json list
ba --json show ab-x7k2
ba --json create "New issue" -t task

Acknowledgment

ba is inspired by beads by Steve Yegge - an excellent issue tracker for AI-assisted development. We loved beads v0.9.6's simplicity before it evolved into a full messaging/routing system. ba takes that original simplicity and adds an ownership-based state machine for multi-agent coordination.

License

Source-available. See LICENSE for details.