Skip to content
Skills Library
Management & product · Tool integration

beads

/beads

Beads (bd) Dolt-backed issue tracker for agent task memory. Covers CLI ops, molecules, Dolt sync, Linear/Jira/GitLab. Use when tracking tasks and dependencies with the Beads CLI, syncing issues via Dolt, or integrating with Linear/Jira/GitLab. Keywords: bd, beads, Dolt, issue tracker.

Repository
llm-code ↗
Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
1
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/bd_generate_markdown_plan.py

What it does and when to use it

Beads (bd) Dolt-backed issue tracker for agent task memory. Covers CLI ops, molecules, Dolt sync, Linear/Jira/GitLab. Use when tracking tasks and dependencies with the Beads CLI, syncing issues via Dolt, or integrating with Linear/Jira/GitLab. Keywords: bd, beads, Dolt, issue tracker.

Original author description

Beads (bd) Dolt-backed issue tracker for agent task memory. Covers CLI ops, molecules, Dolt sync, Linear/Jira/GitLab. Use when tracking tasks and dependencies with the Beads CLI, syncing issues via Dolt, or integrating with Linear/Jira/GitLab. Keywords: bd, beads, Dolt, issue tracker.

How it works

  1. Quick Start
  2. When to Use
  3. Essential Commands
  4. Hash-Based IDs
  5. References
  6. Key Concepts
  7. Configuration
  8. Storage Backend (Dolt)
  9. Agent Integration
  10. Release Highlights (1.3.1)
Original SKILL.md headings · 291 lines, 2,022 words
SKILL.md preview
---
name: beads
description: "Beads (bd) Dolt-backed issue tracker for agent task memory. Covers CLI ops, molecules, Dolt sync, Linear/Jira/GitLab. Use when tracking tasks and dependencies with the Beads CLI, syncing issues via Dolt, or integrating with Linear/Jira/GitLab. Keywords: bd, beads, Dolt, issue tracker."
metadata:
  version: "1.3.1"
  release_date: "2026-09-30"
---

# Beads (bd)

Distributed, Dolt-backed (Git-like) graph issue tracker for AI coding agents. Persistent memory with dependency-aware task tracking.

## Quick Start

Install: `brew install beads` or use the install scripts/binaries from the [GitHub repo](https://github.com/gastownhall/beads).

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

| Command                       | Action                                    |
| ----------------------------- | ----------------------------------------- |
| `bd ready`                    | List tasks with no open blockers          |
| `bd ready --explain`          | Explain why tasks are or are not ready    |
| `bd ready --gated`            | Tasks waiting at gate checkpoints         |
| `bd ready --exclude-type=X`   | Exclude specific issue types              |
| `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 close <id> --claim-next`  | Close current task and claim next         |
| `bd dep add <child> <parent>` | Link tasks (blocks, related, parent)      |
| `bd list`                     | List issues (default: 50, non-closed)     |
| `bd list --format json`       | JSON output (alias for `--json`)          |
| `bd list --include-ephemeral` | Include ephemeral rows (v1.3.1)           |
| `bd show --current`           | Show active issue (no ID needed)          |
| `bd update <id> --claim`      | Atomically claim issue for work           |
| `bd heartbeat <id>`           | Extend a claim's lease (v1.3.0)           |
| `bd reclaim --older-than=10m` | Revert expired leases to ready (v1.3.0)   |
| `bd unclaim <id>`             | Give a claim back (v1.3.0)                |
| `bd update <id> --if-status=S`| CAS update: apply only if status matches  |
| `bd note <id> "text"`         | Append note (shorthand)                   |
| `bd import -i <file>`         | Import JSONL incrementally                |
| `bd sync`                     | Pull, settle conflicts, recompute, push   |
| `bd events`                   | Read the durable events journal (v1.3.0)  |
| `bd serve`                    | Serve the HTTP API (v1.3.0)               |
| `bd dolt pull`                | Pull latest DB changes (advanced)         |
| `bd dolt push`                | Push DB changes (advanced)                |
| `bd bootstrap`                | Repair/bootstrap workspace identity       |
| `bd context`                  | Show current workspace/task context       |
| `bd kv set <key> <value>`     | Store key-value pair                      |
| `bd kv get <key>`             | Retrieve stored value                     |
| `bd dolt show`                | Show Dolt connection/remote settings      |
| `bd config set-many`          | Apply multiple config changes in one step |
| `bd ado sync`                 | Sync with Azure DevOps work items         |
| `bd ado status`               | Check Azure DevOps sync status            |
| `bd ado projects`             | List Azure DevOps projects                |
| `bd gitlab sync`              | Sync with GitLab                          |
| `bd github sync`              | Sync with GitHub Issues                   |
| `bd remember`                 | Write persistent agent memory             |
| `bd recall`                   | Read persistent agent memory              |
| `bd types`                    | List issue types + system types (v1.3.1)  |
| `bd backup init`              | Register a Dolt-native backup (v1.3.1)    |
| `bd backup sync`              | Write a new backup snapshot (v1.3.1)      |
| `bd backup remove`            | Remove a registered backup (v1.3.1)       |
| `bd backup status`            | Show backups and auto mode (v1.3.1)       |
| `bd backup restore`           | Restore the DB from a backup (v1.3.1)     |
| `bd purge`                    | Delete closed ephemeral beads (wisps)     |
| `bd purge --wisps-plane`      | Purge the closed wisps plane (v1.3.1)     |
| `bd purge --limit N`          | Cap one purge run at N beads (v1.3.1)     |

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

| 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)           | Dolt sync, upgrades, and integrations |
| [backup.md](references/backup.md)       | Backups, auto-backup, restore         |

