Skip to main content

Core Concepts

Understanding the fundamental concepts behind beads.

Design Philosophy​

Beads was built with these principles:

  1. Git as source of truth - Issues sync via JSONL files, enabling collaboration across branches
  2. AI-native workflows - Hash-based IDs, JSON output, dependency-aware execution
  3. Local-first operation - SQLite database for fast queries, background sync
  4. Declarative workflows - Formulas define repeatable patterns

Key Components​

Issues​

Work items with:

  • ID - Hash-based (e.g., bd-a1b2) or hierarchical (e.g., bd-a1b2.1)
  • Type - bug, feature, task, epic, chore
  • Priority - 0 (critical) to 4 (backlog)
  • Status - open, in_progress, closed
  • Labels - Flexible tagging
  • Dependencies - Blocking relationships

Dependencies​

Four types of relationships:

TypeDescriptionAffects Ready Queue
blocksHard dependency (X blocks Y)Yes
parent-childEpic/subtask relationshipNo
discovered-fromTrack issues found during workNo
relatedSoft relationshipNo

Daemon​

Background process per workspace:

  • Auto-starts on first command
  • Handles auto-sync with 5s debounce
  • Socket at .beads/bd.sock
  • Manage with bd daemons commands

JSONL Sync​

The synchronization mechanism:

SQLite DB (.beads/beads.db)
    ↕ auto-sync
JSONL (.beads/issues.jsonl)
    ↕ git
Remote repository

Formulas​

Declarative workflow templates:

  • Define steps with dependencies
  • Variable substitution
  • Gates for async coordination
  • Aspect-oriented transformations