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.
- Author
- itechmeat ↗
- Repository
- llm-code ↗
- Licence
- MIT
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 4
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 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
- Quick Start
- When to Use
- Essential Commands
- Hash-Based IDs
- References
- Key Concepts
- Configuration
- Storage Backend (Dolt)
- Agent Integration
- Release Highlights (1.3.1)
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
| Repository | Score | Licence |
|---|---|---|
| This page · itechmeat/llm-code | 100 | MIT |
| gastownhall/beads | 100 | MIT |
| flurdy/agent-skills | 100 | MIT |
| jr2804/prompts | 100 | MIT |
| vinnie357/claude-skills | 100 | MIT |
| aspiers/ai-config | 100 | GPL-3.0 |
| gastownhall/beads | 95 | MIT |
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.