## Key Concepts

### Dolt as Database

Beads stores issues in a Dolt database. Team synchronization happens via Dolt-style
`pull`/`push`, not by committing JSONL files into your repo history.

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

The exact schema evolves between releases. Prefer using CLI helpers to inspect
and validate your current setup:

- `bd dolt show` to see current Dolt connection/remote settings
- `bd dolt test` to validate connectivity
- `bd doctor` / `bd doctor --deep` for health checks

## Storage Backend (Dolt)

Beads uses Dolt as its primary backend. Depending on your setup, Dolt can run:

- Embedded (single-writer, no daemon)
- Server mode (multi-writer)
- Proxied server (bd runs and owns the Dolt server process itself — backup rules differ here, see [backup.md](references/backup.md))

Use `bd doctor` (and `bd doctor --server` when applicable) to validate your
environment. For legacy stores, use `bd migrate` workflows.

## 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.

## Release Highlights (1.3.1)

- **Backup family on proxied-server workspaces**: `bd backup init|sync|remove|status|restore` now works where bd runs the Dolt server itself. `bd backup restore` stops the proxy and its Dolt child before replacing the database, so the next command relaunches against the restored data. External host, socket and team-server databases are still refused with code `proxy.backup.unsupported` and `"reason": "design"` — see [backup.md](references/backup.md).
- **Opt-in auto-backup**: with `backup.enabled=true` (or `BD_BACKUP_ENABLED=1`) the post-command hook takes the same change-detected Dolt-native backup into `.beads/backup` that it takes in direct mode. It is off by default, and it does nothing on an external or team-server topology, under strict `--readonly`, under `bd serve`, with `--dry-run`/`--inspect`, or during a migration freeze. A per-workspace `.beads/backup.lock` keeps auto-backup and `bd backup sync` from running at the same time.
- **Purge flags**: `bd purge --wisps-plane` selects every closed row in the wisps table (including `--no-history` beads) on embedded, server and proxied workspaces and requires `--older-than` or `--pattern`. `--limit N` caps one run at N beads, oldest-closed first; with `--json` the output then adds `remaining` and `has_more` to loop on. `--older-than` accepts hour-precision durations (`36h`, `168h`, `90m`, down to `1s`) and refuses an unrepresentable value instead of wrapping it to a tiny age.
- **Ephemeral listing**: `bd list --include-ephemeral` is the flag `--wisp-type` needs to reach any rows — `bd list --include-ephemeral --wisp-type heartbeat`. It is off by default, so the default listing is unchanged.
- **System types**: `bd types` gains a "System types" section listing `message`, `molecule`, `gate` and `event`, and `bd types --json` gains an additive `system_types` field.

## Release Highlights (1.2.2)

- **Recovery release**: v1.2.0/v1.2.1 were published without release testing; v1.2.2 re-releases the tested 1.1 line under a higher version, so every install channel moves onto tested code. The 1.2.x-only features (work leases, events journal, sync federation, HTTP API server, provenance events) are **not** in this release — they return in a tested future release.
- **If you ran v1.2.1** and hit `schema version mismatch: database is at v65, binary knows up to v53`: roll the schema cursor back to v53 (see `docs/RECOVERY-1.2.1.md`), or use the `BD_IGNORE_SCHEMA_SKEW=1` stopgap — see `references/sync.md`. Upgrade every machine/clone to v1.2.2 **before** recovering, or a leftover 1.2.1 binary will silently re-migrate the database.

## Release Highlights (1.1.0)

- **Safer migrations**: schema-change detection so database migrations no longer apply silently, plus read-only enforcement across all layers.
- **Sync repair**: repair for previously problematic pull merges, and compaction now archives before discarding information.
- **New commands/flags**: `bd metrics` (with a consent notice) and idempotent `--init-if-missing` initialization.

## Release Highlights (1.0.3–1.0.4)

- **Workflow/config ergonomics**: `bd -C` changes working directory before running, `bd close` gains `--reason-file`, and setup/bootstrap flows gain better remote/server config handling.
- **Linear sync**: OAuth client-credentials, idempotency markers, stale-data signaling, per-workspace sync locks, richer type mappings, and batch create/update make larger sync loops safer and faster.
- **Security/export defaults**: Beads now refuses to write secret keys into git-tracked config, and exports exclude memories and ephemeral wisps by default unless you opt back in.
- **Dependencies/data paths**: JSONL bulk dependency add and several hook/bootstrap/init fixes reduce friction in automated and shared-server environments.

## Release Highlights (1.0.0–1.0.2)

