# Beads Documentation

- [Introduction](https://beads.gascity.com/index.md): Dependency-aware, Dolt-backed issue tracker built for AI coding agents that survive context loss
- [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
- [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
- [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
- [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
- [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
- [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
- [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
- [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
- [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
- [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
- [Architecture Overview](https://beads.gascity.com/architecture/index.md): How Beads stores, queries, and syncs issue data with Dolt
- [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
- [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.
- [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.
- [Wisps](https://beads.gascity.com/workflows/wisps.md): Ephemeral molecules for operational work that has no audit value once it's done.
- [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.
- [Recovery Overview](https://beads.gascity.com/recovery/index.md): Diagnose and resolve common Beads issues
- [Accidental v1.2.1 Release](https://beads.gascity.com/recovery/accidental-1-2-1-release.md): Recover a database migrated by the accidental, untested v1.2.1 release
- [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
- [Database Corruption](https://beads.gascity.com/recovery/database-corruption.md): Recover from Dolt database corruption
- [Merge Conflicts](https://beads.gascity.com/recovery/merge-conflicts.md): Resolve Dolt merge conflicts
- [Circular Dependencies](https://beads.gascity.com/recovery/circular-dependencies.md): Detect and break dependency cycles
- [Sync Failures](https://beads.gascity.com/recovery/sync-failures.md): Recover from Dolt sync failures
- [History Bloat](https://beads.gascity.com/recovery/history-squash.md): Shed reachable Dolt history that dolt gc cannot reclaim
- [Uninstalling](https://beads.gascity.com/recovery/uninstalling.md): Remove beads from a repository with bd admin reset, uninstall git hooks, and delete the bd binary after backing up issue data
- [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 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
- [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
- [Bucket Federation Quickstart](https://beads.gascity.com/multi-agent/bucket-federation.md): Federate a beads database across machines through a GCS or S3 bucket — remote add, seed push, birth the second replica, and pick a sync cadence
- [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
- [Integrations](https://beads.gascity.com/integrations/index.md): Browse every beads editor and agent integration, from bd setup recipes to MCP-based clients
- [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
- [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
- [Cursor](https://beads.gascity.com/integrations/cursor.md): Set up beads for Cursor with an always-applied project rules file
- [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
- [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
- [Kiro CLI](https://beads.gascity.com/integrations/kiro.md)
- [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
- [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
- [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
- [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
- [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
- [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
- [Related Projects](https://beads.gascity.com/related-projects.md): Adjacent, independent projects that solve neighboring problems and compose well with beads
- [Reference](https://beads.gascity.com/reference/index.md): Lookup material — configuration, git integration, JSON contracts, observability, troubleshooting, and the FAQ.
- [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.
- [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.
- [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.
- [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.
- [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.
- [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.
- [Events Journal](https://beads.gascity.com/reference/events-journal.md): The durable, ordered record of every committed issue mutation that external tooling tails and replays — enabling it, the record contract, resuming after a prune, automatic retention, and what it deliberately does not cover.
- [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.
- [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.
- [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.
- [FAQ](https://beads.gascity.com/reference/faq.md): Common questions about beads and how to use it effectively
- [CLI Reference](https://beads.gascity.com/cli-reference/index.md): Generated reference for every bd command
- [bd admin](https://beads.gascity.com/cli-reference/admin.md): Administrative commands for beads database maintenance.
- [bd ado](https://beads.gascity.com/cli-reference/ado.md): Commands for syncing issues between beads and Azure DevOps.
- [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): Audit log entries are appended to .beads/interactions.jsonl.
- [bd backup](https://beads.gascity.com/cli-reference/backup.md): Back up your beads database for off-machine recovery.
- [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): Bootstrap sets up the beads database without destroying existing data.
- [bd branch](https://beads.gascity.com/cli-reference/branch.md): List all branches or create a new branch.
- [bd children](https://beads.gascity.com/cli-reference/children.md): List all beads that are children of the specified parent bead.
- [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 Dolt commits older than N days into a single commit.
- [bd completion](https://beads.gascity.com/cli-reference/completion.md): Generate the autocompletion script for bd for the specified shell.
- [bd config](https://beads.gascity.com/cli-reference/config.md): Manage configuration settings for external integrations and preferences.
- [bd context](https://beads.gascity.com/cli-reference/context.md): Show the effective backend identity information including repository paths,
- [bd cook](https://beads.gascity.com/cli-reference/cook.md): Cook transforms a .formula.json file into a proto.
- [bd count](https://beads.gascity.com/cli-reference/count.md): Count issues matching the specified filters.
- [bd create-form](https://beads.gascity.com/cli-reference/create-form.md): Create a new issue using an interactive terminal form.
- [bd create](https://beads.gascity.com/cli-reference/create.md): Create a new issue (or batch from markdown/graph JSON)
- [bd defer](https://beads.gascity.com/cli-reference/defer.md): Defer issues to put them on ice for later.
- [bd delete](https://beads.gascity.com/cli-reference/delete.md): Delete one or more issues and clean up all references to them.
- [bd dep](https://beads.gascity.com/cli-reference/dep.md): Manage dependencies between issues.
- [bd diff](https://beads.gascity.com/cli-reference/diff.md): Show the differences in issues between two commits or branches.
- [bd doctor](https://beads.gascity.com/cli-reference/doctor.md): Sanity check the beads installation for the current directory or specified path.
- [bd dolt](https://beads.gascity.com/cli-reference/dolt.md): Configure and manage Dolt database settings and server lifecycle.
- [bd duplicate](https://beads.gascity.com/cli-reference/duplicate.md): Mark an issue as a duplicate of a canonical issue.
- [bd duplicates](https://beads.gascity.com/cli-reference/duplicates.md): Find issues with identical content (title, description, design, acceptance criteria).
- [bd edit](https://beads.gascity.com/cli-reference/edit.md): Edit an issue field using your configured $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 all issues to JSONL (newline-delimited JSON) format.
- [bd federation](https://beads.gascity.com/cli-reference/federation.md): Federation commands require CGO and the Dolt storage backend.
- [bd find-duplicates](https://beads.gascity.com/cli-reference/find-duplicates.md): Find issues that are semantically similar but not exact duplicates.
- [bd flatten](https://beads.gascity.com/cli-reference/flatten.md): Nuclear option: squash ALL Dolt commit history into a single commit.
- [bd forget](https://beads.gascity.com/cli-reference/forget.md): Remove a memory by its key.
- [bd formula](https://beads.gascity.com/cli-reference/formula.md): Manage workflow formulas - the source layer for molecule templates.
- [bd gate](https://beads.gascity.com/cli-reference/gate.md): Gates are async wait conditions that block workflow steps.
- [bd gc](https://beads.gascity.com/cli-reference/gc.md): Full lifecycle garbage collection for standalone Beads databases.
- [bd github](https://beads.gascity.com/cli-reference/github.md): Commands for syncing issues between beads and GitHub.
- [bd gitlab](https://beads.gascity.com/cli-reference/gitlab.md): Commands for syncing issues between beads and GitLab.
- [bd graph](https://beads.gascity.com/cli-reference/graph.md): Display a visualization of an issue's dependency graph.
- [bd history](https://beads.gascity.com/cli-reference/history.md): Show the complete version history of an issue, including all commits
- [bd hooks](https://beads.gascity.com/cli-reference/hooks.md): Install, uninstall, or list git hooks for beads integration.
- [bd human](https://beads.gascity.com/cli-reference/human.md): Display a focused help menu showing only the most common commands.
- [bd import](https://beads.gascity.com/cli-reference/import.md): Import issues from a JSONL file (newline-delimited JSON) into the database.
- [bd info](https://beads.gascity.com/cli-reference/info.md): Display information about the current database.
- [bd init-safety](https://beads.gascity.com/cli-reference/init-safety.md): bd init flag safety contract.
- [bd init](https://beads.gascity.com/cli-reference/init.md): Initialize bd in the current directory by creating a .beads/ directory
- [bd jira](https://beads.gascity.com/cli-reference/jira.md): Synchronize issues between beads and Jira.
- [bd kv](https://beads.gascity.com/cli-reference/kv.md): Commands for working with the beads key-value store.
- [bd label](https://beads.gascity.com/cli-reference/label.md): Manage issue labels
- [bd linear](https://beads.gascity.com/cli-reference/linear.md): Synchronize issues between beads and Linear.
- [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 recommended sections based on issue type.
- [bd list](https://beads.gascity.com/cli-reference/list.md): List issues
- [bd mail](https://beads.gascity.com/cli-reference/mail.md): Delegates mail operations to an external mail provider.
- [bd memories](https://beads.gascity.com/cli-reference/memories.md): List all memories, or search by keyword.
- [bd merge-slot](https://beads.gascity.com/cli-reference/merge-slot.md): Merge-slot gates serialize conflict resolution in the merge queue.
- [bd metrics](https://beads.gascity.com/cli-reference/metrics.md): Show whether anonymous usage metrics are on, see exactly what is sent, and
- [bd migrate](https://beads.gascity.com/cli-reference/migrate.md): Database migration and data transformation commands.
- [bd mol](https://beads.gascity.com/cli-reference/mol.md): Manage molecules - work templates for agent workflows.
- [bd note](https://beads.gascity.com/cli-reference/note.md): Append a note to an issue's notes field.
- [bd notion](https://beads.gascity.com/cli-reference/notion.md): Commands for syncing issues between beads and Notion.
- [bd onboard](https://beads.gascity.com/cli-reference/onboard.md): Display a minimal snippet to add to your agent instructions file for bd integration.
- [bd orphans](https://beads.gascity.com/cli-reference/orphans.md): Identify orphaned issues - issues that are referenced in commit messages but remain open or in_progress in the database.
- [bd ping](https://beads.gascity.com/cli-reference/ping.md): Lightweight health check that confirms bd can reach its database.
- [bd preflight](https://beads.gascity.com/cli-reference/preflight.md): Display a checklist of common pre-PR checks for contributors.
- [bd prime](https://beads.gascity.com/cli-reference/prime.md): Output essential Beads workflow context in AI-optimized markdown format.
- [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 (ephemeral issue) to a permanent bead.
- [bd prune](https://beads.gascity.com/cli-reference/prune.md): Permanently delete closed non-ephemeral beads and their associated data.
- [bd purge](https://beads.gascity.com/cli-reference/purge.md): Permanently delete closed ephemeral beads and their associated data.
- [bd q](https://beads.gascity.com/cli-reference/q.md): Quick capture creates an issue and outputs only the issue ID.
- [bd query](https://beads.gascity.com/cli-reference/query.md): Query issues using a simple query language that supports compound filters,
- [bd quickstart](https://beads.gascity.com/cli-reference/quickstart.md): Display a quick start guide showing common bd workflows and patterns.
- [bd ready](https://beads.gascity.com/cli-reference/ready.md): Show ready work (open issues with no active blockers).
- [bd recall](https://beads.gascity.com/cli-reference/recall.md): Retrieve the full content of a memory by its key.
- [bd recompute-blocked](https://beads.gascity.com/cli-reference/recompute-blocked.md): Recompute the denormalized is_blocked flag for every issue and wisp.
- [bd remember](https://beads.gascity.com/cli-reference/remember.md): Store a memory that persists across sessions and account rotations.
- [bd rename-prefix](https://beads.gascity.com/cli-reference/rename-prefix.md): Rename the issue prefix for all issues in the database.
- [bd rename](https://beads.gascity.com/cli-reference/rename.md): Rename an issue from one ID to another.
- [bd reopen](https://beads.gascity.com/cli-reference/reopen.md): Reopen closed issues by setting status to 'open' and clearing the closed_at timestamp.
- [bd repo](https://beads.gascity.com/cli-reference/repo.md): Configure and manage multiple repository support for multi-repo hydration.
- [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 across title and ID (excludes closed issues by default).
- [bd set-state](https://beads.gascity.com/cli-reference/set-state.md): Atomically set operational state on an issue.
- [bd setup](https://beads.gascity.com/cli-reference/setup.md): Setup integration files for AI editors and coding assistants.
- [bd ship](https://beads.gascity.com/cli-reference/ship.md): Ship a capability to satisfy 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 a raw SQL query against the underlying database (SQLite or Dolt).
- [bd stale](https://beads.gascity.com/cli-reference/stale.md): Show issues that haven't been updated recently and may need attention.
- [bd state](https://beads.gascity.com/cli-reference/state.md): Query the current value of a state dimension from an issue's labels.
- [bd status](https://beads.gascity.com/cli-reference/status.md): Show a quick snapshot of the issue database state and statistics.
- [bd statuses](https://beads.gascity.com/cli-reference/statuses.md): List all valid issue statuses and their categories.
- [bd supersede](https://beads.gascity.com/cli-reference/supersede.md): Mark an issue as superseded by a newer version.
- [bd swarm](https://beads.gascity.com/cli-reference/swarm.md): Swarm management commands for coordinating parallel work on 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 as lightweight task issues.
- [bd types](https://beads.gascity.com/cli-reference/types.md): List all valid issue types that can be used with bd create --type.
- [bd undefer](https://beads.gascity.com/cli-reference/undefer.md): Undefer issues to restore them to open status.
- [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): Commands for checking bd version upgrades and reviewing changes.
- [bd vc](https://beads.gascity.com/cli-reference/vc.md): Version control operations for the beads database.
- [bd version](https://beads.gascity.com/cli-reference/version.md): Print version information
- [bd where](https://beads.gascity.com/cli-reference/where.md): Show the active beads database location, including redirect information.
- [bd worktree](https://beads.gascity.com/cli-reference/worktree.md): Manage git worktrees with proper beads configuration.