beads

Original：🇺🇸 English
Translated
1 scriptsChecked / no sensitive code detected

Beads (bd) distributed git-backed issue tracker for AI agents: hash-based IDs, dependency graphs, worktrees, molecules, sync, GitLab/Linear/Jira. Keywords: bd, beads, issue tracker, git-backed, dependencies, molecules, worktree, sync, AI agents.

2installs
Sourceitechmeat/llm-code
Added on

NPX Install

npx skill4agent add itechmeat/llm-code beads

Tags

Translated version includes tags in frontmatter
git-backed-issue-trackerai-agent-task-managementdependency-graph-trackingcross-tool-syncdolt-storage

SKILL.md Content

View Translation Comparison →

Beads (bd)

Distributed, git-backed graph issue tracker for AI coding agents. Persistent memory with dependency-aware task tracking.

Quick Start

bash
# Install
brew install steveyegge/beads/bd
# or
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Initialize in repo (humans run once)
bd init

# Tell your agent
echo "Use 'bd' for task tracking" >> AGENTS.md

When to Use

  • AI agent needs persistent task memory across sessions
  • Tracking dependencies between tasks (
    blocks:
    , 
    depends_on:
    )
  • Multi-agent/multi-branch workflows (hash-based IDs prevent conflicts)
  • Incremental delivery with molecules/gates
  • Sync issues with GitLab, Linear, Jira, GitHub

Essential Commands

CommandAction
bd ready
List tasks with no open blockers
bd ready --gated
Tasks waiting at gate checkpoints
bd create "Title" -p 0
Create P0 task
bd show <id>
View task details and audit trail
bd update <id> --status=X
Update status (open/in_progress/done)
bd close <id>
Close task
bd dep add <child> <parent>
Link tasks (blocks, related, parent)
bd list
List issues (default: 50, non-closed)
bd sync
Sync with git/remote
bd kv set <key> <value>
Store key-value pair
bd kv get <key>
Retrieve stored value
bd backend
Show/configure storage backend
bd gitlab sync
Sync with GitLab

Hash-Based IDs

Issues use hash-based IDs like 
bd-a1b2
to prevent merge conflicts:
bash
bd create "Fix login bug" -p 1
# Created: bd-x7k3

bd show bd-x7k3

Hierarchical IDs

bd-a3f8      (Epic)
bd-a3f8.1    (Task)
bd-a3f8.1.1  (Sub-task)
Use 
bd children <id>
to view hierarchy.

References

FilePurpose
workflow.mdDaily operations, status flow, sync
authoring.mdWriting quality issues, EARS patterns
molecules.mdMolecules, gates, formulas, compounds
sync.mdGit sync, sync-branch, Linear/Jira import

Key Concepts

Git as Database

Issues stored as JSONL in 
.beads/
. Versioned, branched, merged like code.

Dependency Graph

bash
bd dep add bd-child bd-parent --blocks   # child blocks parent
bd dep add bd-a bd-b --related           # related items
bd ready                                 # only shows unblocked work

Molecules (Advanced)

Molecules group related issues with gates for incremental delivery:
bash
bd mol create "Feature X" --steps=3      # Create 3-step molecule
bd mol progress bd-xyz                   # Check progress
bd mol burn bd-xyz                       # Complete molecule

Stealth Mode

Use Beads locally without committing to repo:
bash
bd init --stealth

Contributor vs Maintainer

bash
# Contributor (forked repos) — separate planning repo
bd init --contributor

# Maintainer auto-detected via SSH/HTTPS credentials

Configuration

Config stored in 
.beads/config.yaml
:
yaml
sync:
  branch: beads-sync # Sync to separate branch
  remote: origin
daemon:
  auto_start: true
  auto_sync: true
types:
  custom:
    - name: spike
      statuses: [open, in_progress, done]

Storage Backend (Dolt Default)

Beads now defaults to the embedded Dolt backend. Server mode is opt-in for multi-client access. Use 
bd backend
to inspect or configure backend settings, and see the sync reference for server-mode notes.

Agent Integration

Tell Agent About Beads

Add to 
AGENTS.md
:
markdown
## Task Tracking

Use `bd` for task tracking. Run `bd ready` to find work.

Agent-Optimized Output

bash
BD_AGENT_MODE=1 bd list --json  # Ultra-compact JSON output
bd list --json                   # Standard JSON output

MCP Plugin

Beads includes Claude Code MCP plugin for direct integration.

Critical Commands

bash
# What to work on
bd ready                    # Unblocked tasks
bd ready --pretty           # Formatted output

# Create with dependencies
bd create "Task B" --blocks bd-a1b2

# Doctor (fix issues)
bd doctor                   # Check health
bd doctor --fix             # Auto-fix problems

# Sync
bd sync                     # Full sync
bd sync --import-only       # Import only

Anti-patterns

❌ Wrong✅ Correct
priority: high
-p 1
(P0-P4 numeric)
Manual JSON editingUse 
bd
commands
Ignoring 
bd ready
Always check blockers first
Skipping 
bd sync
Sync regularly
Creating without depsDeclare 
--blocks
upfront

Links