Simple task tracking for LLM sessions - ownership-based workflow for multi-agent coordination
- version
- 0.2.1
- GitHub stars
- 11
Install
/plugin install ba@baRun it inside Claude Code after adding the marketplace with /plugin marketplace add open-horizon-labs/ba.
Contents
Discovered from sourceCommands 4
Initialize ba
Initialize ba task tracking for this project.
Step 1: Check current state
- Check if
.ba/already exists - if so, tell user it's already initialized and show status - Check if
babinary is available (command -v ba) - if yes, skip to Step 3
Step 2: Install ba binary
Detect available package managers:
- Homebrew:
command -v brew - Cargo:
command -v cargoORtest -f ~/.cargo/bin/cargo
Offer installation based on what's available:
If Homebrew available (preferred for macOS):
brew install cloud-atlas-ai/ba/ba
If Cargo available:
cargo install ba
# or if cargo not in PATH:
~/.cargo/bin/cargo install ba
If neither available, offer to install a package manager:
-
Install Homebrew (recommended for macOS):
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Then:
brew install cloud-atlas-ai/ba/ba -
Install Rust (cross-platform):
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shThen restart shell and:
cargo install ba
For local development (if user specifies a path):
cargo install --path /path/to/ba
# or: ~/.cargo/bin/cargo install --path /path/to/ba
Step 3: Initialize project
After ba binary is available, run:
ba init
This creates .ba/ directory with:
config.json- Project config (version, ID prefix)issues.jsonl- Issue storage
Step 4: Update AGENTS.md
Check if AGENTS.md exists in the project root. If not, create it with:
# AGENTS.md
This file provides guidance to Claude Code when working with code in this repository.
## Project Overview
[Add project-specific overview here]
## ba Task Tracking
This project uses ba for task tracking. You have the `$ba` skill available in Codex mode.
**Core workflow:**
1. Check ready queue: `ba ready` - shows open, unblocked issues
2. Claim an issue: `ba claim <id> --session $SESSION_ID`
3. Work on the issue
4. Complete: `ba finish <id>`
5. Or release: `ba release <id>` if not done
**Quick reference:**
- `ba list` - Show all open issues (excludes closed)
- `ba list --all` - Include closed issues
- `ba show <id>` - Show issue details
- `ba mine --session $SESSION_ID` - Show your claimed issues
- `ba create "title" -t task -p 1` - Create new issue
- `ba comment <id> "message"` - Add comment
**Ownership-based state machine:**
- `open` → claim → `in_progress` (you own it)
- `in_progress` → finish → `closed`
- `in_progress` → release → `open` (back to pool)
- Claiming a closed issue reopens it automatically
**Issue types:** task, epic, refactor, spike
**Priorities:** 0 (critical) to 4 (backlog), default 2
See README.md for full details.
If AGENTS.md already exists, append the ba section:
# Quoted heredoc prevents $SESSION_ID expansion in AGENTS.md
cat >> AGENTS.md << 'EOF'
## ba Task Tracking
This project uses ba for task tracking. You have the `$ba` skill available in Codex mode.
**Core workflow:**
1. Check ready queue: `ba ready` - shows open, unblocked issues
2. Claim an issue: `ba claim <id> --session $SESSION_ID`
3. Work on the issue
4. Complete: `ba finish <id>`
5. Or release: `ba release <id>` if not done
**Quick reference:**
- `ba list` - Show all open issues (excludes closed)
- `ba list --all` - Include closed issues
- `ba show <id>` - Show issue details
- `ba mine --session $SESSION_ID` - Show your claimed issues
- `ba create "title" -t task -p 1` - Create new issue
- `ba comment <id> "message"` - Add comment
**Ownership-based state machine:**
- `open` → claim → `in_progress` (you own it)
- `in_progress` → finish → `closed`
- `in_progress` → release → `open` (back to pool)
- Claiming a closed issue reopens it automatically
**Issue types:** task, epic, refactor, spike
**Priorities:** 0 (critical) to 4 (backlog), default 2
See README.md for full details.
EOF
Step 5: Install Codex skill
Install the $ba Codex skill files to enable ba commands in Claude Code sessions:
# Create skill directory
SKILL_DIR="$HOME/.codex/skills/ba"
mkdir -p "$SKILL_DIR"
echo "Installing ba Codex skill..."
if curl -fsSL -o "$SKILL_DIR/SKILL.md" \
"https://raw.githubusercontent.com/cloud-atlas-ai/ba/master/codex-skill/SKILL.md" && \
curl -fsSL -o "$SKILL_DIR/AGENTS.md.snippet" \
"https://raw.githubusercontent.com/cloud-atlas-ai/ba/master/codex-skill/AGENTS.md.snippet"; then
echo "✓ Codex skill installed to $SKILL_DIR"
echo ""
echo "The \$ba skill is now available for:"
echo " \$ba ready - Show available issues"
echo " \$ba claim - Claim an issue"
echo " \$ba mine - Show your claimed issues"
echo " \$ba finish - Complete an issue"
else
echo "⚠️ Failed to download Codex skill files"
echo "You can manually install from: https://github.com/cloud-atlas-ai/ba/tree/master/codex-skill"
fi
Step 6: Verify SESSION_ID
Check if SESSION_ID is available for ownership operations:
if [ -z "$SESSION_ID" ]; then
echo ""
echo "⚠️ SESSION_ID not set"
echo "Claude Code provides this automatically in active sessions."
echo "To set manually: export SESSION_ID=\$(uuidgen | tr '[:upper:]' '[:lower:]')"
else
echo ""
echo "✓ SESSION_ID is set: $SESSION_ID"
fi
Step 7: Confirm
Tell user:
✓ ba initialized and ready
Created .ba/ directory with project config
Installed $ba Codex skill to ~/.codex/skills/ba/
Added ba guidance to AGENTS.md
Quick start:
ba create "Your first task" -t task
ba list
ba claim <id> --session $SESSION_ID
Use $ba commands in Codex mode:
$ba ready, $ba claim <id>, $ba finish <id>
Be concise. Detect what's available, offer appropriate options, guide user through setup.
ba New
Guided task creation with proper scoping and specification.
Goal
Help users create well-specified, actionable ba tasks. Guide them from a rough idea to one or more properly scoped tasks.
Step 1: Get initial input
Ask the user what they want to accomplish:
What do you want to accomplish? Describe the task or goal in a few words.
If user provides something vague like "fix the thing" or "improve performance", probe for specifics:
- What specifically is broken or needs improvement?
- What behavior should change?
- What does success look like?
Step 2: Check for duplicates
Before creating, search existing tasks for similar work:
ba list --all --json | jq -r '.[] | "\(.id): \(.title) (\(.status))"'
Look for tasks with:
- Similar keywords in the title
- Related subject matter
- Same general area of the codebase
If a potential duplicate is found:
I found an existing task that might be related:
<id>: <title> (<status>)
Is this the same work, or something different?
If same work:
- If closed: Ask if user wants to reopen it
- If open/in_progress: Point them to it, no new task needed
If different work: Proceed with creation. Consider adding a comment mentioning the related task ID for context.
Step 3: Assess scope
Evaluate if the task is properly scoped. A well-scoped task:
- Can be completed in a single focused session
- Has clear acceptance criteria
- Doesn't require breaking into subtasks
Signs of oversized scope:
- Multiple unrelated changes
- "And also..." in the description
- Would touch many different areas of code
- Contains multiple acceptance criteria that could stand alone
If scope is too large:
Suggest breaking down into smaller tasks:
This sounds like it could be multiple tasks. I see:
1. [First discrete piece of work]
2. [Second discrete piece of work]
3. [Third discrete piece of work]
Should I create these as separate tasks? They can be linked as dependencies if needed.
Step 4: Refine the title
Help craft an actionable title. Good titles:
- Start with a verb (Add, Fix, Update, Remove, Implement, Refactor)
- Are specific enough to understand without context
- Fit in ~10 words
Transform vague titles:
- "auth stuff" → "Add JWT token refresh on expiration"
- "fix bug" → "Fix login redirect loop when session expires"
- "improve perf" → "Add caching to database queries in search endpoint"
Propose a refined title and confirm:
How about: "[refined title]"
Does this capture what you want to do?
Step 5: Determine type
Based on the work described, recommend a type:
- task - Building something new or changing behavior
- refactor - Improving code without changing behavior
- spike - Research or investigation, time-boxed exploration
- epic - Container for related tasks (only if creating multiple)
This sounds like a [type]. [Brief explanation of why]
Step 6: Add context (optional)
For non-trivial tasks, ask if there's additional context:
Any additional context to capture? For example:
- Acceptance criteria (what does "done" look like?)
- Technical constraints or approaches to consider
- Related files or areas of code
If user provides context, it becomes a comment on the created task.
Step 7: Set priority
Offer priority options:
Priority?
- 0: Critical - drop everything
- 1: High - do soon
- 2: Medium - normal queue (default)
- 3: Low - when you get to it
- 4: Backlog - someday/maybe
Default to P2 if user doesn't specify.
Step 8: Handle dependencies (if multiple tasks)
If creating multiple tasks, ask about dependencies:
Should any of these tasks block others?
For example: Task 2 depends on Task 1 being done first.
Step 9: Create task(s)
Execute the creation:
# Single task
ba create "Title here" -t task -p 2
# With comment for context
ba create "Title here" -t task -p 2
ba comment <id> "Additional context here"
# Multiple tasks with dependencies
ba create "First task" -t task -p 2
ba create "Second task (depends on first)" -t task -p 2
ba block <second-id> <first-id>
Step 10: Confirm
Show what was created:
Created:
<id>: Title (type, priority)
Ready to claim with:
ba claim <id> --session $SESSION
Or for multiple tasks:
Created 3 tasks:
<id1>: First task (task, P2) - ready
<id2>: Second task (task, P2) - blocked by <id1>
<id3>: Third task (task, P2) - blocked by <id2>
Task tree:
<id1> → <id2> → <id3>
Start with:
ba claim <id1> --session $SESSION
Quick mode
If user provides a clear, well-specified task upfront, skip the refinement:
User: Create a task to add input validation to the signup form that rejects emails without @ symbol
This is already:
- Actionable (add validation)
- Specific (signup form, email field, @ symbol check)
- Properly scoped (single focused change)
Just confirm type and priority, then create.
Examples
Example 1: Vague input
User: I need to fix auth
Claude: What specifically is broken with authentication?
- Login not working?
- Token expiration issues?
- Permission checks failing?
User: Oh, the JWT tokens expire and users get logged out
Claude: Got it. How about: "Add JWT token refresh before expiration"
This is a task (adding new behavior). Priority?
User: High, it's annoying users
Claude: Created:
ab-x7k2: Add JWT token refresh before expiration (task, P1)
Ready to claim: ba claim ab-x7k2 --session $SESSION
Example 2: Oversized scope
User: I want to add a dashboard
Claude: A dashboard could be quite broad. What should it show?
User: User stats, recent activity, and admin controls
Claude: This sounds like 3 separate pieces:
1. "Add user statistics panel to dashboard"
2. "Add recent activity feed to dashboard"
3. "Add admin control panel to dashboard"
Should I create these as separate tasks? They can work independently.
User: Yes, and admin controls need the stats first
Claude: Created 3 tasks:
ab-y1a2: Add user statistics panel to dashboard (task, P2) - ready
ab-z3b4: Add recent activity feed to dashboard (task, P2) - ready
ab-c5d6: Add admin control panel to dashboard (task, P2) - blocked by ab-y1a2
Start with either ab-y1a2 or ab-z3b4 (both ready).
Example 3: Quick create
User: Task to update the README with new installation instructions for ARM64
Claude: Clear and specific. Creating:
"Update README with ARM64 installation instructions" (task, P2)
ab-m7n8 created. Ready to claim.
Keep the conversation natural. Don't be overly formal or robotic. The goal is helping users think through their tasks, not running them through a rigid form.
ba Quick Start
Show a quick start guide for using ba in this session.
Display Guide
Show this concise reference:
ba - Task Tracking Quick Start
==============================
Core Workflow:
ba ready # See available work
ba claim <id> --session $SESSION_ID # Take ownership
ba show <id> # Check details
ba finish <id> # Complete work
ba release <id> # Abandon work
Browse:
ba list # All open issues
ba list --all # Include closed
ba mine --session $SESSION_ID # Your claimed issues
Create:
ba create "title" -t task -p 1 # New issue
ba comment <id> "msg" --author $SESSION_ID
Dependencies:
ba block <id> <blocker-id> # Mark as blocked
ba tree <id> # Visualize deps
Ownership State Machine:
open → claim → in_progress → finish → closed
↓
release
↓
open
Issue Types:
task - General work (default)
epic - Grouping container
refactor - Improve existing code
spike - Research/investigation
Priorities:
0 - Critical 1 - High 2 - Medium (default)
3 - Low 4 - Backlog
Session ID:
Use --session $SESSION_ID for claim/mine/comment
This identifies you in multi-agent workflows
Storage:
.ba/issues.jsonl - One issue per line (git-friendly)
.ba/config.json - Project configuration
More info: ba --help or README.md
Check if initialized
If .ba/ doesn't exist, suggest:
ba not initialized yet. Run:
/ba init
Keep it concise. This is a reference card, not a tutorial.
ba Status
Show current ba status for this project.
Check if initialized
First, check if ba is initialized:
if [ -d .ba ]; then
echo "✓ ba is initialized"
else
echo "✗ ba not initialized - run /ba init"
exit 0
fi
Show configuration
cat .ba/config.json
Displays:
- Version
- ID prefix (derived from project path)
Show issue counts
echo "Issue counts:"
ba list --json | jq '. | length' | xargs -I {} echo " Open: {}"
ba list --all --json | jq '[.[] | select(.status == "closed")] | length' | xargs -I {} echo " Closed: {}"
ba list --all --json | jq '[.[] | select(.status == "in_progress")] | length' | xargs -I {} echo " In Progress: {}"
Show ready queue
echo ""
echo "Ready to work:"
ba ready
Check your claimed issues
If $SESSION_ID is available:
echo ""
echo "Your claimed issues:"
ba mine --session "$SESSION_ID"
Summary format
Present information concisely:
✓ ba initialized
Project: ab (prefix)
Version: 2
Issues:
Open: 12
In Progress: 3
Closed: 45
Ready to work: 8 issues
Your claimed: 2 issues
ab-x7k2 (P1): Fix auth bug
ab-y8m3 (P2): Add dashboard
Be concise. Show what matters. If not initialized, suggest /ba init.
Sponsors
Details
- Marketplace
- open-horizon-labs/ba
- Source
- plugin
- Author
- Cloud Atlas AI
- Category
- Community
