# Beads Documentation

## Docs

- [Dolt Backend for Beads](https://beads.gascity.com/architecture/dolt.md): How beads uses Dolt for versioned issue storage: embedded vs server mode, remotes, sync, and backups
- [Architecture Overview](https://beads.gascity.com/architecture/index.md): How Beads stores, queries, and syncs issue data with Dolt
- [Storage Backends](https://beads.gascity.com/architecture/storage-backends.md): Running bd on Dolt, Postgres, MySQL, or SQLite, and what version-control features each backend keeps
- [bd admin](https://beads.gascity.com/cli-reference/admin.md): Administrative commands for database maintenance
- [bd ado](https://beads.gascity.com/cli-reference/ado.md): Azure DevOps integration commands
- [bd assign](https://beads.gascity.com/cli-reference/assign.md): Assign an issue to someone
- [bd audit](https://beads.gascity.com/cli-reference/audit.md): Record and label agent interactions (append-only JSONL)
- [bd backup](https://beads.gascity.com/cli-reference/backup.md): Back up your beads database
- [bd batch](https://beads.gascity.com/cli-reference/batch.md): Run multiple write operations in a single database transaction
- [bd blocked](https://beads.gascity.com/cli-reference/blocked.md): Show blocked issues
- [bd bootstrap](https://beads.gascity.com/cli-reference/bootstrap.md): Non-destructive database setup for fresh clones and recovery
- [bd branch](https://beads.gascity.com/cli-reference/branch.md): List or create branches
- [bd children](https://beads.gascity.com/cli-reference/children.md): List child beads of a parent
- [bd close](https://beads.gascity.com/cli-reference/close.md): Close one or more issues
- [bd comment](https://beads.gascity.com/cli-reference/comment.md): Add a comment to an issue
- [bd comments](https://beads.gascity.com/cli-reference/comments.md): View or manage comments on an issue
- [bd compact](https://beads.gascity.com/cli-reference/compact.md): Squash old Dolt commits to reduce history size
- [bd completion](https://beads.gascity.com/cli-reference/completion.md): Generate the autocompletion script for the specified shell
- [bd config](https://beads.gascity.com/cli-reference/config.md): Manage configuration settings
- [bd context](https://beads.gascity.com/cli-reference/context.md): Show effective backend identity and repository context
- [bd cook](https://beads.gascity.com/cli-reference/cook.md): Compile a formula into a proto (ephemeral by default)
- [bd count](https://beads.gascity.com/cli-reference/count.md): Count issues matching filters
- [bd create](https://beads.gascity.com/cli-reference/create.md): Create a new issue (or batch from markdown/graph JSON)
- [bd create-form](https://beads.gascity.com/cli-reference/create-form.md): Create a new issue using an interactive form
- [bd defer](https://beads.gascity.com/cli-reference/defer.md): Defer one or more issues for later
- [bd delete](https://beads.gascity.com/cli-reference/delete.md): Delete one or more issues and clean up references
- [bd dep](https://beads.gascity.com/cli-reference/dep.md): Manage dependencies
- [bd diff](https://beads.gascity.com/cli-reference/diff.md): Show changes between two commits or branches
- [bd doctor](https://beads.gascity.com/cli-reference/doctor.md): Check and fix beads installation health (start here)
- [bd dolt](https://beads.gascity.com/cli-reference/dolt.md): Configure Dolt database settings
- [bd duplicate](https://beads.gascity.com/cli-reference/duplicate.md): Mark an issue as a duplicate of another
- [bd duplicates](https://beads.gascity.com/cli-reference/duplicates.md): Find and optionally merge duplicate issues
- [bd edit](https://beads.gascity.com/cli-reference/edit.md): Edit an issue field in $EDITOR
- [bd epic](https://beads.gascity.com/cli-reference/epic.md): Epic management commands
- [bd export](https://beads.gascity.com/cli-reference/export.md): Export issues to JSONL format
- [bd federation](https://beads.gascity.com/cli-reference/federation.md): Manage peer-to-peer federation (requires CGO)
- [bd find-duplicates](https://beads.gascity.com/cli-reference/find-duplicates.md): Find semantically similar issues using text analysis or AI
- [bd flatten](https://beads.gascity.com/cli-reference/flatten.md): Squash all Dolt history into a single commit
- [bd forget](https://beads.gascity.com/cli-reference/forget.md): Remove a persistent memory
- [bd formula](https://beads.gascity.com/cli-reference/formula.md): Manage workflow formulas
- [bd gate](https://beads.gascity.com/cli-reference/gate.md): Manage async coordination gates
- [bd gc](https://beads.gascity.com/cli-reference/gc.md): Garbage collect: decay old issues, compact Dolt commits, run Dolt GC
- [bd github](https://beads.gascity.com/cli-reference/github.md): GitHub integration commands
- [bd gitlab](https://beads.gascity.com/cli-reference/gitlab.md): GitLab integration commands
- [bd graph](https://beads.gascity.com/cli-reference/graph.md): Display issue dependency graph
- [bd heartbeat](https://beads.gascity.com/cli-reference/heartbeat.md): Refresh the lease on an issue you hold in_progress
- [bd history](https://beads.gascity.com/cli-reference/history.md): Show version history for an issue
- [bd hooks](https://beads.gascity.com/cli-reference/hooks.md): Manage git hooks for beads integration
- [bd human](https://beads.gascity.com/cli-reference/human.md): Show essential commands for human users
- [bd import](https://beads.gascity.com/cli-reference/import.md): Import issues from a JSONL file or stdin into the database
- [CLI Reference](https://beads.gascity.com/cli-reference/index.md): Generated reference for every bd command
- [bd info](https://beads.gascity.com/cli-reference/info.md): Show database information
- [bd init](https://beads.gascity.com/cli-reference/init.md): Initialize bd in the current directory
- [bd init-safety](https://beads.gascity.com/cli-reference/init-safety.md): Explain bd init flag semantics and the destroy-token format
- [bd jira](https://beads.gascity.com/cli-reference/jira.md): Jira integration commands
- [bd kv](https://beads.gascity.com/cli-reference/kv.md): Key-value store commands
- [bd label](https://beads.gascity.com/cli-reference/label.md): Manage issue labels
- [bd linear](https://beads.gascity.com/cli-reference/linear.md): Linear integration commands
- [bd link](https://beads.gascity.com/cli-reference/link.md): Link two issues with a dependency
- [bd lint](https://beads.gascity.com/cli-reference/lint.md): Check issues for missing template sections
- [bd list](https://beads.gascity.com/cli-reference/list.md): List issues
- [bd mail](https://beads.gascity.com/cli-reference/mail.md): Delegate to mail provider (e.g., gt mail)
- [bd memories](https://beads.gascity.com/cli-reference/memories.md): List or search persistent memories
- [bd merge-slot](https://beads.gascity.com/cli-reference/merge-slot.md): Manage merge-slot gates for serialized conflict resolution
- [bd metrics](https://beads.gascity.com/cli-reference/metrics.md): Show or change anonymous usage-metrics settings
- [bd migrate](https://beads.gascity.com/cli-reference/migrate.md): Database migration commands
- [bd migrate-personal](https://beads.gascity.com/cli-reference/migrate-personal.md): Move personal planning issues from the project database to your planning repo
- [bd mol](https://beads.gascity.com/cli-reference/mol.md): Molecule commands (work templates)
- [bd note](https://beads.gascity.com/cli-reference/note.md): Append a note to an issue
- [bd notion](https://beads.gascity.com/cli-reference/notion.md): Notion integration commands
- [bd onboard](https://beads.gascity.com/cli-reference/onboard.md): Display minimal snippet for agent instructions file
- [bd orphans](https://beads.gascity.com/cli-reference/orphans.md): Identify orphaned issues (referenced in commits but still open)
- [bd ping](https://beads.gascity.com/cli-reference/ping.md): Check database connectivity
- [bd preflight](https://beads.gascity.com/cli-reference/preflight.md): Show PR readiness checklist
- [bd prime](https://beads.gascity.com/cli-reference/prime.md): Output AI-optimized workflow context
- [bd priority](https://beads.gascity.com/cli-reference/priority.md): Set the priority of an issue
- [bd promote](https://beads.gascity.com/cli-reference/promote.md): Promote a wisp to a permanent bead
- [bd prune](https://beads.gascity.com/cli-reference/prune.md): Delete old closed beads to reclaim space and shrink exports
- [bd purge](https://beads.gascity.com/cli-reference/purge.md): Delete closed ephemeral beads to reclaim space
- [bd q](https://beads.gascity.com/cli-reference/q.md): Quick capture: create issue and output only ID
- [bd query](https://beads.gascity.com/cli-reference/query.md): Query issues using a simple query language
- [bd quickstart](https://beads.gascity.com/cli-reference/quickstart.md): Quick start guide for bd
- [bd ready](https://beads.gascity.com/cli-reference/ready.md): Show ready work (open, no active blockers)
- [bd recall](https://beads.gascity.com/cli-reference/recall.md): Retrieve a specific memory
- [bd reclaim](https://beads.gascity.com/cli-reference/reclaim.md): Revert stale-lease in_progress issues back to ready (dead-worker recovery)
- [bd recompute-blocked](https://beads.gascity.com/cli-reference/recompute-blocked.md): Recompute is_blocked for all issues (repairs stale flags after a pull)
- [bd remember](https://beads.gascity.com/cli-reference/remember.md): Store a persistent memory
- [bd rename](https://beads.gascity.com/cli-reference/rename.md): Rename an issue ID
- [bd rename-prefix](https://beads.gascity.com/cli-reference/rename-prefix.md): Rename the issue prefix for all issues in the database
- [bd reopen](https://beads.gascity.com/cli-reference/reopen.md): Reopen one or more closed issues
- [bd repo](https://beads.gascity.com/cli-reference/repo.md): Manage multiple repository configuration
- [bd restore](https://beads.gascity.com/cli-reference/restore.md): Restore the pre-compaction content of a compacted issue
- [bd rules](https://beads.gascity.com/cli-reference/rules.md): Audit and compact Claude rules
- [bd search](https://beads.gascity.com/cli-reference/search.md): Search issues by text query
- [bd set-state](https://beads.gascity.com/cli-reference/set-state.md): Set operational state (creates event + updates label)
- [bd setup](https://beads.gascity.com/cli-reference/setup.md): Setup integration with AI editors
- [bd ship](https://beads.gascity.com/cli-reference/ship.md): Publish a capability for cross-project dependencies
- [bd show](https://beads.gascity.com/cli-reference/show.md): Show issue details
- [bd sql](https://beads.gascity.com/cli-reference/sql.md): Execute raw SQL against the beads database
- [bd stale](https://beads.gascity.com/cli-reference/stale.md): Show stale issues (not updated recently)
- [bd state](https://beads.gascity.com/cli-reference/state.md): Query the current value of a state dimension
- [bd status](https://beads.gascity.com/cli-reference/status.md): Show issue database overview and statistics
- [bd statuses](https://beads.gascity.com/cli-reference/statuses.md): List valid issue statuses
- [bd supersede](https://beads.gascity.com/cli-reference/supersede.md): Mark an issue as superseded by a newer one
- [bd swarm](https://beads.gascity.com/cli-reference/swarm.md): Swarm management for structured epics
- [bd tag](https://beads.gascity.com/cli-reference/tag.md): Add a label to an issue
- [bd todo](https://beads.gascity.com/cli-reference/todo.md): Manage TODO items (convenience wrapper for task issues)
- [bd types](https://beads.gascity.com/cli-reference/types.md): List valid issue types
- [bd unclaim](https://beads.gascity.com/cli-reference/unclaim.md): Release a claimed issue
- [bd undefer](https://beads.gascity.com/cli-reference/undefer.md): Undefer one or more issues (restore to open)
- [bd update](https://beads.gascity.com/cli-reference/update.md): Update one or more issues
- [bd upgrade](https://beads.gascity.com/cli-reference/upgrade.md): Check and manage bd version upgrades
- [bd vc](https://beads.gascity.com/cli-reference/vc.md): Version control operations
- [bd version](https://beads.gascity.com/cli-reference/version.md): Print version information
- [bd where](https://beads.gascity.com/cli-reference/where.md): Show active beads location
- [bd worktree](https://beads.gascity.com/cli-reference/worktree.md): Manage git worktrees for parallel development
- [Community Tools](https://beads.gascity.com/community-tools.md): Community-built UIs, editor extensions, and integrations that work with the bd CLI, ranked by maturity
- [Adaptive ID Length](https://beads.gascity.com/core-concepts/adaptive-ids.md): How hash ID length scales with database size to stay short while avoiding collisions
- [Dependencies and Gates](https://beads.gascity.com/core-concepts/dependencies.md): Ordering work with blocking and non-blocking dependencies, and gates that wait on PRs, CI, or timers
- [Graph Links in Beads](https://beads.gascity.com/core-concepts/graph-links.md): Non-blocking links between issues: replies-to threads, relates-to, duplicates, and supersedes chains
- [Hash-based IDs](https://beads.gascity.com/core-concepts/hash-ids.md): Why beads uses collision-resistant hash IDs like bd-a1b2 so agents and branches never clash
- [How Beads Works](https://beads.gascity.com/core-concepts/index.md): The orientation for beads — the dependency-aware issue graph, what bd ready computes, the formula-to-molecule workflow pipeline, and how Dolt sync moves it all between machines.
- [Issues & Dependencies](https://beads.gascity.com/core-concepts/issues.md): The issue model: fields, types, priorities, and the dependencies that decide what work is ready
- [Labels](https://beads.gascity.com/core-concepts/labels.md): Flexible tagging for cross-cutting concerns, filtering, and caching operational state on issues
- [Issue Metadata](https://beads.gascity.com/core-concepts/metadata.md): Storing arbitrary JSON on issues as the extension point for integrations and execution hints
- [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts.md): Why Dolt is the source of truth for sync and how the JSONL export differs from bd dolt push and pull
- [IDE Setup](https://beads.gascity.com/getting-started/ide-setup.md): Configure bd setup recipes, hooks, and instruction files for Claude Code, Cursor, Gemini, Copilot, and other coding agents
- [Installation](https://beads.gascity.com/getting-started/installation.md): Install the bd CLI, Claude Code plugin, and MCP server on macOS, Linux, Windows, and FreeBSD via Homebrew, npm, or go install
- [Quick Start](https://beads.gascity.com/getting-started/quickstart.md): Initialize beads, create issues with dependencies, find ready work, and sync with your team in a few minutes
- [Sync Setup Guide](https://beads.gascity.com/getting-started/sync-setup.md): Set up Dolt sync so issue data follows you across machines: remotes, bootstrapping a clone, and day-to-day push and pull
- [Upgrading](https://beads.gascity.com/getting-started/upgrading.md): Upgrade the bd binary, refresh git hooks, run schema migrations, and handle remote-backed and cross-era databases
- [Introduction](https://beads.gascity.com/index.md): Dependency-aware, Dolt-backed issue tracker built for AI coding agents that survive context loss
- [Aider](https://beads.gascity.com/integrations/aider.md): Set up beads with Aider's human-in-the-loop workflow, where the AI suggests bd commands you approve with /run
- [Azure DevOps (ADO) Integration Configuration](https://beads.gascity.com/integrations/azure-devops.md): Configuration reference for bd ado sync, which bidirectionally syncs beads issues with Azure DevOps work items
- [Claude Code](https://beads.gascity.com/integrations/claude-code.md): Wire beads into Claude Code with a SessionStart hook that primes context, using the CLI instead of MCP
- [Beads Claude Code Plugin](https://beads.gascity.com/integrations/claude-code-plugin.md): Install the beads Claude Code plugin for /beads slash commands, a bundled skill, and session lifecycle hooks
- [Codex](https://beads.gascity.com/integrations/codex.md): Set up beads for Codex with the beads skill, a managed AGENTS.md section, and native hooks that survive compaction
- [Sourcegraph Cody](https://beads.gascity.com/integrations/cody.md): Add beads workflow guidance to Sourcegraph Cody through a .cody/rules/beads.md project rules file
- [GitHub Copilot CLI Integration Design](https://beads.gascity.com/integrations/copilot-cli.md): Design rationale and setup for the Copilot CLI integration, which uses a plugin manifest plus repository instructions
- [Cursor](https://beads.gascity.com/integrations/cursor.md): Set up beads for Cursor with an always-applied rules file, an agent skill, and hooks that restore context after compaction
- [Factory.ai Droid](https://beads.gascity.com/integrations/factory.md): Set up beads for Factory.ai Droid through a managed Beads section in AGENTS.md
- [Gemini CLI](https://beads.gascity.com/integrations/gemini.md): Set up beads for Gemini CLI with SessionStart hooks that run bd prime and GEMINI.md workflow guidance
- [GitHub Copilot](https://beads.gascity.com/integrations/github-copilot.md): Use beads from Copilot Chat in VS Code via the beads-mcp server to track issues in natural language
- [Integrations](https://beads.gascity.com/integrations/index.md): Browse every beads editor and agent integration, from bd setup recipes to MCP-based clients
- [Junie](https://beads.gascity.com/integrations/junie.md): Set up beads for Junie, the JetBrains AI agent, with a guidelines file and an MCP server configuration
- [Kilo Code](https://beads.gascity.com/integrations/kilocode.md): Set up beads for Kilo Code by writing a .kilocode/rules/beads.md project rules file
- [MCP Server](https://beads.gascity.com/integrations/mcp-server.md): Run the beads-mcp server for MCP-only environments like Claude Desktop where the bd CLI is unavailable
- [Mux](https://beads.gascity.com/integrations/mux.md): Set up beads for Mux with a managed AGENTS.md section, optional layered instruction files, and Mux hooks
- [OpenCode](https://beads.gascity.com/integrations/opencode.md): Give OpenCode beads workflow context via a managed Beads section in AGENTS.md
- [Windsurf](https://beads.gascity.com/integrations/windsurf.md): Enable beads in Windsurf through a .windsurf/rules/beads.md rules file with workflow guidance
- [Agent Coordination](https://beads.gascity.com/multi-agent/coordination.md): Assign and claim beads, hand off work, and serialize conflict-prone work with merge slots across multiple agents
- [Federation Setup Guide](https://beads.gascity.com/multi-agent/federation.md): Configure peer-to-peer sync of beads databases across workspaces with Dolt remotes, sovereignty tiers, and topologies
- [Multi-Agent](https://beads.gascity.com/multi-agent/index.md): Coordinate beads across multiple agents and repositories with routing, cross-repo dependencies, and work handoff
- [Multi-Repo Migration Guide](https://beads.gascity.com/multi-agent/multi-repo-migration.md): Adopt multi-repo routing for OSS contributor, team, multi-phase, and multi-persona workflows with separate planning repos
- [Multi-Repo Routing](https://beads.gascity.com/multi-agent/routing.md): How bd create decides which repository each new bead lands in, with role detection and multi-repo hydration
- [Circular Dependencies](https://beads.gascity.com/recovery/circular-dependencies.md): Detect and break dependency cycles
- [Database Corruption](https://beads.gascity.com/recovery/database-corruption.md): Recover from Dolt database corruption
- [Recovery Overview](https://beads.gascity.com/recovery/index.md): Diagnose and resolve common Beads issues
- [Recovery Playbooks](https://beads.gascity.com/recovery/init-safety.md): Step-by-step recovery for bd init and bd dolt push/pull refusals, including the primary-key fork playbook
- [Merge Conflicts](https://beads.gascity.com/recovery/merge-conflicts.md): Resolve Dolt merge conflicts
- [Sync Failures](https://beads.gascity.com/recovery/sync-failures.md): Recover from Dolt sync failures
- [Uninstalling](https://beads.gascity.com/recovery/uninstalling.md): Remove beads from a repository with bd reset, uninstall git hooks, and delete the bd binary after backing up issue data
- [Advanced Features](https://beads.gascity.com/reference/advanced.md): Advanced bd operations for renaming issues and prefixes, merging duplicates, compaction, database redirects, and performance tuning.
- [Antivirus False Positives](https://beads.gascity.com/reference/antivirus.md): Why antivirus tools flag the bd binary as a false positive, and how to verify checksums, add exclusions, and report it.
- [Configuration](https://beads.gascity.com/reference/configuration.md): Complete reference for bd configuration across config.yaml and database-stored settings, with precedence, secrets, auto-commit, backup, and integrations.
- [FAQ](https://beads.gascity.com/reference/faq.md): Common questions about beads and how to use it effectively
- [Git Integration](https://beads.gascity.com/reference/git-integration.md): How bd uses git for hosting and hooks, including hook installation, external hook managers, worktrees, and branch workflows.
- [Reference](https://beads.gascity.com/reference/index.md): Lookup material — configuration, git integration, JSON contracts, observability, troubleshooting, and the FAQ.
- [JSON Output Schema Contract](https://beads.gascity.com/reference/json-schema.md): The stable JSON output contract for bd --json commands, covering the schema_version envelope, per-command fields, and consumer guidelines.
- [Observability (OpenTelemetry)](https://beads.gascity.com/reference/observability.md): Exporting bd metrics and traces over OpenTelemetry (OTLP), with a local VictoriaMetrics and Grafana stack, env vars, and a metric reference.
- [Protected Branches](https://beads.gascity.com/reference/protected-branches.md): Why beads needs no protected-branch workaround since Dolt stores issue data outside Git refs, plus team workflow and legacy sync-branch cleanup.
- [Troubleshooting](https://beads.gascity.com/reference/troubleshooting.md): Fixes for common bd problems across installation, the database and Dolt server, sync, git hooks, dependencies, and platform-specific issues.
- [Git Worktrees Guide](https://beads.gascity.com/reference/worktrees.md): Using beads from Git worktrees, which share one .beads workspace, plus external BEADS_DIR setups and legacy sync-branch cleanup.
- [Related Projects](https://beads.gascity.com/related-projects.md): Adjacent, independent projects that solve neighboring problems and compose well with beads
- [Formulas](https://beads.gascity.com/workflows/formulas.md): Writing declarative TOML or JSON workflow templates with steps, variables, dependencies, gates, and aspects, then cooking them into protos.
- [Gates](https://beads.gascity.com/workflows/gates.md): Async wait conditions that park a workflow step until the world catches up — a human decision, a timer, or a GitHub run or PR.
- [Workflows](https://beads.gascity.com/workflows/index.md): Declare multi-step work once as a formula, then stamp it out as molecules of real, dependency-ordered beads.
- [Molecules](https://beads.gascity.com/workflows/molecules.md): Molecules are epics whose children flow through bd ready as ordered steps; covers creating, executing, bonding, and the molecule lifecycle.
- [TODO Command](https://beads.gascity.com/workflows/todo.md): The bd todo command for managing lightweight TODO items as ordinary task-type issues, with add, list, and done shortcuts.
- [Wisps](https://beads.gascity.com/workflows/wisps.md): Ephemeral molecules for operational work that has no audit value once it's done.