- **Distribution**: precompiled binaries now cover Linux, macOS (Intel/Apple Silicon), Windows (AMD64/ARM64), Android/Termux, and FreeBSD.
- **Automation**: `bd init --non-interactive` / `--role` and `bd bootstrap --non-interactive` improve CI/cloud-agent setup.
- **Workflow**: `bd ready --explain`, `bd config set-many`, batch dependency listing, and comma-separated status filters improve agent ergonomics.
- **Authoring/modeling**: `spike`, `story`, and `milestone` are now first-class issue types; custom statuses/types moved to normalized tables.
- **Integrations/sync**: GitLab sync adds better dedup + epic→milestone mapping, ADO sync respects more filters, and embedded/shared-server recovery got safer.

## Release Highlights (0.62.0–0.63.3)

- **Azure DevOps integration**: `bd ado` CLI commands (sync, status, projects) for work item tracking.
- **Embedded Dolt support**: dep, duplicate, epic, graph, supersede, swarm operations work without a running Dolt server.
- **Custom status categories**: configure active/wip/done/frozen status groupings.
- **`bd note` command**: shorthand for appending notes to issues.
- **`--exclude-type` flag**: filter by issue type on `bd ready` and `bd list`.
- **`--format json` alias**: alternative to `--json` flag for consistency.
- **Audit log**: captures close reason; status changes logged to `interactions.jsonl`.
- **Memories in export/import**: round-trip includes agent memories.
- **Init defaults**: AGENTS.md defaults to minimal profile; `--agents-profile` flag added.
- **Quality/lifecycle commands**: surfaced in prime, template, and doctor.
- **Validation on close**: `--validate` checks `--acceptance` field; `validation.on-close` config.

## Release Highlights (0.61.0)

- `bd close --claim-next` shortens the common close-and-claim-next loop for agents.
- `bd create` gains `--skills`, `--context`, and `--no-history` for richer task creation and optional Dolt-history suppression.
- `bd import` adds incremental JSONL import for portability and recovery workflows.
- `bd init` / `bd bootstrap` can auto-detect the Beads database from the repository git origin.
- Dolt/server-mode sync improves credential pass-through, runtime port reporting, and health checks.
- Config and backup handling are safer, including proper project+user config merge and `BD_BACKUP_ENABLED=false` support.

## 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
bd create "Task C" --context "Need schema review" --skills "python,sql"

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

bd sync                     # Sync DB state
bd import -i backup.jsonl   # Incremental JSONL import

bd dolt pull                # Pull latest changes (advanced)
bd dolt push                # Push to remote (advanced)
```

## Anti-patterns

| ❌ 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 before/after work      |
| Creating without deps | Declare `--blocks` upfront  |

## Links

- [Releases](https://github.com/gastownhall/beads/releases)
- [Documentation](https://github.com/gastownhall/beads#readme)
- [Community Tools](https://github.com/gastownhall/beads/blob/main/docs/COMMUNITY_TOOLS.md)
Files in this package (7)
  • SKILL.md 15 KB
  • references/authoring.md 6 KB
  • references/backup.md 5 KB
  • references/molecules.md 3 KB
  • references/sync.md 8 KB
  • references/workflow.md 13 KB
  • scripts/bd_generate_markdown_plan.py 5 KB

Versions

RepositoryScoreLicence
This page · itechmeat/llm-code100MIT
gastownhall/beads100MIT
flurdy/agent-skills100MIT
jr2804/prompts100MIT
vinnie357/claude-skills100MIT
aspiers/ai-config100GPL-3.0
gastownhall/beads95MIT

Database snapshot: 13.11.2026 · package version db394d4d0621 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90working-with-beads
    Use when working with the beads CLI (`bd`) — issue/task tracking, dependencies, the full command surface (create, ready, dep, epic, gate, swarm, federation, dolt, worktree, compaction), `bd prime`, and the beads data model. Provides an offline CLI reference generated verbatim…
  • 100beads-solo
    Enforces Beads policy for a repository maintained initially by one owner, granting issue-management and commit authority while requiring explicit permission for Git pushes (other than to the user's own fork) and Dolt sync or push operations. Use when the user asks to enroll,…
  • 100flow-next-tracker-sync
    Project a flow-next spec to a tracker issue (Linear, GitHub, GitLab, Jira) and reconcile two-way. Use when asked to sync to a tracker. NOT plan-sync.
  • 100project-init
    Use when beads/Dolt database initialization fails, when bd commands return errors about missing databases, when setting up beads in a new project, or when recovering from diverged Dolt history. Handles fresh init, bootstrap from remote, and recovery workflows.
  • 90beads-jira-sync
    Syncs beads issues to the Jira DNA project with import-beads.js from the standalone beads-jira-import repo. Covers dry-run, state-file backup, live sync, initiative labels on epics, and bead/Jira key lookup. Use for the weekly beads to Jira sync, linking an epic to a DNA…
  • 100beads-workflow
    Convert markdown plans into beads with dependencies using br CLI. Use when creating task graphs, polishing beads before implementation, or bridging planning to agent swarm execution.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.