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

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.
• Molecules are template work items that define structured workflows. When spawned, they create wisps - ephemeral child issues that track execution steps. - wisps are local, not added to issues.jsonl

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

• dependency types, etc.

Migrating 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?

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