Beads

Steve Yegge open source project to give a task-graph to-do list for AI agents to use coordinate with.

https://github.com/steveyegge/beads

docs https://beads.gascity.com/

Architecture: This document describes bd's overall architecture - the data model, sync mechanism, and how components fit together.

• nodes are called issue
• includes field types and value-enum (issue types, priority, status...)
  • even has assignee, 3 different timestamps, etc.
• dependencies
  • blocking types
    • blocks (default) B cannot start until A closes -Task ordering
    • parent-child Children blocked when parent blocked (but parent isn't blocked by children (in my mind closing a parent is blocked by unclosed children, but that's a different thing) - Epic hierarchies
  • Workflow steps add two more blocking types - see Molecules
    • conditional-blocks B runs only if A fails - Error handling paths
    • waits-for B waits for all of A’s children - Fanout aggregation (if A blocks B, then isn't this assumed?)
  • non-blocking types (graph annotations only):
    • related Informational link
    • tracks Tracks progress of another issue
    • discovered-from Found during work on another issue
    • caused-by Root cause link
    • validates Test or verification link
    • supersedes Replaced by a different issue (bd supersede old --with new)
  • there can be multiple dependencies between 2 tasks? Or not?
    • I see bd dep remove issue-2 issue-1 which doesn't include a specific dep-type
    • maybe only 1 blocking-type dependency, and multiple non-blocking?
    • I see bd dep unrelate <id1> <id2> - Removes link in both directions
  • there are also other types of links between issues to create a knowledge graph - esp between non-task nodes: messages, etc. replies-to threads, relates-to, duplicates, and supersedes (replacement)
  • see table comparing graph-links to dependencies
  • dolt table dependencies fields: issue_id, depends_on_id, type; unique! PRIMARY KEY (issue_id, depends_on_id)

Molecules: Work Graphs in Beads: This doc explains how beads structures and executes work. Start here if you're building workflows.

• dependency types, etc.

Formulas: Writing declarative TOML or JSON workflow templates with steps, variables, dependencies, gates, and aspects, then cooking them into protos.

Migrated from Sqlite to Dolt (for local cache).

• tables: issues, routes, interactions, labels, dependencies?

Claude Code Integration Design: *This document explains design decisions for Claude Code integration in beads.

• CLI + Hooks Over MCP
• does not use Claude skills

FAQ:

• bd is a lightweight, git-based issue tracker designed for AI coding agents. It provides dependency-aware task management with automatic sync across machines via git.
• Why not just use GitHub Issues?
• How is this different from Taskwarrior?
• *Can I use bd without AI agents?
  Absolutely! bd is a great CLI issue tracker for humans too. The bd ready command is useful for anyone managing dependencies. Think of it as "Taskwarrior meets git."

TUI viewer (and orchestration layer?) by Jeffrey Emmanuel https://github.com/Dicklesworthstone/beads_viewer

• Yegge: This is the first UI for Beads that I could see myself using. Pretty clever. And it's a Terminal UI!

Bridge Jira and beads: Import Jira issues locally, work with git-backed issue tracking, sync changes back to Jira: jira-beads-sync synchronizes Jira issues with beads, a git-backed issue tracker. Work with Jira issues as YAML files in your repository, manage them with beads commands or Claude Code, then sync your changes back to Jira.

Oct15'2025: Yegge: beads revolution

• issues here have IDs like vc-15 - is vc a repo-specific prefix for uniqueness?
  • hash-based with adaptive-length - large-database uses id like bd-7f3a86 (IDs are generated from: Issue title; Creation timestamp; Random salt)
  • prefix: My project prefixes so far are bd-, vc-, wy-, ef-, and gt-. It just makes the whole world more readable if you cut down on your issue tracker ID sizes by using short prefixes.

Jan20'2026: Koustubh: Building Apps with AI: Deep Dive into beads Workflow.

• Every beads issue is stored as a single line of JSON in .beads/issues.jsonl:

{
  "id": "mission-house-ogp",
  "title": "Implement myschool.edu.au scraper",
  "description": "Create Puppeteer-based scraper...",
  "status": "closed",
  "priority": 1,
  "close_reason": "NAPLAN scraper implemented in server.js",
  "dependencies": [{ "depends_on_id": "mission-house-5mv" }]
}

• another example:

    {
      "depends_on_id": "mission-house-utk",
      "type": "blocks"
    }

• We organized Mission House using a three-level hierarchy: Epics → Features → Tasks
• I see issue_type can be 'bug' or 'task' - any others? Is that part of Beads, or this author's project

Koustubh part2

• file org

.beads/
├── issues.jsonl    # All issues in ONE compact file
├── config.yaml     # Project configuration
└── db.sqlite       # Local cache for fast queries