Todo System (Beads)

Beads (bd) is a Git-native todo system designed for AI agents. Your agent doesn’t just read issues — it creates them, tracks dependencies, and maintains the backlog as part of its work.

The agent’s responsibility

Unlike traditional issue trackers where humans manage the backlog, Beads is owned by your agent:

• Agent discovers work → creates issues
• Agent sees blockers → adds dependencies
• Agent finishes task → closes issue
• Agent notices patterns → updates the backlog

The memory bank holds context. Beads holds actionable work. Your agent maintains both.

Why Beads?

• Git-native — Issues live in your repo, sync with code
• Dependency-aware — Track what blocks what
• Agent-first — bd ready shows unblocked work
• Offline-first — Works without network
• Simple — SQLite database, JSONL export

Installation

Beads comes pre-installed in TinyFat containers. For local use:

# Download latest release
curl -sL https://github.com/steveyegge/beads/releases/latest/download/bd-linux-amd64 -o /usr/local/bin/bd
chmod +x /usr/local/bin/bd

Quick start

1. Initialize in your project

   cd your-project
   bd init

   This creates .beads/ with your database. Prefix auto-detects from directory name.

2. Create an issue

   bd create "Add user authentication"

   Output: ✓ Created issue: proj-a1b2

3. List issues

   bd list

4. See ready work

   bd ready

   Shows issues with no blockers — perfect for picking next task.

Core commands

Creating issues

# Basic
bd create "Fix login bug"

# With priority (0=highest, 4=lowest)
bd create "Critical security fix" -p 0

# With type
bd create "Add OAuth support" -t feature

# With description
bd create "Refactor auth" -d "Split into smaller modules"

# With assignee
bd create "Write tests" --assignee alice

Viewing issues

# List all
bd list

# Filter by status
bd list --status open
bd list --status in_progress
bd list --status closed

# Filter by priority
bd list --priority 0

# Show specific issue
bd show proj-a1b2

Updating issues

# Change status
bd update proj-a1b2 --status in_progress

# Change priority
bd update proj-a1b2 --priority 1

# Assign
bd update proj-a1b2 --assignee bob

Closing issues

# Simple close
bd close proj-a1b2

# With reason
bd close proj-a1b2 --reason "Fixed in commit abc123"

# Multiple issues
bd close proj-a1b2 proj-c3d4

Dependencies

The killer feature. Track what blocks what.

Adding dependencies

# proj-b blocks proj-a (must finish b before a)
bd dep add proj-a proj-b

Viewing dependencies

# Show dependency tree
bd dep tree proj-a

# Find circular dependencies
bd dep cycles

# Show blocked issues
bd blocked

Dependency types

Type	Meaning
blocks	Must complete before dependent
related	Soft connection, doesn’t block
parent-child	Epic/subtask hierarchy

Ready work

bd ready is designed for agents picking up work:

bd ready

Shows issues that are:

• Status: open or in_progress
• No blocking dependencies
• Ready to work on right now

Tip

Teach your agent to run bd ready when starting work. It shows exactly what can be done next.

Issue prefixes

Each project has a unique prefix:

# Auto-detect from directory name
bd init
# myproject/ → myproject-a1b2

# Custom prefix
bd init --prefix api
# → api-a1b2

Prefixes use hash-based IDs (like a1b2) for uniqueness across repos.

Git integration

Beads syncs automatically with Git:

1. After changes — Exports to .beads/issues.jsonl
2. After git pull — Imports if JSONL is newer
3. No manual sync — Just commit and push

The .beads/ directory should be committed:

git add .beads/
git commit -m "Add beads issue tracking"

Agent workflow

For AI agents, Beads enables a structured workflow:

1. Check ready work

   bd ready

2. Claim an issue

   bd update proj-a1b2 --status in_progress

3. Do the work

4. Close when done

   bd close proj-a1b2 --reason "Implemented in this session"

5. Create discovered work

   If you find new issues while working:

   bd create "Found: need to handle edge case X" -t bug

Epics and subtasks

Group related issues:

# Create epic
bd create "User authentication system" -t epic

# Create subtasks with parent
bd create "Login form" --parent proj-epic1
bd create "Password reset" --parent proj-epic1
bd create "OAuth integration" --parent proj-epic1

# View epic with children
bd show proj-epic1

Comments

Add notes to issues:

# Add comment
bd comment proj-a1b2 "Started working on this, found complexity in X"

# View comments
bd comments proj-a1b2

Database location

Beads auto-discovers the database:

1. --db /path/to/db flag
2. $BEADS_DB environment variable
3. .beads/*.db in current or parent directories
4. ~/.beads/default.db fallback

Pairing with Memory Bank

Beads tracks issues. Memory Bank tracks context. Use both:

memory-bank/02-active/nextUp.md  → High-level priorities
.beads/                          → Specific actionable issues

Reference beads in memory bank:

## Next Up

Priority work from `bd ready`:
- proj-a1b2: Fix authentication timeout
- proj-c3d4: Add rate limiting

Command reference

Command	Description
bd init	Initialize in current directory
bd create	Create new issue
bd list	List issues
bd show	Show issue details
bd update	Update issue fields
bd close	Close issue(s)
bd ready	Show unblocked issues
bd blocked	Show blocked issues
bd dep add	Add dependency
bd dep tree	Show dependency tree
bd comment	Add comment
bd stats	Show statistics

Use bd --help or bd <command> --help for full options.

Next steps

• Memory Bank Pattern — Project context structure
• Agent Workspace — Your agent’s filesystem