beads

```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

```

• 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

| Command | Action |

| ----------------------------- | ------------------------------------- |

| 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 | View task details and audit trail |

| bd update --status=X | Update status (open/in_progress/done) |

| bd close | Close task |

| bd dep add | Link tasks (blocks, related, parent) |

| bd list | List issues (default: 50, non-closed) |

| bd sync | Sync with git/remote |

| bd kv set | Store key-value pair |

| bd kv get | Retrieve stored value |

| bd backend | Show/configure storage backend |

| bd gitlab sync | Sync with GitLab |

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 to view hierarchy.

| File | Purpose |

| --------------------------------------- | ----------------------------------------- |

| [workflow.md](references/workflow.md) | Daily operations, status flow, sync |

| [authoring.md](references/authoring.md) | Writing quality issues, EARS patterns |

| [molecules.md](references/molecules.md) | Molecules, gates, formulas, compounds |

| [sync.md](references/sync.md) | Git sync, sync-branch, Linear/Jira import |

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

```

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]

```

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.

Tell Agent About Beads

Add to AGENTS.md:

```markdown

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.

```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

```

| ❌ Wrong | ✅ Correct |

| --------------------- | --------------------------- |

| priority: high | -p 1 (P0-P4 numeric) |

| Manual JSON editing | Use bd commands |

| Ignoring bd ready | Always check blockers first |

| Skipping bd sync | Sync regularly |

| Creating without deps | Declare --blocks upfront |

• [Releases](https://github.com/steveyegge/beads/releases)
• [Documentation](https://github.com/steveyegge/beads#readme)
• [Community Tools](https://github.com/steveyegge/beads/blob/main/docs/COMMUNITY_TOOLS.md)