ba 0.1.0

Simple task tracking for LLM sessions
ba-0.1.0 is not a library.

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

# Update issues
ba update ab-x7k2 --status in_progress
ba update ab-x7k2 --priority 0
ba update ab-x7k2 --assignee alice

# Close issues
ba close ab-x7k2 --reason "Fixed in commit abc123"

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, use claims to coordinate:

# Claim an issue (caller provides their session ID)
ba claim ab-x7k2 --session claude-abc123
# Sets status to in_progress, records session_id

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

# Release when done or switching
ba release ab-x7k2
# Sets status back to open, clears session_id

Claiming prevents other agents from working on the same issue. The session ID is whatever the caller provides (e.g., Claude's session ID).

Labels and Comments

Organize and discuss issues:

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

# Add comments
ba comment ab-x7k2 "Found the root cause" --author claude
ba comment ab-x7k2 "Fixed in commit abc123"  # defaults to anonymous

Labels and comments are shown in ba show output.

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

  • bug - Something broken
  • feature - New functionality
  • task - Work item
  • epic - Large feature composed of subtasks
  • chore - Maintenance work
  • refactor - Code restructuring
  • spike - Research/investigation

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

ac 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. ac takes that original simplicity and adds session-based claiming for multi-agent coordination.

License

Source-available. See LICENSE for details.