# Table of Contents - [Introduction - Beads Documentation](#introduction-beads-documentation) - [Dolt Backend for Beads - Beads Documentation](#dolt-backend-for-beads-beads-documentation) - [Unknown](#unknown) - [Architecture Overview - Beads Documentation](#architecture-overview-beads-documentation) - [Sourcegraph Cody - Beads Documentation](#sourcegraph-cody-beads-documentation) - [Windsurf - Beads Documentation](#windsurf-beads-documentation) - [OpenCode - Beads Documentation](#opencode-beads-documentation) - [Kilo Code - Beads Documentation](#kilo-code-beads-documentation) - [Related Projects - Beads Documentation](#related-projects-beads-documentation) - [Factory.ai Droid - Beads Documentation](#factory-ai-droid-beads-documentation) - [Gemini CLI - Beads Documentation](#gemini-cli-beads-documentation) - [Mux - Beads Documentation](#mux-beads-documentation) - [Cursor - Beads Documentation](#cursor-beads-documentation) - [Integrations - Beads Documentation](#integrations-beads-documentation) - [Circular Dependencies - Beads Documentation](#circular-dependencies-beads-documentation) - [Recovery Overview - Beads Documentation](#recovery-overview-beads-documentation) - [Database Corruption - Beads Documentation](#database-corruption-beads-documentation) - [Multi-Agent - Beads Documentation](#multi-agent-beads-documentation) - [Merge Conflicts - Beads Documentation](#merge-conflicts-beads-documentation) - [Sync Concepts - Beads Documentation](#sync-concepts-beads-documentation) - [Codex - Beads Documentation](#codex-beads-documentation) - [Sync Failures - Beads Documentation](#sync-failures-beads-documentation) - [Wisps - Beads Documentation](#wisps-beads-documentation) - [Workflows - Beads Documentation](#workflows-beads-documentation) - [Workflows - Beads Documentation](#workflows-beads-documentation) - [Issue Metadata - Beads Documentation](#issue-metadata-beads-documentation) - [GitHub Copilot CLI Integration Design - Beads Documentation](#github-copilot-cli-integration-design-beads-documentation) - [History Bloat - Beads Documentation](#history-bloat-beads-documentation) - [Protected Branches - Beads Documentation](#protected-branches-beads-documentation) - [Uninstalling - Beads Documentation](#uninstalling-beads-documentation) - [Git Worktrees Guide - Beads Documentation](#git-worktrees-guide-beads-documentation) - [Reference - Beads Documentation](#reference-beads-documentation) - [Gates - Beads Documentation](#gates-beads-documentation) - [Issues & Dependencies - Beads Documentation](#issues-dependencies-beads-documentation) - [Aider - Beads Documentation](#aider-beads-documentation) - [MCP Server - Beads Documentation](#mcp-server-beads-documentation) - [TODO Command - Beads Documentation](#todo-command-beads-documentation) - [Hash-based IDs - Beads Documentation](#hash-based-ids-beads-documentation) - [Agent Coordination - Beads Documentation](#agent-coordination-beads-documentation) - [Antivirus False Positives - Beads Documentation](#antivirus-false-positives-beads-documentation) - [Observability (OpenTelemetry) - Beads Documentation](#observability-opentelemetry-beads-documentation) - [Recovery Playbooks - Beads Documentation](#recovery-playbooks-beads-documentation) - [JSON Output Schema Contract - Beads Documentation](#json-output-schema-contract-beads-documentation) - [GitHub Copilot - Beads Documentation](#github-copilot-beads-documentation) - [Junie - Beads Documentation](#junie-beads-documentation) - [Formulas - Beads Documentation](#formulas-beads-documentation) - [Claude Code - Beads Documentation](#claude-code-beads-documentation) - [Community Tools - Beads Documentation](#community-tools-beads-documentation) - [Adaptive ID Length - Beads Documentation](#adaptive-id-length-beads-documentation) - [Advanced Features - Beads Documentation](#advanced-features-beads-documentation) - [Git Integration - Beads Documentation](#git-integration-beads-documentation) - [Federation Setup Guide - Beads Documentation](#federation-setup-guide-beads-documentation) - [Graph Links in Beads - Beads Documentation](#graph-links-in-beads-beads-documentation) - [Sync Setup Guide - Beads Documentation](#sync-setup-guide-beads-documentation) - [Molecules - Beads Documentation](#molecules-beads-documentation) - [Azure DevOps (ADO) Integration Configuration - Beads Documentation](#azure-devops-ado-integration-configuration-beads-documentation) - [Upgrading - Beads Documentation](#upgrading-beads-documentation) - [Beads Claude Code Plugin - Beads Documentation](#beads-claude-code-plugin-beads-documentation) - [IDE Setup - Beads Documentation](#ide-setup-beads-documentation) - [How Beads Works - Beads Documentation](#how-beads-works-beads-documentation) - [Dependencies and Gates - Beads Documentation](#dependencies-and-gates-beads-documentation) - [How Beads Works - Beads Documentation](#how-beads-works-beads-documentation) - [Quick Start - Beads Documentation](#quick-start-beads-documentation) - [Multi-Repo Migration Guide - Beads Documentation](#multi-repo-migration-guide-beads-documentation) - [Installation - Beads Documentation](#installation-beads-documentation) - [Multi-Repo Routing - Beads Documentation](#multi-repo-routing-beads-documentation) - [Configuration - Beads Documentation](#configuration-beads-documentation) - [Troubleshooting - Beads Documentation](#troubleshooting-beads-documentation) - [Labels - Beads Documentation](#labels-beads-documentation) - [FAQ - Beads Documentation](#faq-beads-documentation) - [bd admin - Beads Documentation](#bd-admin-beads-documentation) - [bd ado - Beads Documentation](#bd-ado-beads-documentation) - [bd assign - Beads Documentation](#bd-assign-beads-documentation) - [bd audit - Beads Documentation](#bd-audit-beads-documentation) - [bd blocked - Beads Documentation](#bd-blocked-beads-documentation) - [bd children - Beads Documentation](#bd-children-beads-documentation) - [bd bootstrap - Beads Documentation](#bd-bootstrap-beads-documentation) - [bd branch - Beads Documentation](#bd-branch-beads-documentation) - [bd batch - Beads Documentation](#bd-batch-beads-documentation) - [bd backup - Beads Documentation](#bd-backup-beads-documentation) - [bd close - Beads Documentation](#bd-close-beads-documentation) - [bd comment - Beads Documentation](#bd-comment-beads-documentation) - [bd compact - Beads Documentation](#bd-compact-beads-documentation) - [bd comments - Beads Documentation](#bd-comments-beads-documentation) - [bd context - Beads Documentation](#bd-context-beads-documentation) - [bd completion - Beads Documentation](#bd-completion-beads-documentation) - [bd count - Beads Documentation](#bd-count-beads-documentation) - [bd cook - Beads Documentation](#bd-cook-beads-documentation) - [bd create-form - Beads Documentation](#bd-create-form-beads-documentation) - [bd defer - Beads Documentation](#bd-defer-beads-documentation) - [bd delete - Beads Documentation](#bd-delete-beads-documentation) - [bd create - Beads Documentation](#bd-create-beads-documentation) - [bd diff - Beads Documentation](#bd-diff-beads-documentation) - [bd recall - Beads Documentation](#bd-recall-beads-documentation) - [bd edit - Beads Documentation](#bd-edit-beads-documentation) - [bd federation - Beads Documentation](#bd-federation-beads-documentation) - [bd gc - Beads Documentation](#bd-gc-beads-documentation) - [bd forget - Beads Documentation](#bd-forget-beads-documentation) - [bd history - Beads Documentation](#bd-history-beads-documentation) - [bd link - Beads Documentation](#bd-link-beads-documentation) - [bd note - Beads Documentation](#bd-note-beads-documentation) - [bd onboard - Beads Documentation](#bd-onboard-beads-documentation) - [bd info - Beads Documentation](#bd-info-beads-documentation) - [bd memories - Beads Documentation](#bd-memories-beads-documentation) - [bd orphans - Beads Documentation](#bd-orphans-beads-documentation) - [bd priority - Beads Documentation](#bd-priority-beads-documentation) - [bd ping - Beads Documentation](#bd-ping-beads-documentation) - [bd preflight - Beads Documentation](#bd-preflight-beads-documentation) - [bd promote - Beads Documentation](#bd-promote-beads-documentation) - [bd q - Beads Documentation](#bd-q-beads-documentation) - [bd recompute-blocked - Beads Documentation](#bd-recompute-blocked-beads-documentation) - [bd rename - Beads Documentation](#bd-rename-beads-documentation) - [bd remember - Beads Documentation](#bd-remember-beads-documentation) - [bd reopen - Beads Documentation](#bd-reopen-beads-documentation) - [bd restore - Beads Documentation](#bd-restore-beads-documentation) - [bd set-state - Beads Documentation](#bd-set-state-beads-documentation) - [bd ship - Beads Documentation](#bd-ship-beads-documentation) - [bd show - Beads Documentation](#bd-show-beads-documentation) - [bd stale - Beads Documentation](#bd-stale-beads-documentation) - [bd status - Beads Documentation](#bd-status-beads-documentation) - [bd statuses - Beads Documentation](#bd-statuses-beads-documentation) - [bd tag - Beads Documentation](#bd-tag-beads-documentation) - [bd undefer - Beads Documentation](#bd-undefer-beads-documentation) - [bd duplicate - Beads Documentation](#bd-duplicate-beads-documentation) - [bd version - Beads Documentation](#bd-version-beads-documentation) - [bd flatten - Beads Documentation](#bd-flatten-beads-documentation) - [bd export - Beads Documentation](#bd-export-beads-documentation) - [bd init-safety - Beads Documentation](#bd-init-safety-beads-documentation) - [bd lint - Beads Documentation](#bd-lint-beads-documentation) - [bd rename-prefix - Beads Documentation](#bd-rename-prefix-beads-documentation) - [bd purge - Beads Documentation](#bd-purge-beads-documentation) - [bd quickstart - Beads Documentation](#bd-quickstart-beads-documentation) - [bd sql - Beads Documentation](#bd-sql-beads-documentation) - [bd supersede - Beads Documentation](#bd-supersede-beads-documentation) - [bd types - Beads Documentation](#bd-types-beads-documentation) - [bd duplicates - Beads Documentation](#bd-duplicates-beads-documentation) - [bd where - Beads Documentation](#bd-where-beads-documentation) - [bd epic - Beads Documentation](#bd-epic-beads-documentation) - [bd find-duplicates - Beads Documentation](#bd-find-duplicates-beads-documentation) - [bd mail - Beads Documentation](#bd-mail-beads-documentation) - [bd prime - Beads Documentation](#bd-prime-beads-documentation) - [bd metrics - Beads Documentation](#bd-metrics-beads-documentation) - [bd query - Beads Documentation](#bd-query-beads-documentation) - [bd search - Beads Documentation](#bd-search-beads-documentation) - [bd setup - Beads Documentation](#bd-setup-beads-documentation) - [bd ready - Beads Documentation](#bd-ready-beads-documentation) - [bd rules - Beads Documentation](#bd-rules-beads-documentation) - [bd state - Beads Documentation](#bd-state-beads-documentation) - [bd update - Beads Documentation](#bd-update-beads-documentation) - [CLI Reference - Beads Documentation](#cli-reference-beads-documentation) - [bd graph - Beads Documentation](#bd-graph-beads-documentation) - [bd config - Beads Documentation](#bd-config-beads-documentation) - [bd import - Beads Documentation](#bd-import-beads-documentation) - [bd kv - Beads Documentation](#bd-kv-beads-documentation) - [bd label - Beads Documentation](#bd-label-beads-documentation) - [bd prune - Beads Documentation](#bd-prune-beads-documentation) - [bd todo - Beads Documentation](#bd-todo-beads-documentation) - [bd vc - Beads Documentation](#bd-vc-beads-documentation) - [bd formula - Beads Documentation](#bd-formula-beads-documentation) - [CLI Reference - Beads Documentation](#cli-reference-beads-documentation) - [bd list - Beads Documentation](#bd-list-beads-documentation) - [bd hooks - Beads Documentation](#bd-hooks-beads-documentation) - [bd doctor - Beads Documentation](#bd-doctor-beads-documentation) - [bd github - Beads Documentation](#bd-github-beads-documentation) - [bd gitlab - Beads Documentation](#bd-gitlab-beads-documentation) - [bd human - Beads Documentation](#bd-human-beads-documentation) - [bd merge-slot - Beads Documentation](#bd-merge-slot-beads-documentation) - [bd upgrade - Beads Documentation](#bd-upgrade-beads-documentation) - [bd jira - Beads Documentation](#bd-jira-beads-documentation) - [bd init - Beads Documentation](#bd-init-beads-documentation) - [bd notion - Beads Documentation](#bd-notion-beads-documentation) - [bd repo - Beads Documentation](#bd-repo-beads-documentation) - [bd worktree - Beads Documentation](#bd-worktree-beads-documentation) - [bd migrate - Beads Documentation](#bd-migrate-beads-documentation) - [bd swarm - Beads Documentation](#bd-swarm-beads-documentation) - [bd dep - Beads Documentation](#bd-dep-beads-documentation) - [bd gate - Beads Documentation](#bd-gate-beads-documentation) - [bd linear - Beads Documentation](#bd-linear-beads-documentation) - [bd dolt - Beads Documentation](#bd-dolt-beads-documentation) --- # Introduction - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/#content-area) **Beads** (`bd`) is a Dolt-powered issue tracker designed for AI-supervised coding workflows. These docs are for the 1.1.0 release of beads — see the [v1.1.0 release notes](https://github.com/gastownhall/beads/releases/tag/v1.1.0) . [​](https://beads.gascity.com/#why-beads) Why Beads? ------------------------------------------------------- Traditional issue trackers (Jira, GitHub Issues) weren’t designed for AI agents. Beads was built from the ground up for: * **AI-native workflows** - Hash-based IDs prevent collisions when multiple agents work concurrently * **Dolt-backed storage** - Issues stored in a version-controlled SQL database, enabling collaboration via Dolt-native replication * **Dependency-aware execution** - `bd ready` shows only unblocked work * **Formula system** - Declarative templates for repeatable workflows * **Multi-agent coordination** - Routing, gates, and molecules for complex workflows [​](https://beads.gascity.com/#quick-start) Quick Start ---------------------------------------------------------- # Install via Homebrew (macOS/Linux) brew install beads # Or quick install (macOS/Linux/FreeBSD) curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash # Initialize in your project cd your-project bd init --quiet # Create your first issue bd create "Set up database" -p 1 -t task # See ready work bd ready [​](https://beads.gascity.com/#core-concepts) Core Concepts -------------------------------------------------------------- The whole model on one page: [How Beads Works](https://beads.gascity.com/core-concepts/index) . | Concept | Description | | --- | --- | | [**Beads (issues)**](https://beads.gascity.com/core-concepts/issues) | Work items with priorities, types, labels, and dependencies | | [**Dependencies**](https://beads.gascity.com/core-concepts/dependencies) | `blocks`, `parent-child`, `discovered-from`, `related` | | [**Sync**](https://beads.gascity.com/core-concepts/sync-concepts) | Dolt push/pull over your git remote — no server to run | | [**Formulas**](https://beads.gascity.com/workflows/formulas) | Declarative workflow templates (TOML or JSON) | | [**Molecules**](https://beads.gascity.com/workflows/molecules) | Work graphs instantiated from formulas | | [**Gates**](https://beads.gascity.com/workflows/gates) | Async coordination primitives (human, timer, GitHub) | [​](https://beads.gascity.com/#for-ai-agents) For AI Agents -------------------------------------------------------------- Beads is optimized for AI coding agents: # Always use --json for programmatic access bd list --json bd show bd-42 --json # Track discovered work during implementation bd create "Found bug in auth" --description="Details..." \ --deps discovered-from:bd-100 --json # Push changes at end of session bd dolt push See the [Claude Code integration](https://beads.gascity.com/integrations/claude-code) for detailed agent instructions. [​](https://beads.gascity.com/#architecture) Architecture ------------------------------------------------------------ Dolt DB (.beads/embeddeddolt/ in embedded mode, .beads/dolt/ in server mode; gitignored) ↕ dolt commit Local Dolt history ↕ dolt push/pull Remote Dolt repository (shared across machines) The magic is automatic synchronization via Dolt’s version-controlled database with built-in replication. [​](https://beads.gascity.com/#next-steps) Next Steps -------------------------------------------------------- * [Installation](https://beads.gascity.com/getting-started/installation) - Get bd installed * [Quick Start](https://beads.gascity.com/getting-started/quickstart) - Create your first issues * [How Beads Works](https://beads.gascity.com/core-concepts/index) - The concept model on one page * [CLI Reference](https://beads.gascity.com/cli-reference/index) - All available commands * [Workflows](https://beads.gascity.com/workflows/index) - Formulas, molecules, and gates [Installation](https://beads.gascity.com/getting-started/installation) ⌘I --- # Dolt Backend for Beads - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/architecture/dolt#content-area) Beads uses Dolt as its storage backend. Dolt provides a version-controlled SQL database with cell-level merge, native branching, and two deployment modes. [​](https://beads.gascity.com/architecture/dolt#why-dolt) Why Dolt? ---------------------------------------------------------------------- * **Native version control** — cell-level diffs and merges, not line-based * **Multi-writer support** — server mode enables concurrent agents * **Built-in history** — every write creates a Dolt commit * **Native branching** — Dolt branches independent of git branches * **Single-binary option** — embedded mode for solo users (no server needed) [​](https://beads.gascity.com/architecture/dolt#getting-started) Getting Started ----------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/architecture/dolt#install-dolt-server-mode-only) Install Dolt (Server Mode Only) Embedded mode includes everything in the `bd` binary; no separate Dolt install is needed. Install the standalone `dolt` CLI only when you want to run server mode or work directly with the database via `dolt sql`. # macOS brew install dolt # Linux curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash # Verify installation dolt version ### [​](https://beads.gascity.com/architecture/dolt#new-project) New Project # Embedded mode (single writer, no server — default for standalone) bd init # Server mode (multi-writer, e.g. orchestrator) gt dolt start # Start the Dolt server bd init --server # Initialize with server mode ### [​](https://beads.gascity.com/architecture/dolt#migrate-from-sqlite-legacy) Migrate from SQLite (Legacy) If upgrading from an older version that used SQLite: > **Note:** The `bd migrate --to-dolt` command was removed in v0.58.0. For pre-0.50 installations with JSONL data, use the migration script: > > scripts/migrate-jsonl-to-dolt.sh > > > See [Troubleshooting](https://beads.gascity.com/reference/troubleshooting#circuit-breaker-server-appears-down-failing-fast) > if you encounter connection errors after migration. Migration creates backups automatically. Your original SQLite database is preserved as `beads.backup-pre-dolt-*.db`. [​](https://beads.gascity.com/architecture/dolt#modes-of-operation) Modes of Operation ----------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/architecture/dolt#embedded-mode-solo-/-standalone) Embedded Mode (Solo / Standalone) In-process Dolt engine — no separate server needed. This is the default for standalone Beads users. The `bd` binary includes everything; just `bd init` and go. * Single-writer (one process at a time) * Data lives in `.beads/embeddeddolt/` alongside your code * Push to GitHub with `bd dolt push` — code and issues in one repo * Zero ops: no server, no ports, no PID files ### [​](https://beads.gascity.com/architecture/dolt#server-mode-multi-writer-/-orchestrator) Server Mode (Multi-Writer / Orchestrator) Connects to a running `dolt sql-server` for multi-client access. # Start the server (orchestrator) gt dolt start # Or manually cd ~/.dolt-data/beads && dolt sql-server --port 3307 # Initialize in server mode bd init --server # Or switch via environment variable export BEADS_DOLT_SERVER_MODE=1 # .beads/config.yaml (server mode settings) dolt: mode: server host: 127.0.0.1 port: 3307 user: root Configure the connection with flags or environment variables: | Flag | Env Var | Default | | --- | --- | --- | | `--server-host` | `BEADS_DOLT_SERVER_HOST` | `127.0.0.1` | | `--server-port` | `BEADS_DOLT_SERVER_PORT` | `3307` | | `--server-socket` | `BEADS_DOLT_SERVER_SOCKET` | (none; uses TCP) | | `--server-user` | `BEADS_DOLT_SERVER_USER` | `root` | | | `BEADS_DOLT_PASSWORD` | (none) | **Unix domain sockets:** Use `--server-socket` to connect via a Unix socket instead of TCP. This avoids port conflicts between concurrent projects and is useful in sandboxed environments (e.g., Claude Code) where file-level access control is simpler than network allowlists. The Dolt server must be started with `dolt sql-server --socket `. Auto-start is not supported in socket mode. Switch to server mode when you need: * Multiple agents writing simultaneously * Orchestrator multi-rig setups * Federation with remote peers [​](https://beads.gascity.com/architecture/dolt#maintenance-%E2%80%94-bd-prune-and-bd-purge) Maintenance — `bd prune` and `bd purge` --------------------------------------------------------------------------------------------------------------------------------------- `bd prune` permanently deletes closed non-ephemeral beads to reclaim storage and shrink auto-exports. `bd purge` does the same for ephemeral beads (wisps, transient molecules). Both require `--force` to execute. bd prune --older-than 30d # Preview closed beads >30d old bd prune --older-than 30d --force # Delete them bd prune --older-than 90d --dry-run # Detailed preview with stats bd purge --force # Delete all closed ephemeral beads **Reference-aware protection:** `bd prune` automatically skips closed beads whose ID appears in the description, notes, or comments of any open or in-progress bead. This prevents accidental deletion of ADR, decision, and verification beads that downstream work still cites. Use `--ignore-references` to override when cleaning up known-stale references: bd prune --older-than 90d --ignore-references --force `bd purge` is unaffected — ephemeral beads’ references are themselves transient. For full Dolt storage reclaim after deleting many rows, follow with `bd flatten`. [​](https://beads.gascity.com/architecture/dolt#migrating-between-backends) Migrating Between Backends --------------------------------------------------------------------------------------------------------- You can migrate data between embedded mode and server mode using `bd backup`. Both directions preserve full Dolt commit history. `bd export` is not a substitute for this flow. JSONL exports contain issue records from the issues table for migration and interoperability; they do not capture Dolt branches, full commit history, working-set state, or non-issue tables. Use `bd backup` or a manual Dolt backup when you need a restorable database backup. ### [​](https://beads.gascity.com/architecture/dolt#server-%E2%86%92-embedded) Server → Embedded 1. **Create a backup from the server-mode project:** # In the server-mode project directory bd backup init /path/to/backup-dir bd backup sync 2. **Create a new embedded-mode project and restore:** mkdir new-project && cd new-project bd init # creates an embedded-mode project by default bd backup restore --force /path/to/backup-dir `--force` overwrites the freshly-initialized database with the backup contents. The restore automatically: * Updates `metadata.json` to match the restored project identity * Registers the backup directory for future `bd backup sync` * Backfills the embedded migration tracker (`schema_migrations`) 3. **Verify:** bd list bd backup status ### [​](https://beads.gascity.com/architecture/dolt#embedded-%E2%86%92-server) Embedded → Server 1. **Create a backup from the embedded-mode project:** # In the embedded-mode project directory bd backup init /path/to/backup-dir bd backup sync 2. **Create a new server-mode project and restore:** mkdir new-project && cd new-project bd init --server # creates a server-mode project bd backup restore --force /path/to/backup-dir 3. **Verify:** bd list bd backup status ### [​](https://beads.gascity.com/architecture/dolt#backup-commands-reference) Backup Commands Reference | Command | Description | | --- | --- | | `bd backup init ` | Register a backup destination (filesystem or DoltHub URL) | | `bd backup sync` | Push database to the configured backup destination | | `bd backup restore [path]` | Restore from a backup directory (`--force` to overwrite) | | `bd backup remove` | Unregister the backup destination | | `bd backup status` | Show backup configuration and last sync time | ### [​](https://beads.gascity.com/architecture/dolt#notes) Notes * Data locations differ between modes: `.beads/embeddeddolt/` (embedded) vs `.beads/dolt/` (server) * The backup directory is a full Dolt backup, not an `issues.jsonl` export — it can be on a local drive, NAS, or DoltHub * You can also migrate via Dolt remotes (`bd dolt push` / `bd dolt pull`) if both projects share a remote The sections below are the canonical backend migration reference. [​](https://beads.gascity.com/architecture/dolt#federation-peer-to-peer-sync) Federation (Peer-to-Peer Sync) --------------------------------------------------------------------------------------------------------------- Federation lets independent Dolt-backed workspaces (“towns”) sync issues directly with each other via `bd federation add-peer`/`sync`/`status`, without a central hub. Credentials are AES-256 encrypted and stored locally. See [Federation Setup Guide](https://beads.gascity.com/multi-agent/federation) for the full setup guide, including peer configuration, sovereignty tiers, sync/status/topology details, and troubleshooting. [​](https://beads.gascity.com/architecture/dolt#dolt-remotes) Dolt Remotes ----------------------------------------------------------------------------- Use `bd dolt remote add` to configure remotes. This ensures the running Dolt SQL server sees the remote immediately. Remotes added directly with the `dolt` CLI are written to filesystem config and may not be visible to the server until restart. # DoltHub (public or private) bd dolt remote add origin https://doltremoteapi.dolthub.com/org/beads # S3 bd dolt remote add origin aws://[bucket]/path/to/repo # GCS bd dolt remote add origin gs://[bucket]/path/to/repo # Git SSH (GitHub, GitLab, etc.) bd dolt remote add origin git+ssh://git@github.com/org/repo.git # Local file system bd dolt remote add origin file:///path/to/remote ### [​](https://beads.gascity.com/architecture/dolt#push/pull) Push/Pull bd dolt push bd dolt pull `bd dolt remote add` registers the remote through the Dolt store API. SQL remotes are the source of truth for `bd dolt remote list`, `bd dolt push`, and `bd dolt pull`. For git-protocol remotes, credentialed external-server remotes, and cloud remotes whose credentials are only present in the current shell, `bd dolt push` and `bd dolt pull` automatically materialize a matching local CLI remote before using the `dolt` CLI transport. The CLI remote is a local transport mirror, not a separate configuration source. If you are upgrading from an older beads version and previously added remotes with raw `dolt remote add`, re-register them with `bd dolt remote add ` so they are visible through SQL. `bd doctor` reports legacy CLI-only or mismatched CLI remotes under `Dolt Remote Migration`. > **Sharing a Git repo**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs (`refs/heads/`, `refs/tags/`). You can safely point a `git+ssh://` remote at the same repository as your project source code. See [Dolt Git Remotes](https://docs.dolthub.com/concepts/dolt/git/remotes) > . ### [​](https://beads.gascity.com/architecture/dolt#list/remove-remotes) List/Remove Remotes bd dolt remote list # Shows SQL-configured remotes bd dolt remote remove origin # Removes the remote [​](https://beads.gascity.com/architecture/dolt#contributor-onboarding-clone-bootstrap) Contributor Onboarding (Clone Bootstrap) ----------------------------------------------------------------------------------------------------------------------------------- When someone clones a repository that uses Dolt backend: 1. Run `bd bootstrap` in the clone 2. If the git remote has `refs/dolt/data` (pushed via `bd dolt push`), `bd bootstrap` auto-detects it and clones the database from the remote 3. Work continues normally — all existing issues are available **No manual steps required** beyond `bd bootstrap`. The auto-detect: * Probes `origin` for `refs/dolt/data` * Clones the Dolt database from the remote (instead of creating a fresh one) * Configures the Dolt remote for future `bd dolt push`/`pull` If `sync.remote` is set in `.beads/config.yaml`, that takes precedence over auto-detection. Any Dolt-compatible remote URL is supported (DoltHub, S3, GCS, file, or git). On brand-new projects, `bd init` auto-detects `git origin` and persists it as `sync.remote`, so the first `bd dolt push` publishes Dolt history to `refs/dolt/data` on the same git remote. ### [​](https://beads.gascity.com/architecture/dolt#verifying-bootstrap-worked) Verifying Bootstrap Worked bd list # Should show issues bd vc status # Should show the current branch, no uncommitted changes [​](https://beads.gascity.com/architecture/dolt#troubleshooting) Troubleshooting ----------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/architecture/dolt#server-not-running) Server Not Running **Symptom:** Connection refused errors when using server mode. failed to create database: dial tcp 127.0.0.1:3307: connect: connection refused **Fix:** gt dolt start # Orchestrator command # Or gt dolt status # Check if running ### [​](https://beads.gascity.com/architecture/dolt#bootstrap-not-running) Bootstrap Not Running **Symptom:** `bd list` shows nothing on fresh clone. **Check:** ls .beads/dolt/ # Should NOT exist (pre-bootstrap) BD_DEBUG=1 bd list # See bootstrap output **Force bootstrap:** rm -rf .beads/dolt # Remove broken state bd list # Re-triggers bootstrap ### [​](https://beads.gascity.com/architecture/dolt#database-corruption) Database Corruption **Symptom:** Queries fail, inconsistent data. **Diagnosis:** bd doctor # Basic checks bd doctor --deep # Full validation bd doctor --server # Server mode checks (if applicable) **Recovery options:** 1. **Repair what’s fixable:** bd doctor --fix 2. **Rebuild from remote:** rm -rf .beads/dolt bd list # Re-triggers bootstrap ### [​](https://beads.gascity.com/architecture/dolt#already-committed-beads/dolt/-to-git) Already Committed `.beads/dolt/` to Git If you accidentally committed a Dolt data directory: 1. Update gitignore: `bd doctor --fix` 2. Remove it from git tracking: `git rm --cached -r .beads/dolt/` (or `.beads/embeddeddolt/`) 3. Commit the removal: `git commit -m "fix: remove accidentally committed dolt data"` 4. To purge from history, use [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/) or `git filter-repo` ### [​](https://beads.gascity.com/architecture/dolt#lock-contention-embedded-mode) Lock Contention (Embedded Mode) **Symptom:** “database is locked” errors. Embedded mode is single-writer (enforced via file lock). If you need concurrent access, switch to server mode. See [Migrating Between Backends](https://beads.gascity.com/architecture/dolt#migrating-between-backends) . [​](https://beads.gascity.com/architecture/dolt#configuration-reference) Configuration Reference --------------------------------------------------------------------------------------------------- # .beads/config.yaml # Dolt settings dolt: # Auto-commit Dolt history after writes (default: on for embedded, off for server) auto-commit: on # on | off # Storage mode (default: embedded) mode: embedded # embedded | server # Server mode settings (only used when mode: server) host: 127.0.0.1 port: 3307 user: root # Password: env var or credentials file (see below) # Shared server mode (GH#2377): all projects share a single Dolt server # at ~/.beads/shared-server/. Each project uses its own database (prefix-based). # Eliminates port conflicts and reduces resource usage on multi-project machines. shared-server: false # true | false ### [​](https://beads.gascity.com/architecture/dolt#environment-variables) Environment Variables | Variable | Purpose | | --- | --- | | `BEADS_DOLT_PASSWORD` | Server mode password (highest priority) | | `BEADS_CREDENTIALS_FILE` | Path to credentials file (overrides default location) | | `BEADS_DOLT_SERVER_MODE` | Enable server mode (set to “1”) | | `BEADS_DOLT_SERVER_HOST` | Server host (default: 127.0.0.1) | | `BEADS_DOLT_SERVER_PORT` | Server port (default: 3307, or 3308 in shared mode) | | `BEADS_DOLT_SERVER_TLS` | Enable TLS (set to “1” or “true”) | | `BEADS_DOLT_SERVER_USER` | MySQL connection user | | `BEADS_DOLT_SHARED_SERVER` | Enable shared server mode (set to “1” or “true”) | | `DOLT_REMOTE_USER` | Clone/push/pull auth user | | `DOLT_REMOTE_PASSWORD` | Clone/push/pull auth password | | `BD_DOLT_AUTO_COMMIT` | Override auto-commit setting | ### [​](https://beads.gascity.com/architecture/dolt#credentials-file) Credentials File For multi-server setups, you can store passwords in an INI-style credentials file instead of juggling environment variables per project. Passwords are looked up by `[host:port]` section, so each project automatically gets the right password based on its configured server. **Password resolution order:** 1. `BEADS_DOLT_PASSWORD` env var (highest priority, existing behavior) 2. Credentials file lookup by `[host:port]` (using the resolved runtime port) 3. Empty string (no password) **Port resolution note:** The `[host:port]` used for credential lookup matches the resolved runtime port (from the port file, env var, or config — in that priority order), not necessarily the port stored in `metadata.json`. This matters when using IAP tunnels: if your tunnel maps remote:3307 to localhost:3308, store your password under `[127.0.0.1:3308]` and the credentials file will match the actual connection. **Default location:** `~/.config/beads/credentials` (Linux/macOS), `%APPDATA%\beads\credentials` (Windows) **Override location:** Set `BEADS_CREDENTIALS_FILE` env var. **File format:** # ~/.config/beads/credentials [127.0.0.1:3307] password=localDevPassword [beads.company.com:3307] password=teamServerPassword [10.0.1.50:3308] password=officePassword **Permissions:** On Linux/macOS, a warning is printed to stderr if the file is readable by group or others (mirrors ssh behavior). Set permissions with: chmod 600 ~/.config/beads/credentials [​](https://beads.gascity.com/architecture/dolt#dolt-version-control) Dolt Version Control --------------------------------------------------------------------------------------------- Dolt maintains its own version history, separate from Git: # View an issue's version history across Dolt commits bd history bd-42 # Show current branch and uncommitted changes bd vc status # Create manual checkpoint bd vc commit -m "Checkpoint before refactor" ### [​](https://beads.gascity.com/architecture/dolt#auto-commit-behavior) Auto-Commit Behavior In **embedded mode** (standalone default), each `bd` write command creates a Dolt commit: bd create "New issue" # Creates issue + Dolt commit In **server mode** (orchestrator), auto-commit defaults to OFF because the server manages its own transaction lifecycle. Firing `DOLT_COMMIT` after every write under concurrent load causes ‘database is read only’ errors. Override for batch operations (embedded) or explicit commits (server): bd --dolt-auto-commit off create "Issue 1" bd --dolt-auto-commit off create "Issue 2" bd vc commit -m "Batch: created issues" [​](https://beads.gascity.com/architecture/dolt#server-management-orchestrator) Server Management (Orchestrator) ------------------------------------------------------------------------------------------------------------------- The orchestrator provides integrated Dolt server management: gt dolt start # Start server (background) gt dolt stop # Stop server gt dolt status # Show server status gt dolt logs # View server logs gt dolt sql # Open SQL shell Server runs on port 3307 (avoids MySQL conflict on 3306). ### [​](https://beads.gascity.com/architecture/dolt#standalone-to-managed-city-handoff) Standalone-to-managed-city handoff When an existing standalone project is later added to a managed city or orchestrator, avoid letting two Dolt servers become sources of truth for the same beads database name. A common split-brain symptom is that `.beads/dolt-server.port` points at the old standalone server while the shell environment points `bd` at the managed server with `BEADS_DOLT_PORT` or `BEADS_DOLT_SERVER_PORT`. Check before migrating: bd doctor bd dolt status `bd doctor` warns when the runtime managed port differs from the local port file. The warning is intentionally diagnostic only; do not delete the local port file until the standalone store has been exported and imported into the managed server. Safe manual handoff: # From the standalone project, without managed-city port overrides: unset BEADS_DOLT_PORT BEADS_DOLT_SERVER_PORT bd backup bd export > /tmp/beads-standalone.jsonl bd dolt stop # Then enter the managed-city environment and import into its Dolt server: bd import /tmp/beads-standalone.jsonl bd doctor After `bd doctor` shows one healthy store and the imported issue count is correct, archive the old local Dolt data directory instead of deleting it immediately. Keep the backup until the managed city has been pushed or otherwise snapshotted. ### [​](https://beads.gascity.com/architecture/dolt#shared-server-mode) Shared Server Mode On machines with multiple beads projects, each project normally starts its own Dolt server. Shared server mode runs a single Dolt server at `~/.beads/shared-server/` that serves all projects: # Enable for this project (config.yaml key) bd config set dolt.shared-server true # Or enable machine-wide via environment variable export BEADS_DOLT_SHARED_SERVER=1 # Or enable during init bd init --prefix myproject --shared-server **Benefits:** * No port conflicts between projects (single server on port 3308, avoids orchestrator on 3307) * Reduced resource usage (one process instead of many) * Automatic database isolation (each project uses its own database name) **How it works:** * Server state files (PID, port, lock, log) live in `~/.beads/shared-server/` * Dolt data directory: `~/.beads/shared-server/dolt/` * Each project’s database is stored as a subdirectory (e.g., `~/.beads/shared-server/dolt/myproject/`) * The file lock mechanism ensures safe concurrent access from multiple projects * Default port is 3308 (not 3307) to avoid conflict with the orchestrator. Override with `BEADS_DOLT_SERVER_PORT` or `dolt.port` in config.yaml **Important:** Each project on a shared server **must have a unique prefix** (database name). Two projects with the same prefix share the same database — if this happens accidentally, the project identity check will detect the mismatch and refuse to connect, preventing silent data corruption. Always use distinct prefixes when running `bd init --shared-server`. # Check shared server status from any project bd dolt status # Show full configuration including shared mode bd dolt show ### [​](https://beads.gascity.com/architecture/dolt#data-location-orchestrator) Data Location (Orchestrator) /.dolt-data/ ├── hq/ # Town beads (hq-*) ├── my-project/ # Project rig (mp-*) ├── beads/ # Beads rig (bd-*) └── other-project/ # Other rig (op-*) ### [​](https://beads.gascity.com/architecture/dolt#central-dolt-server-macos-launchagent) Central Dolt Server (macOS LaunchAgent) If you do not use the orchestrator but still want a single persistent Dolt server for multiple projects on macOS, run a custom `LaunchAgent` instead of spawning per-project embedded instances. #### [​](https://beads.gascity.com/architecture/dolt#why-not-brew-services-start-dolt) Why Not `brew services start dolt`? After installing Dolt with `brew install dolt`, the natural next step is `brew services start dolt`. However, the Homebrew formula runs `dolt sql-server` without the `--config` flag, and Dolt does not auto-discover `config.yaml` from its working directory. The config file must be passed explicitly with `--config `. #### [​](https://beads.gascity.com/architecture/dolt#setup-with-a-custom-launchagent) Setup with a Custom LaunchAgent Install Dolt and initialize its data directory: brew install dolt cd /opt/homebrew/var/dolt && dolt init Configure Dolt for port 3307: # /opt/homebrew/var/dolt/config.yaml log_level: info listener: host: 127.0.0.1 port: 3307 max_connections: 100 behavior: autocommit: true Create the LaunchAgent plist: cat > ~/Library/LaunchAgents/com.local.dolt-server.plist << 'EOF' Label com.local.dolt-server ProgramArguments /opt/homebrew/bin/dolt sql-server --config /opt/homebrew/var/dolt/config.yaml WorkingDirectory /opt/homebrew/var/dolt RunAtLoad KeepAlive StandardOutPath /opt/homebrew/var/log/dolt.log StandardErrorPath /opt/homebrew/var/log/dolt-error.log EOF Load and verify the service: launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist mysql -h 127.0.0.1 -P 3307 -u root -e "SELECT 1" Point beads at the central server: export BEADS_DOLT_SERVER_MODE=1 export BEADS_DOLT_SERVER_PORT=3307 Manage the service: # Stop launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist # Restart launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist # Check logs tail -f /opt/homebrew/var/log/dolt.log [​](https://beads.gascity.com/architecture/dolt#advanced-dolt-usage) Advanced Dolt Usage ------------------------------------------------------------------------------------------- The `dolt` CLI lets you operate directly on the database for power-user workflows. The data directory depends on your mode: `.beads/embeddeddolt/` (embedded) or `.beads/dolt/` (server). ### [​](https://beads.gascity.com/architecture/dolt#branching) Branching cd .beads/dolt # or .beads/embeddeddolt for embedded mode dolt branch feature-x dolt checkout feature-x ### [​](https://beads.gascity.com/architecture/dolt#time-travel) Time Travel dolt log dolt checkout dolt sql -q "SELECT * FROM issues" ### [​](https://beads.gascity.com/architecture/dolt#diff-and-blame) Diff and Blame dolt diff main feature-x dolt blame issues [​](https://beads.gascity.com/architecture/dolt#migration-cleanup) Migration Cleanup --------------------------------------------------------------------------------------- After successful migration from SQLite, you may have backup files: .beads/beads.backup-pre-dolt-20260122-213600.db .beads/sqlite.backup-pre-dolt-20260123-192812.db These are safe to delete once you’ve verified Dolt is working: # Verify Dolt works bd list bd doctor # Then clean up (after appropriate waiting period) rm .beads/*.backup-*.db **Recommendation:** Keep backups for at least a week before deleting. [​](https://beads.gascity.com/architecture/dolt#see-also) See Also --------------------------------------------------------------------- * [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts) - The conceptual model behind cross-machine sync (Dolt source of truth, wire format, anti-patterns) * [Sync Setup Guide](https://beads.gascity.com/getting-started/sync-setup) - Setting up sync across multiple computers * [Federation Setup Guide](https://beads.gascity.com/multi-agent/federation) - Peer-to-peer federation setup * [Configuration](https://beads.gascity.com/reference/configuration) - Full configuration reference * [Dependencies and Gates](https://beads.gascity.com/core-concepts/dependencies) - Dependencies and gates * [Git Integration](https://beads.gascity.com/reference/git-integration) - Git worktrees and protected branches * [Troubleshooting](https://beads.gascity.com/reference/troubleshooting) - General troubleshooting [Architecture Overview](https://beads.gascity.com/architecture) [Workflows](https://beads.gascity.com/workflows) ⌘I --- # Unknown \# 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 - \[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\](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 terminal form. - \[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. - \[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): Display information about the current database. - \[bd init\](https://beads.gascity.com/cli-reference/init.md): Initialize bd in the current directory by creating a .beads/ directory - \[bd init-safety\](https://beads.gascity.com/cli-reference/init-safety.md): bd init flag safety contract. - \[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\](https://beads.gascity.com/cli-reference/rename.md): Rename an issue from one ID to another. - \[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 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. - \[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 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 - \[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 - \[History Bloat\](https://beads.gascity.com/recovery/history-squash.md): Shed reachable Dolt history that dolt gc cannot reclaim - \[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 admin 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. --- # Architecture Overview - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/architecture#content-area) This document explains how Beads’ architecture works with Dolt as its storage backend: the storage layout, the data model, and the sync paths. For the concept model — beads, dependencies, ready work, molecules — see [How Beads Works](https://beads.gascity.com/core-concepts/index) . [​](https://beads.gascity.com/architecture#architecture) Architecture ------------------------------------------------------------------------ Beads uses **Dolt** as its sole storage backend — a version-controlled SQL database that provides git-like semantics (branch, merge, diff, push, pull) natively at the database level. By default, Dolt runs in **embedded mode** (in-process, no separate server). For multi-writer setups (multiple agents, orchestrator), switch to **server mode** which connects to a running `dolt sql-server`. See the [Dolt Server Mode](https://beads.gascity.com/architecture#dolt-server-mode) section below for details. **Source of Truth** **Dolt** is the source of truth. Every write auto-commits to Dolt history, providing full version control, branching, and merge capabilities at the database level.Recovery is straightforward: pull from a Dolt remote with `bd dolt pull`, or restore from a Dolt-native backup with `bd backup restore`. ### [​](https://beads.gascity.com/architecture#why-dolt) Why Dolt? * **Version-controlled SQL**: Full SQL queries with native version control * **Cell-level merge**: Concurrent changes merge automatically at the field level * **Multi-writer**: Server mode supports concurrent agents * **Native branching**: Dolt branches independent of git branches * **Works offline**: All queries run against local database * **Portable**: `bd export` produces JSONL for migration and interoperability [​](https://beads.gascity.com/architecture#data-model) Data Model -------------------------------------------------------------------- The database stores five kinds of records: issues (the beads themselves), dependencies (typed edges such as `blocks`, `parent-child`, `related`, and `discovered-from`), labels, comments, and events (the audit trail). What each means — and how `bd ready` computes the claimable frontier from them — is covered in [How Beads Works](https://beads.gascity.com/core-concepts/index) . Issue IDs are content-derived hashes (`bd-a1b2`) so that concurrent writers never collide and no central ID coordination is needed. See [Hash-based IDs](https://beads.gascity.com/core-concepts/hash-ids) for the design and [COLLISION\_MATH](https://github.com/gastownhall/beads/blob/main/engdocs/COLLISION_MATH.md) for the birthday-paradox analysis of hash length vs collision probability. ### [​](https://beads.gascity.com/architecture#issue-schema) Issue Schema Core fields on every issue, as stored in Dolt and emitted in `bd export` JSONL. Optional fields are omitted when empty. | Field | Type | Description | | --- | --- | --- | | `id` | string | Unique hash ID (e.g., `bd-a1b2`) | | `title` | string | Issue title (required) | | `description` | string | Detailed description (optional) | | `design` | string | Design notes (optional) | | `acceptance_criteria` | string | Acceptance criteria (optional) | | `notes` | string | Additional notes (optional) | | `status` | string | `open`, `in_progress`, `blocked`, `deferred`, `closed`, `pinned`, `hooked` (defaults to `open`; extendable via the `status.custom` config key) | | `priority` | int | 0–4, where 0 = critical and 4 = backlog | | `issue_type` | string | `bug`, `feature`, `task`, `epic`, `chore`, `decision`, `message`, `molecule`, `gate`, `spike`, `story`, `milestone` (defaults to `task`) | | `assignee` | string | Assigned user/agent (optional) | | `estimated_minutes` | int | Time estimate in minutes (optional) | | `created_at` / `updated_at` | RFC3339 | Creation and last-modification times | | `created_by` | string | Who created the issue (optional) | | `closed_at` / `close_reason` | RFC3339 / string | Set when the issue is closed (optional) | | `external_ref` | string | External reference such as `gh-9` or `jira-ABC` (optional) | | `metadata` | JSON | Arbitrary extension data — see [Issue Metadata](https://beads.gascity.com/core-concepts/metadata) | | `labels` | \[\]string | Tags attached to the issue (optional) | | `dependencies` | \[\]Dependency | Typed edges to other issues (optional) | | `comments` | \[\]Comment | Discussion thread (optional) | Issues also carry workflow-layer field groups, among others: scheduling (`due_at`, `defer_until`), claim leasing (`lease_expires_at`, `heartbeat_at`), gates (`await_type`, `await_id`, `timeout`), and molecule/wisp fields (`ephemeral`, `mol_type`, `bonded_from`). Internal fields — `content_hash` (a SHA-256 of the issue’s canonical content, used for change detection), `source_repo`, and `id_prefix` — never appear in exports. The schema is stable by default: prefer the `metadata` field for integration-, orchestrator-, or team-specific data before proposing new first-class fields. See the [Project Charter’s schema boundary](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md#schema-boundary) . [​](https://beads.gascity.com/architecture#data-flow) Data Flow ------------------------------------------------------------------ ### [​](https://beads.gascity.com/architecture#write-path) Write Path User runs bd create → Dolt database updated → Auto-committed to Dolt history ### [​](https://beads.gascity.com/architecture#read-path) Read Path User runs bd list → Dolt SQL query → Results returned immediately ### [​](https://beads.gascity.com/architecture#sync-path) Sync Path User runs bd dolt push → Commits pushed to Dolt remote User runs bd dolt pull → Remote commits fetched and merged Dolt remotes can live on DoltHub, S3, GCS, a filesystem path, or your existing git remote — issue history rides under `refs/dolt/data`, separate from code branches. See [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts) for the wire format and setup. Cross-repo setups can also exchange beads peer-to-peer via [federation](https://beads.gascity.com/multi-agent/federation) . Ephemeral [wisps](https://beads.gascity.com/workflows/wisps) are excluded from federation push by default, so execution traces never enter shared history. ### [​](https://beads.gascity.com/architecture#multi-machine-sync-considerations) Multi-Machine Sync Considerations When working across multiple machines or clones: 1. **Always sync before switching machines** bd dolt push # Push changes before leaving 2. **Pull before creating new issues** bd dolt pull # Pull changes first on new machine bd create "New issue" 3. **Avoid parallel edits** - If two machines create issues simultaneously without syncing, Dolt’s cell-level merge handles most conflicts automatically See [Sync Failures Recovery](https://beads.gascity.com/recovery/sync-failures) for data loss prevention in multi-machine workflows (Pattern A5/C3). [​](https://beads.gascity.com/architecture#dolt-server-mode) Dolt Server Mode -------------------------------------------------------------------------------- The Dolt server handles background synchronization and database operations: * Manages the Dolt database backend * Handles auto-commit for change tracking * Provides concurrent access for multiple agents * Runtime files live directly in `.beads/`: `dolt-server.pid`, `dolt-server.log`, and `dolt-server.port` An opt-in _shared server_ mode runs a single Dolt server at `~/.beads/shared-server/` for all projects, enabled with `dolt.shared-server: true` in `config.yaml` or `BEADS_DOLT_SHARED_SERVER=1` — see [Dolt Backend](https://beads.gascity.com/architecture/dolt#shared-server-mode) . Start the Dolt server with `bd dolt start`. Check health with `bd doctor`. ### [​](https://beads.gascity.com/architecture#embedded-mode-no-server) Embedded Mode (No Server) Embedded mode is the default (`bd init` with no flags): Dolt runs in-process, single-writer, with data at `.beads/embeddeddolt/` — no server process and no separate Dolt install. Server mode is opt-in via `bd init --server`; the choice is persisted in `.beads/metadata.json`. bd create "CI-generated issue" bd dolt push **Beyond solo use, embedded mode is a natural fit for:** * CI/CD pipelines (Jenkins, GitHub Actions) * Docker containers * Ephemeral environments * Scripts that should not leave background processes ### [​](https://beads.gascity.com/architecture#multi-clone-scenarios) Multi-Clone Scenarios **Race Conditions in Multi-Clone Workflows** When multiple git clones of the same repository run sync operations simultaneously, race conditions can occur during push/pull operations. This is particularly common in: * Multi-agent AI workflows (multiple Claude/GPT instances) * Developer workstations with multiple checkouts * Worktree-based development workflows **Prevention:** 1. Stop the Dolt server (`bd dolt stop`) before switching between clones 2. Dolt handles worktrees natively in server mode 3. Use embedded mode for automated workflows See [Sync Failures Recovery](https://beads.gascity.com/recovery/sync-failures) for sync race condition troubleshooting (Pattern B2). [​](https://beads.gascity.com/architecture#directory-layout) Directory Layout -------------------------------------------------------------------------------- .beads/ ├── embeddeddolt/ # Dolt database (embedded mode, default) — gitignored ├── dolt/ # Dolt database (server mode) — gitignored ├── dolt-server.pid # Server-mode runtime files (.pid, .log, .port) — gitignored ├── issues.jsonl # Passive JSONL export for viewers and interchange ├── metadata.json # Backend config — tracked in git └── config.yaml # Project config (optional) — tracked in git The database directory for your mode is the only thing holding issue data; everything else is configuration, runtime state, or a derived export. `bd init` writes a `.beads/.gitignore` that keeps the database and runtime files out of git. [​](https://beads.gascity.com/architecture#recovery-model) Recovery Model ---------------------------------------------------------------------------- Dolt’s version control makes recovery straightforward: 1. **Lost database?** → Pull from Dolt remote: `bd dolt pull` 2. **Have a backup?** → Restore it: `bd backup restore [path] --force` 3. **Merge conflicts?** → Dolt handles cell-level merge natively Create backups with `bd backup init` (a filesystem path or DoltHub destination) and push them with `bd backup sync`. Dolt-native backups preserve full commit history; a JSONL export does not. ### [​](https://beads.gascity.com/architecture#universal-recovery-sequence) Universal Recovery Sequence The following sequence resolves the majority of reported issues. For detailed procedures, see [Recovery Runbooks](https://beads.gascity.com/recovery/index) . bd dolt stop # Stop Dolt server (prevents race conditions) git worktree prune # Clean orphaned worktrees bd dolt pull # Pull from Dolt remote bd dolt start # Restart server **Use `bd doctor --fix` With Care** Always back up and preview before running `bd doctor --fix`: 1. **Back up first:** `cp -r .beads .beads.backup` 2. **Preview changes:** `bd doctor --dry-run` — shows what would be fixed without making changes 3. **Review diagnostics:** `bd doctor` (no flags) — diagnostic only, no changes made 4. **Then fix:** `bd doctor --fix` — or `bd doctor --fix -i` to confirm each fix individually **Why caution?** The `--fix` flag may remove dependencies it flags as circular, including valid parent-child relationships. Use `--fix-child-parent` only if you’re certain the flagged deps are invalid.**Other diagnostic tools:** * `bd blocked` — check which issues are blocked and why * `bd show ` — inspect a specific issue’s state See [Recovery](https://beads.gascity.com/recovery/index) for specific procedures and [Database Corruption Recovery](https://beads.gascity.com/recovery/database-corruption) for Dolt recovery steps. [​](https://beads.gascity.com/architecture#design-decisions) Design Decisions -------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/architecture#why-dolt-2) Why Dolt? Dolt is a version-controlled SQL database that provides git-like semantics natively. Unlike plain SQLite (binary merge conflicts) or JSONL (slow queries), Dolt gives you both fast SQL queries and proper merge semantics. ### [​](https://beads.gascity.com/architecture#why-not-a-cloud-server) Why not a cloud server? Beads is designed for offline-first, local-first development. The Dolt server runs locally — no cloud dependency, no downtime, no vendor lock-in, and full functionality on airplanes or in restricted networks. ### [​](https://beads.gascity.com/architecture#trade-offs) Trade-offs | Benefit | Trade-off | | --- | --- | | Works offline | No real-time collaboration | | Version-controlled database | Server mode needed for concurrent writers | | Cell-level merge | Requires initial setup | | Local-first speed | Manual sync to remotes | | SQL queries | Dolt storage engine dependency | ### [​](https://beads.gascity.com/architecture#when-not-to-use-beads) When NOT to use Beads Beads is not suitable for: * **Large teams (10+)** — Git-based sync doesn’t scale well for high-frequency concurrent edits * **Non-developers** — Requires Git and command-line familiarity * **Real-time collaboration** — No live updates; requires explicit sync * **Rich media attachments** — Designed for text-based issue tracking For these use cases, consider GitHub Issues, Linear, or Jira. [​](https://beads.gascity.com/architecture#related-documentation) Related Documentation ------------------------------------------------------------------------------------------ * [How Beads Works](https://beads.gascity.com/core-concepts/index) — The concept model: beads, dependencies, ready work, molecules * [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts) — Cross-machine sync, wire format, and anti-patterns * [Dolt Backend](https://beads.gascity.com/architecture/dolt) — Embedded vs server mode in depth, shared server, migration * [Recovery Runbooks](https://beads.gascity.com/recovery/index) — Step-by-step procedures for common issues * [CLI Reference](https://beads.gascity.com/cli-reference/index) — Complete command documentation * [Getting Started](https://beads.gascity.com/index) — Installation and first steps * [Project Charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md) — Product scope and boundaries (contributor doc) * [Internals](https://github.com/gastownhall/beads/blob/main/engdocs/INTERNALS.md) — Implementation details (contributor doc) [Issue Metadata](https://beads.gascity.com/core-concepts/metadata) [Dolt Backend for Beads](https://beads.gascity.com/architecture/dolt) ⌘I --- # Sourcegraph Cody - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/cody#content-area) Use Beads with Sourcegraph Cody through a project rules file. bd setup cody bd setup cody --check The setup command creates `.cody/rules/beads.md` with Beads workflow guidance. [​](https://beads.gascity.com/integrations/cody#remove) Remove ----------------------------------------------------------------- bd setup cody --remove [Codex](https://beads.gascity.com/integrations/codex) [Cursor](https://beads.gascity.com/integrations/cursor) ⌘I --- # Windsurf - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/windsurf#content-area) Use Beads with Windsurf through a project rules file. bd setup windsurf bd setup windsurf --check The setup command creates `.windsurf/rules/beads.md` with Beads workflow guidance. [​](https://beads.gascity.com/integrations/windsurf#remove) Remove --------------------------------------------------------------------- bd setup windsurf --remove [OpenCode](https://beads.gascity.com/integrations/opencode) [MCP Server](https://beads.gascity.com/integrations/mcp-server) ⌘I --- # OpenCode - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/opencode#content-area) Use Beads with OpenCode through managed `AGENTS.md` guidance. bd setup opencode bd setup opencode --check The setup command creates or updates `AGENTS.md` with a managed Beads section. Restart OpenCode after setup if it is already running. [​](https://beads.gascity.com/integrations/opencode#remove) Remove --------------------------------------------------------------------- bd setup opencode --remove [Mux](https://beads.gascity.com/integrations/mux) [Windsurf](https://beads.gascity.com/integrations/windsurf) ⌘I --- # Kilo Code - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/kilocode#content-area) Use Beads with Kilo Code through a project rules file. bd setup kilocode bd setup kilocode --check The setup command creates `.kilocode/rules/beads.md` with Beads workflow guidance. [​](https://beads.gascity.com/integrations/kilocode#remove) Remove --------------------------------------------------------------------- bd setup kilocode --remove [Junie](https://beads.gascity.com/integrations/junie) [Mux](https://beads.gascity.com/integrations/mux) ⌘I --- # Related Projects - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/related-projects#content-area) Adjacent or complementary tools that solve different problems in the same neighborhood as Beads. These are not Beads integrations (see [Community Tools](https://beads.gascity.com/community-tools) for those) — they are independent projects whose users may also find Beads useful, or vice versa. [​](https://beads.gascity.com/related-projects#recall-/-knowledge-graph) Recall / knowledge graph ---------------------------------------------------------------------------------------------------- * **[scry](https://github.com/prmichaelsen/scry) ** — ([scryspec.com](https://scryspec.com/) ) — marker-indexed knowledge and recall graph for AI coding agents. Files declare identity via inline `@scry.entry` markers; the index makes designs, lessons, and decisions reachable by meaning, tag, and seeded question rather than by path. Different job from Beads: where Beads is a task graph for _what to do next_, scry is a recall layer for _what was decided and why_. They compose — independently arrived at the same hash-based-ID convention (`bd-a1b2`, `~hash`) for the same reason: preventing collisions across multi-agent and multi-branch work. [Community Tools](https://beads.gascity.com/community-tools) [Reference](https://beads.gascity.com/reference) ⌘I --- # Factory.ai Droid - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/factory#content-area) Use Beads with Factory.ai Droid through managed `AGENTS.md` guidance. bd setup factory bd setup factory --check The setup command creates or updates `AGENTS.md` with a managed Beads section. Factory Droid reads `AGENTS.md` automatically when it starts a session. [​](https://beads.gascity.com/integrations/factory#remove) Remove -------------------------------------------------------------------- bd setup factory --remove [Cursor](https://beads.gascity.com/integrations/cursor) [Gemini CLI](https://beads.gascity.com/integrations/gemini) ⌘I --- # Gemini CLI - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/gemini#content-area) Use Beads with Gemini CLI through SessionStart hooks and `GEMINI.md` guidance. bd setup gemini bd setup gemini --check By default, setup installs global hooks in `~/.gemini/settings.json`. For project-local hooks, use: bd setup gemini --project The hook runs `bd prime --hook-json` so Gemini receives compact Beads workflow context at session start. The setup also writes Beads guidance to `GEMINI.md`. [​](https://beads.gascity.com/integrations/gemini#stealth-mode) Stealth Mode ------------------------------------------------------------------------------- For CI or other environments where setup should avoid git operations: bd setup gemini --stealth bd setup gemini --project --stealth [​](https://beads.gascity.com/integrations/gemini#remove) Remove ------------------------------------------------------------------- bd setup gemini --remove bd setup gemini --project --remove [Factory.ai Droid](https://beads.gascity.com/integrations/factory) [Junie](https://beads.gascity.com/integrations/junie) ⌘I --- # Mux - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/mux#content-area) Use Beads with Mux through `AGENTS.md`, optional layered Mux instruction files, and Mux hooks. bd setup mux bd setup mux --check The default setup writes a managed Beads section to root `AGENTS.md`. [​](https://beads.gascity.com/integrations/mux#workspace-and-global-layers) Workspace and Global Layers ---------------------------------------------------------------------------------------------------------- Mux also supports workspace and global instruction layers: bd setup mux --project bd setup mux --global bd setup mux --project --global Project setup writes `.mux/AGENTS.md` and installs Mux hook files under `.mux/`: * `.mux/init` * `.mux/tool_post` * `.mux/tool_env` Global setup writes `~/.mux/AGENTS.md`. [​](https://beads.gascity.com/integrations/mux#remove) Remove ---------------------------------------------------------------- bd setup mux --remove bd setup mux --project --remove bd setup mux --global --remove [Kilo Code](https://beads.gascity.com/integrations/kilocode) [OpenCode](https://beads.gascity.com/integrations/opencode) ⌘I --- # Cursor - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/cursor#content-area) Use Beads with Cursor through a project rules file that keeps the workflow guidance in front of the agent every turn. bd setup cursor bd setup cursor --check `bd setup cursor` installs **`.cursor/rules/beads.mdc`** — an always-applied rule with the canonical Beads workflow guidance (the same content every other editor integration uses), so it stays in sync as the workflow evolves. Because it is always applied, Cursor re-includes it every turn, including after a context compaction. Restart Cursor after installing so the rule loads. [​](https://beads.gascity.com/integrations/cursor#verifying-it-works) Verifying it works ------------------------------------------------------------------------------------------- bd setup cursor --check In a session, the agent should know your bd workflow without being told — ask it what work is ready and it should run `bd ready`. If it doesn’t, confirm `.cursor/rules/beads.mdc` exists and restart Cursor. After a context compaction, have the agent run `bd prime` to restore the workflow context, ready work, and project memories. [​](https://beads.gascity.com/integrations/cursor#remove) Remove ------------------------------------------------------------------- bd setup cursor --remove This removes the rules file while leaving the rest of `.cursor/` intact. [​](https://beads.gascity.com/integrations/cursor#related) Related --------------------------------------------------------------------- * [IDE Setup](https://beads.gascity.com/getting-started/ide-setup) — all editor integrations * [Claude Code](https://beads.gascity.com/integrations/claude-code) * [Codex](https://beads.gascity.com/integrations/codex) [Sourcegraph Cody](https://beads.gascity.com/integrations/cody) [Factory.ai Droid](https://beads.gascity.com/integrations/factory) ⌘I --- # Integrations - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations#content-area) Beads integration pages are based on two sources of support in the repository: * Built-in `bd setup` recipes from `internal/recipes/recipes.go` * First-party MCP integrations and editor guides already shipped in the repo Run this command to see the built-in setup recipes supported by your installed `bd` binary: bd setup --list [​](https://beads.gascity.com/integrations#built-in-setup-recipes) Built-in Setup Recipes -------------------------------------------------------------------------------------------- | Recipe | Integration | Primary setup surface | | --- | --- | --- | | `aider` | [Aider](https://beads.gascity.com/integrations/aider) | `.aider.conf.yml` and `.aider/` instructions | | `claude` | [Claude Code](https://beads.gascity.com/integrations/claude-code) | Claude hooks and `CLAUDE.md` | | `codex` | [Codex](https://beads.gascity.com/integrations/codex) | Beads skill, `AGENTS.md`, and Codex hooks | | `cody` | [Sourcegraph Cody](https://beads.gascity.com/integrations/cody) | `.cody/rules/beads.md` | | `cursor` | [Cursor](https://beads.gascity.com/integrations/cursor) | `.cursor/rules/beads.mdc` + `.cursor/hooks.json` | | `factory` | [Factory.ai Droid](https://beads.gascity.com/integrations/factory) | `AGENTS.md` | | `gemini` | [Gemini CLI](https://beads.gascity.com/integrations/gemini) | Gemini hooks and `GEMINI.md` | | `junie` | [Junie](https://beads.gascity.com/integrations/junie) | `.junie/guidelines.md` and MCP config | | `kilocode` | [Kilo Code](https://beads.gascity.com/integrations/kilocode) | `.kilocode/rules/beads.md` | | `mux` | [Mux](https://beads.gascity.com/integrations/mux) | `AGENTS.md`, optional `.mux/AGENTS.md`, and Mux hooks | | `opencode` | [OpenCode](https://beads.gascity.com/integrations/opencode) | `AGENTS.md` | | `windsurf` | [Windsurf](https://beads.gascity.com/integrations/windsurf) | `.windsurf/rules/beads.md` | [​](https://beads.gascity.com/integrations#mcp-based-integrations) MCP-Based Integrations -------------------------------------------------------------------------------------------- These integrations use the Beads MCP server rather than a dedicated `bd setup` recipe: * [MCP Server](https://beads.gascity.com/integrations/mcp-server) — the beads MCP server for any MCP-capable client. * [GitHub Copilot](https://beads.gascity.com/integrations/github-copilot) — Copilot in VS Code via MCP. * [GitHub Copilot CLI](https://beads.gascity.com/integrations/copilot-cli) — the Copilot coding-agent CLI. [​](https://beads.gascity.com/integrations#other-integration-surfaces) Other Integration Surfaces ---------------------------------------------------------------------------------------------------- * [Claude Code Plugin](https://beads.gascity.com/integrations/claude-code-plugin) — the packaged plugin with slash commands and MCP tools (`/plugin install beads`). * [Azure DevOps](https://beads.gascity.com/integrations/azure-devops) — configuration reference for syncing beads with ADO work items. [Multi-Repo Migration Guide](https://beads.gascity.com/multi-agent/multi-repo-migration) [Aider](https://beads.gascity.com/integrations/aider) ⌘I --- # Circular Dependencies - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/recovery/circular-dependencies#content-area) This runbook helps you detect and break circular dependency cycles in your issues. [​](https://beads.gascity.com/recovery/circular-dependencies#symptoms) Symptoms ---------------------------------------------------------------------------------- * “circular dependency detected” errors * `bd blocked` shows unexpected results * Issues that should be ready appear blocked [​](https://beads.gascity.com/recovery/circular-dependencies#diagnosis) Diagnosis ------------------------------------------------------------------------------------ # Check for blocked issues bd blocked # View dependencies for a specific issue bd show # List all dependencies bd dep tree [​](https://beads.gascity.com/recovery/circular-dependencies#solution) Solution ---------------------------------------------------------------------------------- **Step 1:** Identify the cycle bd blocked --verbose **Step 2:** Map the dependency chain bd show bd show # Follow the chain until you return to **Step 3:** Determine which dependency to remove Consider: Which dependency is least critical to the workflow? **Step 4:** Remove the problematic dependency bd dep remove **Step 5:** Verify the cycle is broken bd blocked bd ready [​](https://beads.gascity.com/recovery/circular-dependencies#prevention) Prevention -------------------------------------------------------------------------------------- * Think “X needs Y” not “X before Y” when adding dependencies * Use `bd blocked` after adding dependencies to check for cycles * Keep dependency chains shallow when possible [Merge Conflicts](https://beads.gascity.com/recovery/merge-conflicts) [Sync Failures](https://beads.gascity.com/recovery/sync-failures) ⌘I --- # Recovery Overview - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/recovery#content-area) This section provides step-by-step recovery procedures for common Beads issues. Each runbook follows a consistent format: Symptoms, Diagnosis, Solution (5 steps max), and Prevention. [​](https://beads.gascity.com/recovery#common-issues) Common Issues ---------------------------------------------------------------------- | Issue | Symptoms | Runbook | | --- | --- | --- | | Init Safety Refusals | `bd init` or `bd dolt` refuses with a pattern code like `pk-fork-refused` | [Recovery Playbooks](https://beads.gascity.com/recovery/init-safety) | | Database Corruption | Database errors, missing data | [Database Corruption](https://beads.gascity.com/recovery/database-corruption) | | Merge Conflicts | Dolt conflicts during sync | [Merge Conflicts](https://beads.gascity.com/recovery/merge-conflicts) | | Circular Dependencies | Cycle detection errors | [Circular Dependencies](https://beads.gascity.com/recovery/circular-dependencies) | | Sync Failures | `bd dolt push`/`bd dolt pull` errors | [Sync Failures](https://beads.gascity.com/recovery/sync-failures) | | History Bloat | Store grows unbounded; `dolt gc` reclaims nothing | [History Bloat](https://beads.gascity.com/recovery/history-squash) | | Removing beads | Uninstall bd or strip beads from a repo | [Uninstalling](https://beads.gascity.com/recovery/uninstalling) | [​](https://beads.gascity.com/recovery#quick-diagnostic) Quick Diagnostic ---------------------------------------------------------------------------- Before diving into specific runbooks, try these quick checks: # Check Beads status bd status # Verify Dolt server is running bd doctor # Check for blocked issues bd blocked Most issues can be diagnosed with `bd status`. Start there before following specific runbooks. [​](https://beads.gascity.com/recovery#getting-help) Getting Help -------------------------------------------------------------------- If these runbooks don’t resolve your issue: 1. Check the [FAQ](https://beads.gascity.com/reference/faq) 2. Search [existing issues](https://github.com/gastownhall/beads/issues) 3. Open a new issue with diagnostic output [TODO Command](https://beads.gascity.com/workflows/todo) [Recovery Playbooks](https://beads.gascity.com/recovery/init-safety) ⌘I --- # Database Corruption - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/recovery/database-corruption#content-area) This runbook helps you recover from database corruption in Beads. [​](https://beads.gascity.com/recovery/database-corruption#symptoms) Symptoms -------------------------------------------------------------------------------- * Error messages during `bd` commands * “database is locked” errors that persist * Missing issues that should exist * Inconsistent database state [​](https://beads.gascity.com/recovery/database-corruption#diagnosis) Diagnosis ---------------------------------------------------------------------------------- # Check database integrity bd doctor # Check Dolt server health bd dolt show [​](https://beads.gascity.com/recovery/database-corruption#solution) Solution -------------------------------------------------------------------------------- **Step 1:** Stop the Dolt server bd dolt stop **Step 2:** Back up current state cp -r .beads .beads.backup **Step 3:** Preview what doctor would fix bd doctor --dry-run **Step 4:** Rebuild database bd doctor --fix **Step 5:** Verify recovery bd doctor bd list **Step 6:** Restart the Dolt server dolt sql-server [​](https://beads.gascity.com/recovery/database-corruption#prevention) Prevention ------------------------------------------------------------------------------------ * Let the Dolt server handle synchronization * Use `bd dolt stop` before system shutdown * Run `bd doctor` periodically to catch issues early [Recovery Playbooks](https://beads.gascity.com/recovery/init-safety) [Merge Conflicts](https://beads.gascity.com/recovery/merge-conflicts) ⌘I --- # Multi-Agent - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/multi-agent#content-area) Beads supports coordination between multiple AI agents and repositories. [​](https://beads.gascity.com/multi-agent#overview) Overview --------------------------------------------------------------- Multi-agent features enable: * **Routing** - Automatic issue routing to correct repositories * **Cross-repo dependencies** - Dependencies across repository boundaries * **Agent coordination** - Work assignment and handoff between agents [​](https://beads.gascity.com/multi-agent#key-concepts) Key Concepts ----------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent#routing) Routing Routing decides which repository a new bead lands in, based on your role (contributor vs maintainer) and the `routing.*` config keys — an explicit `--repo` flag always wins. See [Multi-Repo Routing](https://beads.gascity.com/multi-agent/routing) for the decision flow and configuration reference. ### [​](https://beads.gascity.com/multi-agent#work-assignment) Work Assignment Assign or atomically claim work: bd assign bd-42 agent-1 # shorthand for bd update bd-42 --assignee agent-1 bd update bd-42 --claim # atomically set assignee + in_progress bd ready --claim --json # claim the first ready match ### [​](https://beads.gascity.com/multi-agent#cross-repo-dependencies) Cross-repo Dependencies Track dependencies across repositories: bd dep add bd-42 external:other-repo:api-ready [​](https://beads.gascity.com/multi-agent#architecture) Architecture ----------------------------------------------------------------------- ┌─────────────────┐ │ Main Repo │ │ (coordinator) │ └────────┬────────┘ │ routes ┌────┴────┐ │ │ ┌───▼───┐ ┌───▼───┐ │Frontend│ │Backend│ │ Repo │ │ Repo │ └────────┘ └────────┘ [​](https://beads.gascity.com/multi-agent#getting-started) Getting Started ----------------------------------------------------------------------------- 1. **Single repo**: Standard beads workflow 2. **Multi-repo**: Configure routes and cross-repo deps 3. **Multi-agent**: Add work assignment and handoff [​](https://beads.gascity.com/multi-agent#pages-in-this-section) Pages in this section ----------------------------------------------------------------------------------------- * [Routing](https://beads.gascity.com/multi-agent/routing) — automatic issue routing across repositories and `BEADS_DIR` resolution. * [Coordination](https://beads.gascity.com/multi-agent/coordination) — work assignment and handoff patterns between agents. * [Federation](https://beads.gascity.com/multi-agent/federation) — peer-to-peer sharing of beads across repos and organizations. * [Multi-Repo Migration](https://beads.gascity.com/multi-agent/multi-repo-migration) — moving an existing single-repo setup to multi-repo routing. [Uninstalling](https://beads.gascity.com/recovery/uninstalling) [Multi-Repo Routing](https://beads.gascity.com/multi-agent/routing) ⌘I --- # Merge Conflicts - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/recovery/merge-conflicts#content-area) This runbook helps you resolve merge conflicts that occur during Dolt sync operations. [​](https://beads.gascity.com/recovery/merge-conflicts#symptoms) Symptoms ---------------------------------------------------------------------------- * `bd dolt pull` fails with conflict errors * Different issue states between clones [​](https://beads.gascity.com/recovery/merge-conflicts#diagnosis) Diagnosis ------------------------------------------------------------------------------ # Check database health bd doctor # Preview what fixes would be applied bd doctor --dry-run [​](https://beads.gascity.com/recovery/merge-conflicts#solution) Solution ---------------------------------------------------------------------------- **Step 1:** Back up current state cp -r .beads .beads.backup **Step 2:** Check for conflicts bd doctor **Step 3:** Fix to reconcile bd doctor --fix **Step 4:** Verify state bd list bd stats **Step 5:** Push resolved state bd dolt push [​](https://beads.gascity.com/recovery/merge-conflicts#prevention) Prevention -------------------------------------------------------------------------------- * Sync before and after work sessions using `bd dolt pull` / `bd dolt push` * Avoid concurrent modifications from multiple clones without the Dolt server running [Database Corruption](https://beads.gascity.com/recovery/database-corruption) [Circular Dependencies](https://beads.gascity.com/recovery/circular-dependencies) ⌘I --- # Sync Concepts - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/core-concepts/sync-concepts#content-area) Beads issue data lives in Dolt. The local Dolt database is the source of truth for `bd list`, `bd show`, `bd ready`, and every write command. [​](https://beads.gascity.com/core-concepts/sync-concepts#the-wire-format) The Wire Format --------------------------------------------------------------------------------------------- Cross-machine sync uses Dolt remotes: bd dolt push bd dolt pull For normal git-hosted projects, the Dolt remote can be the same `origin` URL used for source code. Dolt stores issue history under `refs/dolt/data`, separate from source branches such as `refs/heads/main`. On new projects, `bd init` auto-detects `git remote get-url origin` and configures a Dolt remote named `origin`. The first `bd dolt push` publishes `refs/dolt/data`. Fresh clones should run `bd bootstrap` to clone that Dolt history. When bootstrap finds `refs/dolt/data` on git origin, it also wires that origin as the Dolt remote for future `bd dolt push` and `bd dolt pull`. [​](https://beads.gascity.com/core-concepts/sync-concepts#what-jsonl-is-for) What JSONL Is For ------------------------------------------------------------------------------------------------- `.beads/issues.jsonl` is an export. It exists for viewers, interchange, migration, and backup. It is not the canonical cross-machine sync channel. Do not use routine `bd import .beads/issues.jsonl` as a replacement for `bd dolt pull`. JSONL import is upsert-only; it cannot infer that records absent from an export were deleted, pruned, or simply never exported. [​](https://beads.gascity.com/core-concepts/sync-concepts#hooks) Hooks ------------------------------------------------------------------------- The pre-commit hook refreshes `.beads/issues.jsonl` when `export.auto=true`. That keeps the export current for tools, but it does not push Dolt history. The post-merge and post-checkout hooks skip JSONL import when `sync.remote` is configured. For old projects with no Dolt remote, they may import JSONL as a compatibility fallback and print a warning that this is not durable sync. [​](https://beads.gascity.com/core-concepts/sync-concepts#repair) Repair --------------------------------------------------------------------------- For projects initialized before automatic git-origin remote wiring, pick the machine with the authoritative local Dolt database first. Then run: bd dolt remote list bd export -o .beads/issues.pre-remote.jsonl # optional issue audit export bd dolt remote add origin bd dolt push Use the Dolt-compatible git URL form when needed. For example, `git+ssh://git@github.com/org/repo.git` or `git+https://github.com/org/repo.git`. `bd dolt remote add origin ...` persists `sync.remote` into `.beads/config.yaml`; commit and push that config change so fresh clones can run `bd bootstrap`. Other machines should then run: bd dolt pull # or, if the local database is stale or missing: bd bootstrap [Graph Links in Beads](https://beads.gascity.com/core-concepts/graph-links) [Labels](https://beads.gascity.com/core-concepts/labels) ⌘I --- # Codex - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/codex#content-area) Use Beads with Codex through the `beads` skill, managed `AGENTS.md` guidance, and native Codex hooks. bd setup codex bd setup codex --check Project setup writes: * `.agents/skills/beads/` for the Beads skill. * `AGENTS.md` with a managed Beads section. * `.codex/config.toml` with `[features].hooks = true`. * `.codex/hooks.json` with the Beads hook fallback. `bd init` runs this project setup by default unless `--skip-agents` or `--stealth` is used. Global setup uses `bd setup codex --global` and writes under `$CODEX_HOME` when set, otherwise `~/.codex`. Codex 0.129.0+ supports `/hooks`, compact lifecycle hooks, and hook-provided developer context. Beads uses that lifecycle to inject `bd prime` on session start and recover context after compaction. Use `/hooks` to inspect or toggle the installed handlers. [​](https://beads.gascity.com/integrations/codex#hook-lifecycle) Hook Lifecycle ---------------------------------------------------------------------------------- * `SessionStart` (`startup|resume|clear`) injects full `bd prime` output. * `PreCompact` (`manual|auto`) checks `bd prime --memories-only` and warns if Beads context is unavailable. * `PostCompact` (`manual|auto`) records that the session needs a Beads refresh. * `UserPromptSubmit` injects full `bd prime` once after compaction, then clears the refresh marker. `PreCompact` alone does not inject context because Codex ignores plain stdout from compact hooks. The post-compact marker plus first-prompt refresh is the reliable recovery path. Refresh markers are stored in a user cache/temp directory keyed by Codex `session_id` and workspace path. They are not written to tracked files or to the Beads database. The Beads Codex plugin stores hooks at `plugins/beads/.codex-plugin/hooks/hooks.json` and declares them in `plugins/beads/.codex-plugin/plugin.json` as `"hooks": "./.codex-plugin/hooks/hooks.json"`. Without the plugin, `bd setup codex` installs the same hook config in `.codex/hooks.json` and enables `[features].hooks = true`. [​](https://beads.gascity.com/integrations/codex#manual-fallback) Manual Fallback ------------------------------------------------------------------------------------ If you manage `.codex/hooks.json` by hand instead of running `bd setup codex`, the equivalent shape is: { "hooks": { "SessionStart": [\ {\ "matcher": "startup|resume|clear",\ "hooks": [{ "type": "command", "command": "bd codex-hook SessionStart", "statusMessage": "Loading Beads context" }]\ }\ ], "PreCompact": [\ {\ "matcher": "manual|auto",\ "hooks": [{ "type": "command", "command": "bd codex-hook PreCompact", "statusMessage": "Checking Beads context" }]\ }\ ], "PostCompact": [\ {\ "matcher": "manual|auto",\ "hooks": [{ "type": "command", "command": "bd codex-hook PostCompact", "statusMessage": "Scheduling Beads context refresh" }]\ }\ ], "UserPromptSubmit": [\ {\ "hooks": [{ "type": "command", "command": "bd codex-hook UserPromptSubmit", "statusMessage": "Refreshing Beads context" }]\ }\ ] } } Then ensure `.codex/config.toml` enables: [features] hooks = true [Beads Claude Code Plugin](https://beads.gascity.com/integrations/claude-code-plugin) [Sourcegraph Cody](https://beads.gascity.com/integrations/cody) ⌘I --- # Sync Failures - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/recovery/sync-failures#content-area) This runbook helps you recover from Dolt sync failures. [​](https://beads.gascity.com/recovery/sync-failures#symptoms) Symptoms -------------------------------------------------------------------------- * `bd dolt push` or `bd dolt pull` hangs or times out * Network-related error messages * “failed to push” or “failed to pull” errors * Dolt server not responding [​](https://beads.gascity.com/recovery/sync-failures#diagnosis) Diagnosis ---------------------------------------------------------------------------- # Check Dolt server health bd doctor bd dolt show # View Dolt server logs tail -50 .beads/dolt-server.log # server mode [​](https://beads.gascity.com/recovery/sync-failures#solution) Solution -------------------------------------------------------------------------- **Step 1:** Stop the Dolt server bd dolt stop **Step 2:** Check for lock files ls -la .beads/*.lock # Remove stale locks if Dolt server is definitely stopped rm -f .beads/*.lock **Step 3:** Back up and preview fixes cp -r .beads .beads.backup bd doctor --dry-run **Step 4:** Apply fixes if needed bd doctor --fix **Step 5:** Restart the Dolt server dolt sql-server **Step 6:** Verify sync works bd dolt push bd doctor [​](https://beads.gascity.com/recovery/sync-failures#common-causes) Common Causes ------------------------------------------------------------------------------------ | Cause | Solution | | --- | --- | | Network timeout | Retry with better connection | | Stale lock file | Remove lock after stopping Dolt server | | Corrupted state | Back up, then `bd doctor --fix` | | Merge conflicts | See [Merge Conflicts](https://beads.gascity.com/recovery/merge-conflicts) | [​](https://beads.gascity.com/recovery/sync-failures#prevention) Prevention ------------------------------------------------------------------------------ * Ensure stable network before sync * Let sync complete before closing terminal * Use `bd dolt stop` before system shutdown [Circular Dependencies](https://beads.gascity.com/recovery/circular-dependencies) [History Bloat](https://beads.gascity.com/recovery/history-squash) ⌘I --- # Wisps - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/workflows/wisps#content-area) Operational workflows — release checklists, health patrols, diagnostics — create beads that are worthless the moment they close. **Wisps** are molecules instantiated in the _vapor phase_: real beads you work through normally, flagged `Ephemeral=true` so they stay out of sync and can be deleted wholesale later. [​](https://beads.gascity.com/workflows/wisps#what-are-wisps) What are Wisps? -------------------------------------------------------------------------------- * Issues in the main database with the ephemeral flag set — worked on with normal `bd` commands. * Local by design: excluded from federation push by default (`federation.exclude_types` defaults to `[wisp]`) and not part of the shared audit trail. * Deleted in bulk by `bd purge` or `bd mol wisp gc` once closed. [​](https://beads.gascity.com/workflows/wisps#wisp-vs-pour) Wisp vs Pour --------------------------------------------------------------------------- | Aspect | Molecule (`bd mol pour`) | Wisp (`bd mol wisp`) | | --- | --- | --- | | Persistence | permanent, part of history | ephemeral, purged when done | | Sync | synced like any bead | excluded from federation push | | Use case | feature work, anything worth referencing later | release runs, operational loops, health checks | Formulas can declare `phase = "vapor"` to recommend wisp instantiation — pouring a vapor-phase formula warns. [​](https://beads.gascity.com/workflows/wisps#the-wisp-lifecycle) The Wisp Lifecycle --------------------------------------------------------------------------------------- # 1. Create — from a proto, or ad-hoc bd mol wisp [--var key=value] bd create "One-off check" --ephemeral # 2. Execute — normal bd operations work on wisp issues bd ready --mol bd update --claim bd close # 3a. Keep it after all: squash promotes to persistent (clears the flag) bd mol squash # 3b. Or burn: delete without creating a digest bd mol burn [​](https://beads.gascity.com/workflows/wisps#managing-wisps) Managing Wisps ------------------------------------------------------------------------------- bd mol wisp list # list all wisps in the current context bd mol wisp gc # garbage collect old/abandoned wisps bd purge --force # delete all closed ephemeral beads [​](https://beads.gascity.com/workflows/wisps#forcing-a-phase) Forcing a Phase --------------------------------------------------------------------------------- `bd mol bond` accepts phase overrides when combining work: bd mol bond mol-critical-bug wisp-patrol --pour # persist a bug found during a patrol [​](https://beads.gascity.com/workflows/wisps#best-practices) Best Practices ------------------------------------------------------------------------------- 1. **Wisps for operational loops** — patrols, release runs, diagnostics. 2. **Molecules for tracked work** — anything with audit value gets poured, not wisped. 3. **Squash before you delete** — if a wisp surfaced something durable, `bd mol squash` promotes it; burning is irreversible. 4. **Garbage collect regularly** — `bd mol wisp gc` or `bd purge --force`. [Gates](https://beads.gascity.com/workflows/gates) [TODO Command](https://beads.gascity.com/workflows/todo) ⌘I --- # Workflows - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/workflows#content-area) Repeatable multi-step work — a release checklist, a feature pipeline, a review process — shouldn’t be re-planned by hand every time. Beads lets you declare the shape once and instantiate it on demand: a **formula** (TOML source) is cooked into a **proto** (template), and the proto is poured into a **molecule** — real beads whose steps flow through `bd ready` like any other work. The full pipeline is diagrammed in [How Beads Works](https://beads.gascity.com/core-concepts/index) . bd formula list # formulas visible on the search paths bd cook release.formula.toml # compile the formula into a proto bd mol pour release --var version=1.2.0 # instantiate real work bd ready --mol # which steps can run right now The three phases, in the chemistry metaphor the CLI uses: | Phase | What it is | Lifecycle | | --- | --- | --- | | **Proto** (solid) | template epic with `{{variables}}`, carries the `template` label | reusable, not live work | | **Molecule** (liquid) | persistent beads poured from a proto (`bd mol pour`) | synced like any bead | | **Wisp** (vapor) | ephemeral instantiation (`bd mol wisp`) | excluded from federation push by default; deleted by `bd purge` | [​](https://beads.gascity.com/workflows#pages-in-this-section) Pages in this section --------------------------------------------------------------------------------------- * [Molecules](https://beads.gascity.com/workflows/molecules) — instantiated work graphs: pouring, inspecting, bonding, and squashing molecules. * [Formulas](https://beads.gascity.com/workflows/formulas) — the TOML/JSON source format: steps, `needs` dependencies, variables, and composition rules. * [Gates](https://beads.gascity.com/workflows/gates) — async wait conditions (human, timer, GitHub run/PR, cross-rig bead) that park a step until the world catches up. * [Wisps](https://beads.gascity.com/workflows/wisps) — ephemeral molecules for transient operational work that shouldn’t clutter history. * [TODO Command](https://beads.gascity.com/workflows/todo) — `bd todo`, the lightweight interface for managing TODO items as task beads. [Dolt Backend for Beads](https://beads.gascity.com/architecture/dolt) [Molecules](https://beads.gascity.com/workflows/molecules) ⌘I --- # Workflows - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/workflows/index#content-area) Repeatable multi-step work — a release checklist, a feature pipeline, a review process — shouldn’t be re-planned by hand every time. Beads lets you declare the shape once and instantiate it on demand: a **formula** (TOML source) is cooked into a **proto** (template), and the proto is poured into a **molecule** — real beads whose steps flow through `bd ready` like any other work. The full pipeline is diagrammed in [How Beads Works](https://beads.gascity.com/core-concepts/index) . bd formula list # formulas visible on the search paths bd cook release.formula.toml # compile the formula into a proto bd mol pour release --var version=1.2.0 # instantiate real work bd ready --mol # which steps can run right now The three phases, in the chemistry metaphor the CLI uses: | Phase | What it is | Lifecycle | | --- | --- | --- | | **Proto** (solid) | template epic with `{{variables}}`, carries the `template` label | reusable, not live work | | **Molecule** (liquid) | persistent beads poured from a proto (`bd mol pour`) | synced like any bead | | **Wisp** (vapor) | ephemeral instantiation (`bd mol wisp`) | excluded from federation push by default; deleted by `bd purge` | [​](https://beads.gascity.com/workflows/index#pages-in-this-section) Pages in this section --------------------------------------------------------------------------------------------- * [Molecules](https://beads.gascity.com/workflows/molecules) — instantiated work graphs: pouring, inspecting, bonding, and squashing molecules. * [Formulas](https://beads.gascity.com/workflows/formulas) — the TOML/JSON source format: steps, `needs` dependencies, variables, and composition rules. * [Gates](https://beads.gascity.com/workflows/gates) — async wait conditions (human, timer, GitHub run/PR, cross-rig bead) that park a step until the world catches up. * [Wisps](https://beads.gascity.com/workflows/wisps) — ephemeral molecules for transient operational work that shouldn’t clutter history. * [TODO Command](https://beads.gascity.com/workflows/todo) — `bd todo`, the lightweight interface for managing TODO items as task beads. [Dolt Backend for Beads](https://beads.gascity.com/architecture/dolt) [Molecules](https://beads.gascity.com/workflows/molecules) ⌘I --- # Issue Metadata - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/core-concepts/metadata#content-area) The `metadata` field on issues accepts arbitrary JSON. Any valid JSON value is stored as-is. Metadata is the preferred extension point for data that is specific to an integration, orchestrator, team workflow, or experimental automation. Before adding first-class fields, commands, or schema changes, check the [Project Charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md#schema-boundary) . [​](https://beads.gascity.com/core-concepts/metadata#example-agent-execution-metadata) Example: Agent Execution Metadata --------------------------------------------------------------------------------------------------------------------------- Agent execution hints are one example of using metadata to extend beads without adding new native database fields. Automation may store these hints so agents can make routing decisions without parsing prose. Agents enacting an issue should read metadata first, then use description and notes for scope and rationale: bd show --json | jq '.[0] | {id,title,metadata,description,notes}' The current convention for execution hint keys is: | Key | Meaning | | --- | --- | | `execution_agent_type` | Suggested worker class, such as `explorer`, `worker`, or `mixed`. | | `execution_suggested_model` | Suggested model for the parent agent or spawned subagent. | | `execution_reasoning_effort` | Suggested reasoning effort, such as `low`, `medium`, `high`, or `xhigh`. | | `execution_mode` | Whether work should be local, delegated, or staged between delegated and local execution. | | `execution_parallel_group` | Grouping hint for work that can run alongside related tasks. | These keys are advisory metadata, not core issue fields. When a workflow uses them, they take precedence over free-form notes for execution routing. Notes remain useful for rationale, ownership, and exact prompts. Model and effort values are portable hints, not runtime bindings. The `execution_reasoning_effort` values above are a canonical advisory scale: writers should store canonical values rather than runtime-local ones, and a consumer whose runtime uses a different scale should map the stored value to its nearest native level instead of dropping the hint. Likewise, `execution_suggested_model` is a capability-tier suggestion: a consumer on a different provider should substitute a model of the same tier rather than ignore the hint. Parent/orchestrator agents must consume these keys before spawning subagents. Model and reasoning effort are normally fixed at launch, so reading metadata after delegation is too late. Do not add a first-class helper such as `bd show --execution` or `bd plan --json`. Issue gh-3541 resolved to keep execution hints as metadata only; the JSON/JQ snippet remains the supported access path. [​](https://beads.gascity.com/core-concepts/metadata#example-tracker-round-trip-metadata) Example: Tracker Round-Trip Metadata --------------------------------------------------------------------------------------------------------------------------------- Tracker integrations map external issues into beads fields such as title, status, priority, type, labels, dependencies, and `external_ref`. When an integration needs to preserve tracker-specific fields that do not belong in the native beads schema, it can store those fields in issue metadata: { "example_tracker": { "board_id": "ENG", "sprint_id": 42, "remote_type": "story" } } This keeps beads’ core issue model stable while allowing the integration to round-trip fields it understands. Prefer namespaced keys and keep tracker-specific policy in the integration. If a value becomes broadly useful to beads itself, revisit whether it deserves a native field. [​](https://beads.gascity.com/core-concepts/metadata#reserved-key-prefixes) Reserved Key Prefixes ---------------------------------------------------------------------------------------------------- | Prefix | Reserved For | | --- | --- | | `bd:` | Beads internal use | | `_` | Internal/private keys | Avoid these prefixes in user-defined keys to prevent conflicts with future Beads features. [​](https://beads.gascity.com/core-concepts/metadata#related) Related ------------------------------------------------------------------------ * [Project Charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md) - Product scope and schema boundary * [#1416](https://github.com/gastownhall/beads/issues/1416) - Optional schema enforcement (future) [Labels](https://beads.gascity.com/core-concepts/labels) [Architecture Overview](https://beads.gascity.com/architecture) ⌘I --- # GitHub Copilot CLI Integration Design - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/copilot-cli#content-area) This document explains design decisions for GitHub Copilot CLI integration in beads. For **VS Code + MCP**, see [GitHub Copilot](https://beads.gascity.com/integrations/github-copilot) . [​](https://beads.gascity.com/integrations/copilot-cli#integration-approach) Integration Approach ---------------------------------------------------------------------------------------------------- **Recommended: Copilot CLI plugin + repository instructions** - Beads uses Copilot CLI’s native plugin manifest plus repository instructions: * `.copilot-plugin/plugin.json` registers `bd prime` hooks natively * `.github/copilot-instructions.md` provides repository-specific workflow guidance * Direct CLI commands with `--json` flags remain the primary operational interface **Alternative: VS Code MCP** - For Copilot Chat in the editor: * Native tool calling through MCP * Higher context overhead from tool schemas * Use when you want editor-native tool access instead of terminal-first workflow [​](https://beads.gascity.com/integrations/copilot-cli#why-plugin-+-instructions-over-custom-setup-code) Why Plugin + Instructions Over Custom Setup Code? ------------------------------------------------------------------------------------------------------------------------------------------------------------- **The plugin manifest already models the behavior we want:** 1. **Hooks belong in the tool’s native format** * Copilot CLI understands plugin manifests directly * `SessionStart` and `PreCompact` can be declared as data instead of custom Go logic * This keeps beads core smaller and easier to maintain 2. **Instructions stay explicit and reviewable** * Repository guidance still lives in `.github/copilot-instructions.md` * Teams can review the instructions like any other project documentation * The hook behavior and the human-readable guidance stay separate 3. **Lower maintenance burden** * No Copilot-specific install/check/remove implementation in core * No Copilot-specific doctor checks * The recipe just writes the native plugin file and the instruction file [​](https://beads.gascity.com/integrations/copilot-cli#why-copilot-cli-over-mcp-for-terminal-work) Why Copilot CLI Over MCP for Terminal Work? ------------------------------------------------------------------------------------------------------------------------------------------------- **Context efficiency still matters**, even with large context windows: 1. **Compute cost scales with tokens** - Every token in context is processed on every inference 2. **Latency increases with context** - Smaller prompts keep the CLI more responsive 3. **Energy consumption** - Lean prompts are more sustainable over long sessions 4. **Attention quality** - Models generally perform better with tighter, more relevant context **The math:** * MCP tool schemas can add 10-50k tokens to context * `bd prime` adds ~1-2k tokens of workflow context * That is an order-of-magnitude reduction in overhead [​](https://beads.gascity.com/integrations/copilot-cli#installation) Installation ------------------------------------------------------------------------------------ # Install the Copilot CLI plugin manifest + repository instructions bd setup copilot # Check installation status bd setup copilot --check # Remove the integration bd setup copilot --remove **What it installs:** * `.copilot-plugin/plugin.json` * `SessionStart` hook: Runs `bd prime` when Copilot CLI starts a session * `PreCompact` hook: Runs `bd prime` before context compaction * `.github/copilot-instructions.md` * Repository workflow guidance for Copilot CLI [​](https://beads.gascity.com/integrations/copilot-cli#related-files) Related Files -------------------------------------------------------------------------------------- * `plugins/beads/.copilot-plugin/plugin.json` - Source plugin manifest for the shared plugin package * `plugins/beads/copilot_manifest.go` - Embedded manifest source used by `bd setup copilot` * `internal/recipes/recipes.go` - Lightweight `copilot` recipe definition * `internal/recipes/template.go` - Static Copilot instructions template used by `bd setup` * [GitHub Copilot integration](https://beads.gascity.com/integrations/github-copilot) - VS Code MCP integration [​](https://beads.gascity.com/integrations/copilot-cli#references) References -------------------------------------------------------------------------------- * [GitHub Copilot CLI docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) * [Adding repository custom instructions for GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/add-custom-instructions) [GitHub Copilot](https://beads.gascity.com/integrations/github-copilot) [Azure DevOps (ADO) Integration Configuration](https://beads.gascity.com/integrations/azure-devops) ⌘I --- # History Bloat - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/recovery/history-squash#content-area) Every bead write mints a Dolt commit, and Dolt keeps every byte a reachable commit references — `dolt gc` only reclaims what nothing points to. A workspace that has accumulated months of high-frequency writes can grow far past its live data (gigabytes of storage for a few thousand beads) while `dolt gc` reclaims nothing, because the entire chain is still reachable from your branch. This runbook squashes that chain to a single baseline commit so the old history becomes collectable, without touching your live data. This procedure rewrites history. Every other clone of the database becomes unmergeable and must re-clone, and remotes and backups must be re-pointed. Run it in a fenced window: all writers stopped **on every machine that syncs this database**, backup verified first. [​](https://beads.gascity.com/recovery/history-squash#symptoms) Symptoms --------------------------------------------------------------------------- * The Dolt data directory (or its remote/backup) is large and growing while `bd stats` shows a modest number of beads * `dolt gc` and `dolt gc --full` reclaim little or nothing * Cloning or pulling the database is slow far out of proportion to its content [​](https://beads.gascity.com/recovery/history-squash#diagnosis) Diagnosis ----------------------------------------------------------------------------- Run these inside the Dolt data directory — `.beads/embeddeddolt//` in embedded mode, `.beads/dolt//` in server mode: # How big is the store? du -sh . # How deep is the history? Thousands of commits with a small live # dataset means the history, not the data, is the bloat. dolt log --oneline | wc -l # Confirm gc has nothing unreachable to collect dolt gc --full If `dolt gc --full` frees the space, you are done — no squash needed. [​](https://beads.gascity.com/recovery/history-squash#solution) Solution --------------------------------------------------------------------------- **Step 1:** Fence and back up. Stop every writer: agents, background services, and — easiest to miss — any scheduled sync job (cron, launchd, systemd) that pushes or pulls this database, on _every machine that syncs it_, not just the one you squash on. List the machines and their sync units by name and verify each is stopped. One live peer sync undoes the squash on its next tick: it pulls the new baseline, cross-merges it into its old chain, and pushes the entire old history back to the fresh remote. In server mode also stop the server after backing up. The backup is dolt-native and keeps the full history, so it remains your rollback. bd backup sync bd dolt stop **Step 2:** Squash to a single baseline. From the Dolt data directory, re-commit the current tree directly on top of the root commit. Keeping the root as the sole ancestor preserves a valid chain — do not try to “simplify” further by starting an orphan branch: root=$(dolt log --oneline | tail -1 | cut -d' ' -f1) dolt reset --soft "$root" dolt add -A dolt commit -m "history squash: baseline $(date +%F)" **Step 3:** Drop the other refs and collect. Anything still pointing at the old chain keeps it alive — stale local branches and tags, and also the _remote-tracking refs_ left behind by every past push and fetch, which any long-lived synced workspace has. Delete them all before collecting; Step 4’s force-push recreates the remote-tracking refs on the new chain: dolt branch # delete stale branches: dolt branch -D dolt branch -r # delete remote-tracking refs: dolt branch -rd / dolt tag # delete stale tags: dolt tag -d dolt gc --full du -sh . # verify: the store should now be a fraction of its old size If the size barely moved, a ref still anchors the old chain — re-check `dolt branch`, `dolt branch -r`, and `dolt tag` for survivors and collect again. (A failed collection does not endanger Step 4 — the push sends only what the new baseline references — but this machine keeps the bloat until the gc succeeds.) **Step 4:** Re-point remotes and backups. The new history is unrelated to the old, so the first publish must replace it: bd dolt push --force bd backup remove && bd backup init # fresh destination, then: bd backup sync A Dolt remote accumulates chunks monotonically: the force-push re-points the remote’s refs at the squashed chain but deletes nothing, so the _remote’s_ storage does not shrink. To reclaim the published side too, replace the remote — clear its storage (or pick a fresh path/prefix) before the push: `bd dolt remote remove `, `bd dolt remote add `, then `bd dolt push --force`. Every other clone must re-clone after a squash regardless, so replacing the remote costs nothing extra. **Step 5:** Verify, then re-clone everywhere else. On this machine: bd doctor bd list -n 5 Every other clone of this database must be re-created from the squashed remote. Old clones must not pull: the two chains still share the root, so a pull can “succeed” as a cross-merge that re-anchors the entire old history — and a later push resurrects the bloat on the squashed remote. Re-enable each machine’s sync jobs only after that machine has re-cloned; unfence your writers last. [​](https://beads.gascity.com/recovery/history-squash#prevention) Prevention ------------------------------------------------------------------------------- High-frequency coordination state lives in unversioned tables precisely so routine agent traffic does not mint history — claim leases and [wisps](https://beads.gascity.com/workflows/wisps) — so bloat at this scale usually means something is writing versioned tables in a tight loop. Find and fix that writer, watch data-directory growth over time, and run `dolt gc` periodically so unreachable garbage never accumulates on top of reachable history. [Sync Failures](https://beads.gascity.com/recovery/sync-failures) [Uninstalling](https://beads.gascity.com/recovery/uninstalling) ⌘I --- # Protected Branches - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference/protected-branches#content-area) Beads does not need a protected-branch workaround in current releases. Issue data is stored in Dolt under `refs/dolt/data`, separate from normal Git branches such as `main`. Beads commands do not commit issue updates to your current code branch, so GitHub, GitLab, and Bitbucket branch protection rules continue to apply only to your code history. [​](https://beads.gascity.com/reference/protected-branches#current-workflow) Current Workflow ------------------------------------------------------------------------------------------------ Initialize beads in the project: bd init Commit the small tracked configuration files if your project policy requires them: git add .beads/.gitignore .beads/metadata.json .beads/config.yaml .gitignore git commit -m "Initialize beads issue tracker" The local Dolt database directory remains gitignored. Sync issue data through a Dolt remote: bd dolt pull bd dolt push No `beads-sync` Git branch, protected-branch exception, or beads-managed Git worktree is required. [​](https://beads.gascity.com/reference/protected-branches#why-protected-branches-are-safe) Why Protected Branches Are Safe ------------------------------------------------------------------------------------------------------------------------------ Protected branches guard Git refs such as `refs/heads/main`. Dolt stores beads data in its own ref namespace. That means: * `bd create`, `bd update`, and `bd close` do not create commits on `main`. * `bd dolt push` pushes Dolt data, not a code branch. * Normal code changes still go through your existing pull-request workflow. [​](https://beads.gascity.com/reference/protected-branches#team-usage) Team Usage ------------------------------------------------------------------------------------ For a shared tracker: bd init --team bd dolt pull bd ready bd update --claim bd dolt push Pull before starting work and push before handing off so other clones see the latest issue state. [​](https://beads.gascity.com/reference/protected-branches#legacy-sync-branch-cleanup) Legacy Sync-Branch Cleanup -------------------------------------------------------------------------------------------------------------------- Older beads versions documented an experimental `sync.branch` workflow that committed `.beads` changes to a branch such as `beads-sync` and used hidden Git worktrees under `.git/beads-worktrees/`. That workflow has been removed. If an old checkout still has sync-branch config, clear it: bd config set sync.branch "" If stale hidden worktrees prevent branch checkout, remove them and prune Git’s worktree registry: rm -rf .git/beads-worktrees rm -rf .git/worktrees/beads-* git worktree prune If a remote `beads-sync` branch exists only for the removed workflow, archive or delete it according to your repository policy after confirming all current issue data has been synced through Dolt. [​](https://beads.gascity.com/reference/protected-branches#troubleshooting) Troubleshooting ---------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/protected-branches#bd-dolt-push-has-no-remote) `bd dolt push` Has No Remote Add or inspect the Dolt remote: bd dolt remote list bd dolt remote add origin bd dolt push ### [​](https://beads.gascity.com/reference/protected-branches#conflicts-during-bd-dolt-pull) Conflicts During `bd dolt pull` Dolt reports database-level conflicts separately from Git branch conflicts. Use the merge strategy or doctor guidance printed by the failed command: bd vc merge --strategy [ours|theirs] bd doctor --fix ### [​](https://beads.gascity.com/reference/protected-branches#stale-hooks-mention-legacy-sync-commands) Stale Hooks Mention Legacy Sync Commands Refresh generated hooks: bd hooks install [​](https://beads.gascity.com/reference/protected-branches#see-also) See Also -------------------------------------------------------------------------------- * [Git Worktrees Guide](https://beads.gascity.com/reference/worktrees) - Git worktree behavior * [Git Integration](https://beads.gascity.com/reference/git-integration) - general Git integration guide * [Recovery Playbooks](https://beads.gascity.com/recovery/init-safety) - recovery playbooks [Git Worktrees Guide](https://beads.gascity.com/reference/worktrees) [Advanced Features](https://beads.gascity.com/reference/advanced) ⌘I --- # Uninstalling - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/recovery/uninstalling#content-area) This guide explains how to remove beads from a repository or remove the `bd` binary from a machine. [​](https://beads.gascity.com/recovery/uninstalling#before-you-remove-data) Before You Remove Data ----------------------------------------------------------------------------------------------------- Removing `.beads/` permanently deletes the local Dolt database. If the issue history matters, make a Dolt-native backup first: bd backup init /path/to/beads-backup bd backup sync For review, migration, or interoperability, you can also write an issue-table export: bd export -o ~/beads-issues-$(date +%Y%m%d).jsonl `bd export` is not a complete restorable database backup. It does not preserve Dolt branches, commit history, working-set state, or non-issue tables. [​](https://beads.gascity.com/recovery/uninstalling#repository-reset) Repository Reset ----------------------------------------------------------------------------------------- Use `bd admin reset` from the repository root. It previews what will be removed by default: bd admin reset If the preview is correct, run: bd admin reset --force This removes beads-managed repository data such as: * the `.beads/` directory * beads-managed git hook sections * legacy beads sync worktrees under `.git/beads-worktrees/` [​](https://beads.gascity.com/recovery/uninstalling#remove-hooks-only) Remove Hooks Only ------------------------------------------------------------------------------------------- To keep issue data but remove git hooks: bd hooks uninstall This is preferable to manually deleting hook files because beads preserves unrelated user hook content outside its managed hook markers. [​](https://beads.gascity.com/recovery/uninstalling#manual-cleanup) Manual Cleanup ------------------------------------------------------------------------------------- Use manual cleanup only if `bd admin reset` is unavailable or cannot run in the repository. # Stop a local Dolt server if one is running. bd dolt stop 2>/dev/null || true # Remove beads-managed hooks when bd hooks uninstall is unavailable. rm -f .git/hooks/pre-commit rm -f .git/hooks/prepare-commit-msg rm -f .git/hooks/post-merge rm -f .git/hooks/pre-push rm -f .git/hooks/post-checkout # Remove the local beads database and config. rm -rf .beads # Remove legacy sync-branch worktrees from older beads versions. rm -rf .git/beads-worktrees git worktree prune If `.gitattributes` contains only beads merge-driver configuration, remove it. If it contains other project entries, edit out only the beads line. If beads-specific git config remains, remove it: git config --unset beads.role 2>/dev/null || true git config --unset merge.beads.driver 2>/dev/null || true git config --unset merge.beads.name 2>/dev/null || true [​](https://beads.gascity.com/recovery/uninstalling#remove-the-bd-binary) Remove the `bd` Binary --------------------------------------------------------------------------------------------------- The CLI is a standalone binary. Remove it according to how it was installed: # Homebrew brew uninstall beads # Go install rm -f "$(which bd)" # Manual install location rm -f /usr/local/bin/bd If you installed the MCP package separately, remove that package with the tool you used to install it. [​](https://beads.gascity.com/recovery/uninstalling#verify-removal) Verify Removal ------------------------------------------------------------------------------------- which bd test ! -e .beads bd hooks list 2>/dev/null || true git config --get merge.beads.driver [​](https://beads.gascity.com/recovery/uninstalling#reinstall-later) Reinstall Later --------------------------------------------------------------------------------------- To initialize beads again: bd init [History Bloat](https://beads.gascity.com/recovery/history-squash) [Multi-Agent](https://beads.gascity.com/multi-agent) ⌘I --- # Git Worktrees Guide - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference/worktrees#content-area) Beads works from normal Git worktrees without a separate sync branch. Current beads stores issue data in Dolt under `refs/dolt/data`, so issue sync is separate from Git branch commits. [​](https://beads.gascity.com/reference/worktrees#current-model) Current Model --------------------------------------------------------------------------------- All worktrees in the same repository use the same beads workspace unless you override discovery with `BEADS_DIR`. project/ ├── .git/ # Shared Git directory ├── .beads/ # Shared beads config and local Dolt data ├── main-worktree/ └── feature-worktree/ Key points: * `bd` discovers the repository’s `.beads` directory from linked worktrees. * Issue changes are stored in Dolt, not committed to the current Git branch. * Cross-clone sync uses `bd dolt pull` and `bd dolt push`. * No `sync.branch` or beads-managed Git worktree is required. [​](https://beads.gascity.com/reference/worktrees#basic-usage) Basic Usage ----------------------------------------------------------------------------- Initialize beads once in the repository: cd project bd init Create linked worktrees normally: git worktree add ../project-feature feature-branch cd ../project-feature bd ready bd create "Implement feature X" -t feature -p 1 Sync issue data through the configured Dolt remote: bd dolt pull bd dolt push [​](https://beads.gascity.com/reference/worktrees#external-beads-workspace) External Beads Workspace ------------------------------------------------------------------------------------------------------- If you want a separate issue-tracker repository shared by many code worktrees, point `BEADS_DIR` at that workspace: export BEADS_DIR=~/project-beads/.beads cd ~/project/main && bd list cd ~/project/feature-1 && bd list cd ~/project/feature-2 && bd list With an external `BEADS_DIR`, `bd dolt push` and `bd dolt pull` target the external beads workspace, not the code repository. [​](https://beads.gascity.com/reference/worktrees#hooks) Hooks ----------------------------------------------------------------- Git hooks installed by beads are worktree-aware. If hooks are stale or mention removed legacy sync commands, refresh them: bd hooks install [​](https://beads.gascity.com/reference/worktrees#legacy-cleanup) Legacy Cleanup ----------------------------------------------------------------------------------- Older beads versions had an experimental `sync.branch` workflow that created hidden worktrees such as `.git/beads-worktrees//`. That workflow has been removed. If a legacy checkout cannot switch branches because a beads-created worktree still holds the branch, remove the stale worktree records: rm -rf .git/beads-worktrees rm -rf .git/worktrees/beads-* git worktree prune If old config still contains a sync branch, clear it: bd config set sync.branch "" [​](https://beads.gascity.com/reference/worktrees#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/worktrees#database-not-found-in-a-worktree) Database Not Found In A Worktree Check that the main repository has a `.beads` directory and that the worktree belongs to that repository: git worktree list cd /path/to/main/repo ls -la .beads If the repository has no beads workspace yet, run `bd init` from the main repository. ### [​](https://beads.gascity.com/reference/worktrees#multiple-beads-directories) Multiple `.beads` Directories If a worktree has its own accidental `.beads` directory, remove or archive the extra copy after confirming it does not contain unique issue data. By default, worktrees should share the repository workspace. ### [​](https://beads.gascity.com/reference/worktrees#concurrent-writers) Concurrent Writers For ordinary single-user worktree use, run commands directly. For true multi-writer workflows across machines or agents, sync frequently with `bd dolt pull` and `bd dolt push`, and coordinate through the tracker to avoid working the same issue concurrently. [​](https://beads.gascity.com/reference/worktrees#see-also) See Also ----------------------------------------------------------------------- * [Protected Branches](https://beads.gascity.com/reference/protected-branches) - protected branch behavior * [Git Integration](https://beads.gascity.com/reference/git-integration) - general Git integration guide * [Multi-Repo Migration Guide](https://beads.gascity.com/multi-agent/multi-repo-migration) - multi-workspace patterns [Git Integration](https://beads.gascity.com/reference/git-integration) [Protected Branches](https://beads.gascity.com/reference/protected-branches) ⌘I --- # Reference - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference#content-area) Lookup material for beads: the pages here specify contracts and edge cases rather than teach concepts (that’s [How Beads Works](https://beads.gascity.com/core-concepts/index) ). [​](https://beads.gascity.com/reference#pages-in-this-section) Pages in this section --------------------------------------------------------------------------------------- * [Configuration](https://beads.gascity.com/reference/configuration) — every config key, environment variable, default, and the precedence between them. * [Git Integration](https://beads.gascity.com/reference/git-integration) — hooks, `refs/dolt/data`, role detection, and branchless (jujutsu) workflows. * [Git Worktrees Guide](https://beads.gascity.com/reference/worktrees) — how beads behaves across worktrees sharing one repository. * [Protected Branches](https://beads.gascity.com/reference/protected-branches) — sync-branch mode for repos where direct pushes to main are blocked. * [Advanced Features](https://beads.gascity.com/reference/advanced) — rename, merge, compaction, and other power-user operations. * [JSON Output Schema Contract](https://beads.gascity.com/reference/json-schema) — the stability contract behind every `--json` flag. * [Observability (OpenTelemetry)](https://beads.gascity.com/reference/observability) — traces and metrics bd can emit, and how to point them at a collector. * [Troubleshooting](https://beads.gascity.com/reference/troubleshooting) — symptom-first fixes for common failures (deeper runbooks live in [Recovery](https://beads.gascity.com/recovery/index) ). * [Antivirus False Positives](https://beads.gascity.com/reference/antivirus) — Windows AV heuristics and binary verification. * [FAQ](https://beads.gascity.com/reference/faq) — beads vs other trackers, and the questions everyone asks in week one. * [CLI Reference](https://beads.gascity.com/cli-reference/index) — the generated page-per-command reference, nested below as a collapsible group. [Related Projects](https://beads.gascity.com/related-projects) [Configuration](https://beads.gascity.com/reference/configuration) ⌘I --- # Gates - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/workflows/gates#content-area) Some workflow steps can’t proceed on code alone: a release needs CI to go green, a deploy needs a human sign-off, a cleanup should wait 24 hours. A **gate** is an issue that represents that wait. It blocks a step the same way any blocker does — the step leaves the ready frontier until the gate closes — so agents never need to poll or spin. [​](https://beads.gascity.com/workflows/gates#how-a-gate-works) How a gate works ----------------------------------------------------------------------------------- A gate is a bead like any other: created open, it blocks its waiters through a normal dependency edge, and the step becomes ready the moment the gate closes. Gates close in one of two ways: * **Manually** — `bd gate resolve ` (human gates always close this way). * **Via `bd gate check`** — evaluates open timer and GitHub gates against the real world and closes the ones whose condition is met. bd gate list # open gates bd gate list --all # include closed bd gate show # details and waiters bd gate check # evaluate open gates, close satisfied ones bd gate check --dry-run # report without closing bd gate resolve # close a gate manually [​](https://beads.gascity.com/workflows/gates#gate-types) Gate types ----------------------------------------------------------------------- | Type | Waits for | Closed by | | --- | --- | --- | | `human` | a person’s decision | `bd gate resolve` only | | `timer` | a duration after gate creation | `bd gate check` once the timeout elapses | | `gh:run` | a GitHub Actions workflow to complete successfully | `bd gate check` (uses `gh run view`) | | `gh:pr` | a pull request to merge | `bd gate check` (uses `gh pr view`) | | `bead` | a bead in another rig to close | currently unresolvable — multi-rig routing was removed, so `bd gate check` reports these gates as uncheckable | Timeouts use Go duration syntax: `30m`, `1h`, `24h` (there is no `d` unit — write `24h`, not `1d`). [​](https://beads.gascity.com/workflows/gates#gates-in-formulas) Gates in formulas ------------------------------------------------------------------------------------- A formula step declares a gate with a `[steps.gate]` block. When the formula is instantiated, bd creates the gate issue and wires it as a blocker of that step. The schema has four fields: `type`, `id`, `await_id`, and `timeout`. This is the release gate from beads’ own release formula — the step that waits for the GitHub release workflow: [[steps]] id = "wait-for-ci" title = "Wait for release workflow" [steps.gate] type = "gh:run" id = "release.yml" # which workflow to watch timeout = "30m" # escalate if it takes longer A human sign-off gate: [[steps]] id = "approve-deploy" title = "Human approves the deploy" [steps.gate] type = "human" And a cooling-off timer: [[steps]] id = "wait-24h" title = "Let the release bake" [steps.gate] type = "timer" timeout = "24h" Verify what the parser actually understood before pouring — unknown keys in TOML are dropped silently: bd formula show --json # inspect the parsed gate blocks [​](https://beads.gascity.com/workflows/gates#creating-gates-outside-formulas) Creating gates outside formulas ----------------------------------------------------------------------------------------------------------------- `bd gate create` attaches a gate to existing work: # Block bd-abc until a PR merges bd gate create --type=gh:pr --blocks bd-abc --await-id=42 # Block bd-abc until a human resolves the gate bd gate create --type=human --blocks bd-abc --reason "Design sign-off" # Add another waiter to an existing gate bd gate add-waiter [​](https://beads.gascity.com/workflows/gates#fan-in-waiting-on-other-steps) Fan-in: waiting on other steps -------------------------------------------------------------------------------------------------------------- Waiting on _other steps_ is not a gate — it’s a dependency. Use `needs` to fan in on named steps, and `waits_for` when a step must wait for dynamically-created children: [[steps]] id = "merge-results" title = "Merge results" needs = ["test-a", "test-b"] # fan-in on named steps [[steps]] id = "summarize" title = "Summarize all spawned work" waits_for = "all-children" # or "any-children", or "children-of(step-id)" [​](https://beads.gascity.com/workflows/gates#working-with-gated-molecules) Working with gated molecules ----------------------------------------------------------------------------------------------------------- bd ready --gated # molecules where a gate just closed (ready to resume) bd blocked # what's waiting, and on which gates Automation patterns: run `bd gate check` on a schedule (cron, CI, or an orchestrator loop) so timer and GitHub gates close without a human in the loop; keep `human` gates for the decisions that should never auto-close. [Formulas](https://beads.gascity.com/workflows/formulas) [Wisps](https://beads.gascity.com/workflows/wisps) ⌘I --- # Issues & Dependencies - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/core-concepts/issues#content-area) Understanding the issue model in beads. [​](https://beads.gascity.com/core-concepts/issues#issue-structure) Issue Structure -------------------------------------------------------------------------------------- Every issue has: bd show bd-42 --json { "id": "bd-42", "title": "Implement authentication", "description": "Add JWT-based auth", "type": "feature", "status": "open", "priority": 1, "labels": ["backend", "security"], "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } [​](https://beads.gascity.com/core-concepts/issues#issue-types) Issue Types ------------------------------------------------------------------------------ | Type | Use Case | | --- | --- | | `bug` | Something broken that needs fixing | | `feature` | New functionality | | `task` | Work item (tests, docs, refactoring) | | `epic` | Large feature with subtasks | | `chore` | Maintenance (dependencies, tooling) | [​](https://beads.gascity.com/core-concepts/issues#priorities) Priorities ---------------------------------------------------------------------------- | Priority | Level | Examples | | --- | --- | --- | | 0 | Critical | Security, data loss, broken builds | | 1 | High | Major features, important bugs | | 2 | Medium | Nice-to-have features, minor bugs | | 3 | Low | Polish, optimization | | 4 | Backlog | Future ideas | [​](https://beads.gascity.com/core-concepts/issues#creating-issues) Creating Issues -------------------------------------------------------------------------------------- # Basic issue bd create "Fix login bug" -t bug -p 1 # With description bd create "Add password reset" \ --description="Users need to reset forgotten passwords via email" \ -t feature -p 2 # With labels bd create "Update dependencies" -t chore -l "maintenance,security" # JSON output for agents bd create "Task" -t task --json [​](https://beads.gascity.com/core-concepts/issues#dependencies) Dependencies -------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/issues#blocking-dependencies) Blocking Dependencies The `blocks` relationship affects the ready queue: # Add dependency: bd-2 depends on bd-1 bd dep add bd-2 bd-1 # View dependencies bd dep tree bd-2 # See blocked issues bd blocked # See ready work (not blocked) bd ready ### [​](https://beads.gascity.com/core-concepts/issues#structural-relationships) Structural Relationships These don’t affect the ready queue: # Parent-child (epic subtasks) bd create "Epic" -t epic bd create "Subtask" --parent bd-42 # Discovered-from (found during work) bd create "Found bug" --deps discovered-from:bd-42 # Related (soft link) bd dep relate bd-1 bd-2 ### [​](https://beads.gascity.com/core-concepts/issues#dependency-types) Dependency Types | Type | Description | Ready Queue Impact | | --- | --- | --- | | `blocks` | Hard dependency | Yes - blocked items not ready | | `parent-child` | Epic/subtask hierarchy | No | | `discovered-from` | Tracks origin of discovery | No | | `related` | Soft relationship | No | [​](https://beads.gascity.com/core-concepts/issues#hierarchical-issues) Hierarchical Issues ---------------------------------------------------------------------------------------------- For large features, use hierarchical IDs: # Create epic bd create "Auth System" -t epic -p 1 # Returns: bd-a3f8e9 # Child tasks auto-number bd create "Design login UI" --parent bd-a3f8e9 # bd-a3f8e9.1 bd create "Backend validation" --parent bd-a3f8e9 # bd-a3f8e9.2 # View hierarchy bd dep tree bd-a3f8e9 [​](https://beads.gascity.com/core-concepts/issues#updating-issues) Updating Issues -------------------------------------------------------------------------------------- # Change status bd update bd-42 --claim # Change priority bd update bd-42 --priority 0 # Add labels bd update bd-42 --add-label urgent # Multiple changes bd update bd-42 --claim --priority 1 --add-label "in-review" [​](https://beads.gascity.com/core-concepts/issues#closing-issues) Closing Issues ------------------------------------------------------------------------------------ # Simple close bd close bd-42 # With reason bd close bd-42 --reason "Implemented in PR #123" # JSON output bd close bd-42 --json [​](https://beads.gascity.com/core-concepts/issues#searching-and-filtering) Searching and Filtering ------------------------------------------------------------------------------------------------------ # By status bd list --status open bd list --status in_progress # By priority bd list --priority 1 bd list --priority 0,1 # Multiple # By type bd list --type bug bd list --type feature,task # By label bd list --label-any urgent,critical bd list --label-all backend,security # Combined filters bd list --status open --priority 1 --type bug --json [How Beads Works](https://beads.gascity.com/core-concepts) [Dependencies and Gates](https://beads.gascity.com/core-concepts/dependencies) ⌘I --- # Aider - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/aider#content-area) How to use beads with Aider. [Aider](https://aider.chat/) is a human-in-the-loop AI pair programming tool: unlike autonomous agents such as [Claude Code](https://beads.gascity.com/integrations/claude-code) , it doesn’t run shell commands on its own. The beads integration works with that design — the AI **suggests** `bd` commands, and you confirm each one with aider’s `/run` command. [​](https://beads.gascity.com/integrations/aider#setup) Setup ---------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/aider#prerequisites) Prerequisites * beads installed and initialized in your project (see [Installation](https://beads.gascity.com/getting-started/installation) ); run `bd init` if there’s no `.beads/` directory yet * aider installed: `pip install aider-chat` (or `pipx install aider-chat`) ### [​](https://beads.gascity.com/integrations/aider#quick-setup) Quick Setup bd setup aider This creates: * `.aider.conf.yml` — tells aider to load the beads instructions * `.aider/BEADS.md` — workflow instructions the AI reads * `.aider/README.md` — quick reference for humans ### [​](https://beads.gascity.com/integrations/aider#verify-setup) Verify Setup bd setup aider --check ### [​](https://beads.gascity.com/integrations/aider#remove-the-integration) Remove the Integration bd setup aider --remove This removes `.aider.conf.yml`, `.aider/BEADS.md`, and `.aider/README.md`. [​](https://beads.gascity.com/integrations/aider#configuration) Configuration -------------------------------------------------------------------------------- The generated `.aider.conf.yml` loads the beads instructions into aider’s read-only context: # Beads Issue Tracking Integration for Aider # Auto-generated by 'bd setup aider' # Load Beads workflow instructions for the AI # This file is marked read-only and cached for efficiency read: - .aider/BEADS.md `.aider/BEADS.md` holds the workflow rules the AI follows: track all work in bd (never markdown TODOs), suggest `bd ready` to find work, suggest `bd create` for new issues, suggest `bd dolt push` at end of session — and always _suggest_ commands for you to run via `/run`. You can edit it to add project-specific instructions, but rerunning `bd setup aider` regenerates it. [​](https://beads.gascity.com/integrations/aider#workflow) Workflow ---------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/aider#start-session) Start Session # Aider will have access to issues via .aider.conf.yml aider # Or manually inject context bd prime | aider --message-file - ### [​](https://beads.gascity.com/integrations/aider#inside-aider) Inside Aider Aider’s own commands start with `/` (`/run`, `/add`, `/help`); anything else is a message to the AI. The AI suggests bd commands, and you execute the ones you approve with `/run`: You: What issues are ready to work on? Aider: Let me check the available work. Run: /run bd ready You: Let's work on bd-42 Aider: To claim it, run: /run bd update bd-42 --claim To give the AI full bd context mid-session, run `/run bd prime` — the AI reads the output and picks up the complete workflow guide. ### [​](https://beads.gascity.com/integrations/aider#during-work) During Work Use bd commands alongside aider: # In another terminal or after exiting aider bd create "Found bug during work" --deps discovered-from:bd-42 --json bd update bd-42 --claim bd ready # Link an already-created issue as discovered work bd dep add bd-77 bd-42 --type discovered-from ### [​](https://beads.gascity.com/integrations/aider#end-session) End Session bd dolt push [​](https://beads.gascity.com/integrations/aider#best-practices) Best Practices ---------------------------------------------------------------------------------- 1. **Keep issues visible** - Use `bd prime` to inject issue context 2. **Push regularly** - Run `bd dolt push` after significant changes 3. **Use discovered-from** - Track issues found during work 4. **Document context** - Include descriptions in issues 5. **Aider commits, bd syncs** - Aider auto-commits your code changes; issue data moves separately with `bd dolt push` [​](https://beads.gascity.com/integrations/aider#example-workflow) Example Workflow -------------------------------------------------------------------------------------- # 1. Check ready work bd ready # 2. Start aider with issue context aider --message "Working on bd-42: Fix auth bug" # 3. Work in aider... # 4. Create discovered issues bd create "Found related bug" --deps discovered-from:bd-42 --json # 5. Complete and push bd close bd-42 --reason "Fixed" bd dolt push [​](https://beads.gascity.com/integrations/aider#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/integrations/aider#config-not-loading) Config not loading # Check config exists cat .aider.conf.yml # Regenerate bd setup aider Aider reads `.aider.conf.yml` at startup, so restart aider (`/exit`, then `aider`) after regenerating. ### [​](https://beads.gascity.com/integrations/aider#issues-not-visible) Issues not visible # Use bd prime to inject issue context bd prime | aider --message-file - # Or check database health bd doctor [​](https://beads.gascity.com/integrations/aider#see-also) See Also ---------------------------------------------------------------------- * [Claude Code](https://beads.gascity.com/integrations/claude-code) * [IDE Setup](https://beads.gascity.com/getting-started/ide-setup) * [Quickstart](https://beads.gascity.com/getting-started/quickstart) * [Aider documentation](https://aider.chat/docs/) * [AGENTS.md](https://github.com/gastownhall/beads/blob/main/AGENTS.md) - the full bd agent workflow guide [Integrations](https://beads.gascity.com/integrations) [Claude Code](https://beads.gascity.com/integrations/claude-code) ⌘I --- # MCP Server - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/mcp-server#content-area) Use beads in MCP-only environments. [​](https://beads.gascity.com/integrations/mcp-server#when-to-use-mcp) When to Use MCP ----------------------------------------------------------------------------------------- Use MCP server when CLI is unavailable: * Claude Desktop (no shell access) * Sourcegraph Amp without shell * Other MCP-only environments **Prefer CLI + hooks** when shell is available - it’s more context efficient. [​](https://beads.gascity.com/integrations/mcp-server#installation) Installation ----------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/mcp-server#using-uv-recommended) Using uv (Recommended) uv tool install beads-mcp ### [​](https://beads.gascity.com/integrations/mcp-server#using-pip) Using pip pip install beads-mcp [​](https://beads.gascity.com/integrations/mcp-server#configuration) Configuration ------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/mcp-server#claude-desktop-macos) Claude Desktop (macOS) Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: { "mcpServers": { "beads": { "command": "beads-mcp" } } } ### [​](https://beads.gascity.com/integrations/mcp-server#claude-desktop-windows) Claude Desktop (Windows) Add to `%APPDATA%\Claude\claude_desktop_config.json`: { "mcpServers": { "beads": { "command": "beads-mcp" } } } ### [​](https://beads.gascity.com/integrations/mcp-server#sourcegraph-amp) Sourcegraph Amp Add to MCP settings: { "beads": { "command": "beads-mcp", "args": [] } } ### [​](https://beads.gascity.com/integrations/mcp-server#vs-code-/-github-copilot) VS Code / GitHub Copilot Create `.vscode/mcp.json` in your project: { "servers": { "beads": { "command": "beads-mcp" } } } **For all projects:** Add to VS Code user-level MCP config: | Platform | Path | | --- | --- | | macOS | `~/Library/Application Support/Code/User/mcp.json` | | Linux | `~/.config/Code/User/mcp.json` | | Windows | `%APPDATA%\Code\User\mcp.json` | { "servers": { "beads": { "command": "beads-mcp", "args": [] } } } **Note:** Requires VS Code 1.96+ with MCP support enabled. See [GitHub Copilot Integration](https://beads.gascity.com/integrations/github-copilot) for complete setup guide. [​](https://beads.gascity.com/integrations/mcp-server#available-tools) Available Tools ----------------------------------------------------------------------------------------- The MCP server exposes these tools: | Tool | Description | | --- | --- | | `ready` | Show ready work (no open blockers) | | `list` | List issues with filters | | `show` | Show issue details, dependencies, and dependents | | `create` | Create a new issue | | `claim` | Atomically claim an issue | | `update` | Update an issue | | `close` / `reopen` | Close or reopen an issue | | `dep` | Manage dependencies | | `comment` / `comments` | Add or list comments | | `note` | Append to an issue’s notes | | `blocked` | Show blocked issues and their blockers | | `stats` / `context` | Database stats and workspace context | | `admin` | Administrative operations | | `discover_tools` / `get_tool_info` | Tool discovery and schemas | There is no MCP sync tool — syncing stays on the CLI (`bd dolt push` / `bd dolt pull`). [​](https://beads.gascity.com/integrations/mcp-server#usage) Usage --------------------------------------------------------------------- Once configured, use naturally: Create an issue for fixing the login bug with priority 1 The MCP server translates to appropriate `bd` commands. [​](https://beads.gascity.com/integrations/mcp-server#trade-offs) Trade-offs ------------------------------------------------------------------------------- | Aspect | CLI + Hooks | MCP Server | | --- | --- | --- | | Context overhead | ~1-2k tokens | 10-50k tokens | | Latency | Direct calls | MCP protocol | | Setup | Hooks config | MCP config | | Availability | Shell required | MCP environments | [​](https://beads.gascity.com/integrations/mcp-server#troubleshooting) Troubleshooting ----------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/mcp-server#server-won%E2%80%99t-start) Server won’t start Check if `beads-mcp` is in PATH: which beads-mcp If not found: # Reinstall pip uninstall beads-mcp pip install beads-mcp ### [​](https://beads.gascity.com/integrations/mcp-server#tools-not-appearing) Tools not appearing 1. Restart Claude Desktop 2. Check MCP config JSON syntax 3. Verify server path ### [​](https://beads.gascity.com/integrations/mcp-server#permission-errors) Permission errors # Check directory permissions ls -la .beads/ # Initialize if needed bd init --quiet [​](https://beads.gascity.com/integrations/mcp-server#see-also) See Also --------------------------------------------------------------------------- * [Claude Code](https://beads.gascity.com/integrations/claude-code) - CLI integration * [Installation](https://beads.gascity.com/getting-started/installation) - Full install guide [Windsurf](https://beads.gascity.com/integrations/windsurf) [GitHub Copilot](https://beads.gascity.com/integrations/github-copilot) ⌘I --- # TODO Command - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/workflows/todo#content-area) The `bd todo` command provides a lightweight interface for managing TODO items as task-type issues. [​](https://beads.gascity.com/workflows/todo#philosophy) Philosophy ---------------------------------------------------------------------- TODOs in bd are not a separate tracking system - they are regular task-type issues with convenient shortcuts. This means: * **No parallel systems**: TODOs use the same storage and sync as all other issues * **Promotable**: Easy to convert a TODO to a bug/feature when needed * **Full featured**: TODOs support all bd features (dependencies, labels, routing) * **Simple interface**: Quick commands for common TODO workflows [​](https://beads.gascity.com/workflows/todo#quick-start) Quick Start ------------------------------------------------------------------------ # Add a TODO bd todo add "Fix the login bug" -p 1 # List TODOs bd todo # Mark TODO as done bd todo done [​](https://beads.gascity.com/workflows/todo#commands) Commands ------------------------------------------------------------------ ### [​](https://beads.gascity.com/workflows/todo#bd-todo-or-bd-todo-list) `bd todo` (or `bd todo list`) List all open task-type issues. bd todo # List open TODOs bd todo list # Same as above bd todo list --all # Show completed TODOs too bd todo list --json # JSON output **Output:** ○ test-yxg Fix the login bug ● P1 open ○ test-ryl Update documentation ● P3 open Total: 2 TODOs ### [​](https://beads.gascity.com/workflows/todo#bd-todo-add-%3Ctitle%3E) `bd todo add ` Create a new TODO item (task-type issue). bd todo add "Fix the login bug" # Default P2 bd todo add "Update docs" -p 3 -d "Add examples" # With priority and description bd todo add "Critical fix" --priority 0 --description "ASAP" # P0 task **Flags:** * `-p, --priority <0-4>`: Priority (default: 2) * `-d, --description <text>`: Description ### [​](https://beads.gascity.com/workflows/todo#bd-todo-done-%3Cid%3E-%3Cid%3E-) `bd todo done <id> [<id>...]` Mark one or more TODOs as complete. bd todo done test-abc # Close one TODO bd todo done test-abc test-def # Close multiple bd todo done test-abc --reason "Fixed in PR #42" # With reason **Flags:** * `--reason <text>`: Reason for closing (default: “Completed”) [​](https://beads.gascity.com/workflows/todo#converting-todos) Converting TODOs ---------------------------------------------------------------------------------- TODOs are regular task issues, so you can convert them: # Promote TODO to bug bd update test-abc --type bug --priority 0 # Add dependencies bd dep add test-abc test-def # Add labels bd update test-abc --set-labels "urgent,frontend" [​](https://beads.gascity.com/workflows/todo#viewing-todo-details) Viewing TODO Details ------------------------------------------------------------------------------------------ Use regular bd commands: bd show test-abc # View TODO details bd list --type task # List all tasks (including TODOs) bd ready # See ready TODOs in work queue [​](https://beads.gascity.com/workflows/todo#examples) Examples ------------------------------------------------------------------ ### [​](https://beads.gascity.com/workflows/todo#daily-todo-workflow) Daily TODO workflow # Morning: add your tasks bd todo add "Review PRs" bd todo add "Fix CI pipeline" -p 1 bd todo add "Update changelog" -p 3 # Check what's on your plate bd todo # Complete work bd todo done <id> bd todo done <id> # End of day: see what's left bd todo ### [​](https://beads.gascity.com/workflows/todo#converting-todo-to-full-issue) Converting TODO to full issue # Start with a quick TODO bd todo add "Login is broken" # Later, realize it's more serious bd update <id> --type bug --priority 0 --description "Users can't login, multiple reports" bd update <id> --acceptance "Login works for all user types" # Now it's a full-fledged bug with proper tracking bd show <id> [​](https://beads.gascity.com/workflows/todo#faq) FAQ -------------------------------------------------------- **Q: Are TODOs different from tasks?** A: No, TODOs are just task-type issues. The `bd todo` command provides shortcuts for common task operations. **Q: Can TODOs have dependencies?** A: Yes! Use `bd dep add <todo-id> <blocks-id>` like any other issue. **Q: Do TODOs sync across machines?** A: Yes, they’re stored in the Dolt database and synced via Dolt remotes like all other issues. **Q: Can I use TODOs with bd ready?** A: Yes! `bd ready` shows all unblocked issues, including task-type TODOs. **Q: Should I use TODOs or regular tasks?** A: Use `bd todo` for quick, informal tasks. Use `bd create -t task` for tasks that need more context or are part of larger planning. [​](https://beads.gascity.com/workflows/todo#design-rationale) Design Rationale ---------------------------------------------------------------------------------- The TODO command follows beads’ philosophy of **minimal surface area**: 1. **No new types**: TODOs are task-type issues 2. **No special storage**: Same Dolt database as everything else 3. **Convenience layer**: Just shortcuts for common operations 4. **Fully compatible**: Works with all bd features and commands This ensures: * No duplicate tracking systems * No migration needed between TODOs and tasks * Works with all existing bd tooling (federation, compaction, routing) * Simple to understand and maintain [Wisps](https://beads.gascity.com/workflows/wisps) [Recovery Overview](https://beads.gascity.com/recovery) ⌘I --- # Hash-based IDs - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/core-concepts/hash-ids#content-area) Understanding beads’ collision-resistant ID system. [​](https://beads.gascity.com/core-concepts/hash-ids#the-problem) The Problem -------------------------------------------------------------------------------- Traditional sequential IDs (`#1`, `#2`, `#3`) break when: * Multiple agents create issues simultaneously * Different branches have independent numbering * Forks diverge and later merge [​](https://beads.gascity.com/core-concepts/hash-ids#the-solution) The Solution ---------------------------------------------------------------------------------- Beads uses hash-based IDs: bd-a1b2c3 # Short hash bd-f14c # Even shorter bd-a3f8e9.1 # Hierarchical (child of bd-a3f8e9) **Properties:** * Globally unique (content-based hash) * No coordination needed between creators * Merge-friendly across branches * Predictable length (configurable) [​](https://beads.gascity.com/core-concepts/hash-ids#how-hashes-work) How Hashes Work ---------------------------------------------------------------------------------------- IDs are generated from: * Issue title * Creation timestamp * Random salt # Create issue - ID assigned automatically bd create "Fix authentication bug" # Returns: bd-7x2f # The ID is deterministic for same content+timestamp [​](https://beads.gascity.com/core-concepts/hash-ids#hierarchical-ids) Hierarchical IDs ------------------------------------------------------------------------------------------ For epics and subtasks: # Parent epic bd create "Auth System" -t epic # Returns: bd-a3f8e9 # Children auto-increment bd create "Design UI" --parent bd-a3f8e9 # bd-a3f8e9.1 bd create "Backend" --parent bd-a3f8e9 # bd-a3f8e9.2 bd create "Tests" --parent bd-a3f8e9 # bd-a3f8e9.3 Benefits: * Clear parent-child relationship * No namespace collision (parent hash is unique) * Up to 3 levels of nesting [​](https://beads.gascity.com/core-concepts/hash-ids#id-configuration) ID Configuration ------------------------------------------------------------------------------------------ Configure ID prefix and length: # Set prefix (default: bd) bd config set id.prefix myproject # Set hash length (default: 4) bd config set id.hash_length 6 # New issues use new format bd create "Test" # Returns: myproject-a1b2c3 [​](https://beads.gascity.com/core-concepts/hash-ids#collision-handling) Collision Handling ---------------------------------------------------------------------------------------------- While rare, collisions are handled automatically: 1. On import, if hash collision detected 2. Beads appends disambiguator 3. Both issues preserved # Check for collisions bd info --schema --json | jq '.collision_count' [​](https://beads.gascity.com/core-concepts/hash-ids#working-with-ids) Working with IDs ------------------------------------------------------------------------------------------ # Partial ID matching bd show a1b2 # Finds bd-a1b2... bd show auth # Fuzzy match by title # Full ID required for ambiguous cases bd show bd-a1b2c3d4 # List with full IDs bd list --full-ids [​](https://beads.gascity.com/core-concepts/hash-ids#migration-from-sequential-ids) Migration from Sequential IDs -------------------------------------------------------------------------------------------------------------------- If migrating from a system with sequential IDs: # Bootstrap from a JSONL export (preserves original IDs in metadata) bd init --from-jsonl old-issues.jsonl # View original ID bd show bd-new --json | jq '.original_id' [​](https://beads.gascity.com/core-concepts/hash-ids#best-practices) Best Practices -------------------------------------------------------------------------------------- 1. **Use short references** - `bd-a1b2` is usually unique enough 2. **Use `--json` for scripts** - Parse full ID programmatically 3. **Reference by hash in commits** - `Fixed bd-a1b2` in commit messages 4. **Let hierarchies form naturally** - Create epics, add children as needed [Dependencies and Gates](https://beads.gascity.com/core-concepts/dependencies) [Adaptive ID Length](https://beads.gascity.com/core-concepts/adaptive-ids) ⌘I --- # Agent Coordination - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/multi-agent/coordination#content-area) Patterns for coordinating work between multiple AI agents. [​](https://beads.gascity.com/multi-agent/coordination#work-assignment) Work Assignment ------------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/multi-agent/coordination#assigning-and-claiming-work) Assigning and Claiming Work Assign work to a specific agent, or claim it atomically for yourself: # Assign issue to an agent bd assign bd-42 agent-1 # Atomically claim an issue (sets assignee to you, status to in_progress) bd update bd-42 --claim # Claim the first ready issue matching your filters bd ready --claim --json # Release a claimed issue bd assign bd-42 "" # clear the assignee bd update bd-42 --status open # make it claimable again ### [​](https://beads.gascity.com/multi-agent/coordination#checking-assigned-work) Checking Assigned Work # What is agent-1 working on? bd list --assignee agent-1 --status in_progress # What is ready for agent-1? bd ready --assignee agent-1 # JSON output bd list --assignee agent-1 --json [​](https://beads.gascity.com/multi-agent/coordination#handoff-patterns) Handoff Patterns -------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/coordination#sequential-handoff) Sequential Handoff Agent A completes work, hands off to Agent B: # Agent A bd comment bd-42 "API complete, ready for review" bd assign bd-42 agent-b # Agent B picks up bd list --assignee agent-b # Sees bd-42 bd update bd-42 --claim ### [​](https://beads.gascity.com/multi-agent/coordination#parallel-work) Parallel Work Multiple agents work on different issues: # Coordinator bd assign bd-42 agent-a bd assign bd-43 agent-b bd assign bd-44 agent-c # Each agent claims its issue and works independently bd update bd-42 --claim # Coordinator monitors progress bd list --status in_progress --json ### [​](https://beads.gascity.com/multi-agent/coordination#fan-out-/-fan-in) Fan-Out / Fan-In Split work, then merge: # Fan-out bd create "Part A" --parent bd-epic bd create "Part B" --parent bd-epic bd create "Part C" --parent bd-epic bd assign bd-epic.1 agent-a bd assign bd-epic.2 agent-b bd assign bd-epic.3 agent-c # Fan-in: wait for all parts (one dependency per call) bd dep add bd-merge bd-epic.1 bd dep add bd-merge bd-epic.2 bd dep add bd-merge bd-epic.3 For structured epic fan-out, `bd swarm` creates and tracks a swarm molecule from an epic (`bd swarm create`, `bd swarm status`). [​](https://beads.gascity.com/multi-agent/coordination#agent-discovery) Agent Discovery ------------------------------------------------------------------------------------------ Beads has no agent registry — assignees are plain strings. To see which agents are active, group in-progress work by assignee: bd list --status in_progress --json [​](https://beads.gascity.com/multi-agent/coordination#conflict-prevention) Conflict Prevention -------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/coordination#atomic-claims) Atomic Claims `--claim` is atomic: when multiple agents pull from the same ready queue, the first claim wins, and repeating a claim you already hold is idempotent. Prefer claiming over assigning when agents self-select work: bd ready --claim --json ### [​](https://beads.gascity.com/multi-agent/coordination#merge-slots) Merge Slots Serialize conflict-prone work (such as merge-queue conflict resolution) with a merge slot — an exclusive-access primitive only one agent can hold at a time. Each project has one merge slot bead, named from the issue prefix (e.g. `bd-merge-slot`): # Create the merge slot for this project bd merge-slot create # Check availability bd merge-slot check # Acquire before starting; release when done bd merge-slot acquire bd merge-slot release [​](https://beads.gascity.com/multi-agent/coordination#communication-patterns) Communication Patterns -------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/coordination#via-comments) Via Comments # Agent A leaves note bd comment bd-42 "Completed API, needs frontend integration" # Agent B reads bd comments bd-42 ### [​](https://beads.gascity.com/multi-agent/coordination#via-labels) Via Labels # Mark for review bd update bd-42 --add-label "needs-review" # Agent B filters bd list --label-any needs-review [​](https://beads.gascity.com/multi-agent/coordination#coordinating-across-repositories) Coordinating Across Repositories ---------------------------------------------------------------------------------------------------------------------------- Agents can coordinate work that spans repositories: # Depend on a capability delivered by another project bd dep add bd-42 external:backend:api-ready Multi-repo routing, aggregated views, and contributor/team workflows are covered in [Routing](https://beads.gascity.com/multi-agent/routing) and [Multi-Repo Migration](https://beads.gascity.com/multi-agent/multi-repo-migration) . [​](https://beads.gascity.com/multi-agent/coordination#best-practices) Best Practices ---------------------------------------------------------------------------------------- 1. **Clear ownership** - Assign or claim work so every issue has one owner 2. **Document handoffs** - Use comments to explain context 3. **Use labels for status** - `needs-review`, `blocked`, `ready` 4. **Avoid conflicts** - Claim atomically; use merge slots to serialize conflict-prone work 5. **Monitor progress** - Regular status checks 6. **Sync at session end** - Run `bd dolt push` so other agents see your updates [Multi-Repo Routing](https://beads.gascity.com/multi-agent/routing) [Federation Setup Guide](https://beads.gascity.com/multi-agent/federation) ⌘I --- # Antivirus False Positives - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference/antivirus#content-area) [​](https://beads.gascity.com/reference/antivirus#overview) Overview ----------------------------------------------------------------------- Some antivirus software may flag beads (`bd` or `bd.exe`) as malicious. This is a **false positive** - beads is a legitimate, open-source command-line tool for issue tracking. Beads release installers now verify downloaded archives against release `checksums.txt` before installation. For users who manually install binaries, checksum verification should be the first trust step before running `bd` or creating antivirus exclusions. [​](https://beads.gascity.com/reference/antivirus#why-this-happens) Why This Happens --------------------------------------------------------------------------------------- Go binaries (including beads) are sometimes flagged by antivirus software due to: 1. **Heuristic detection**: Some malware is written in Go, causing antivirus ML models to flag Go-specific binary patterns as suspicious 2. **Behavioral analysis**: CLI tools that modify files and interact with git may trigger behavioral detection 3. **Unsigned binaries**: Without code signing, new executables may be treated with suspicion This is a **known industry-wide problem** affecting many legitimate Go projects. See the [Go project issues](https://github.com/golang/go/issues/16292) for examples. [​](https://beads.gascity.com/reference/antivirus#known-issues) Known Issues ------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/antivirus#kaspersky-antivirus) Kaspersky Antivirus **Detection**: `PDM:Trojan.Win32.Generic` **Affected versions**: bd.exe v0.23.1 and potentially others **Component**: System Watcher (Proactive Defense Module) Kaspersky’s PDM (Proactive Defense Module) uses behavioral analysis that commonly triggers false positives on Go executables. [​](https://beads.gascity.com/reference/antivirus#solutions-for-users) Solutions for Users --------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/antivirus#option-1-verify-file-integrity-recommended-first) Option 1: Verify File Integrity (Recommended First) Before running a downloaded binary or adding antivirus exclusions, verify the file is legitimate: 1. Download beads from the [official GitHub releases](https://github.com/gastownhall/beads/releases) 2. Verify the SHA256 checksum matches the `checksums.txt` file in the release 3. If a release includes code signing, verify that signature too **Verify checksum (Windows PowerShell):** Get-FileHash bd.exe -Algorithm SHA256 **Verify checksum (macOS/Linux):** shasum -a 256 bd Compare the output with the checksum in `checksums.txt` from the release page. ### [​](https://beads.gascity.com/reference/antivirus#option-2-add-exclusion-after-verification) Option 2: Add Exclusion (After Verification) Add beads to your antivirus exclusion list: **Kaspersky:** 1. Open Kaspersky and go to Settings 2. Navigate to Threats and Exclusions → Manage Exclusions 3. Click Add → Add path to exclusion 4. Add the directory containing `bd.exe` (e.g., `C:\Users\YourName\AppData\Local\bd\`) 5. Select which components the exclusion applies to (scan, monitoring, etc.) **Windows Defender:** 1. Open Windows Security 2. Go to Virus & threat protection → Manage settings 3. Scroll to Exclusions → Add or remove exclusions 4. Add the beads installation directory or the specific `bd.exe` file **Other antivirus software:** * Look for “Exclusions”, “Whitelist”, or “Trusted Applications” settings * Add the beads installation directory or executable ### [​](https://beads.gascity.com/reference/antivirus#option-3-report-false-positive) Option 3: Report False Positive Help improve detection accuracy by reporting the false positive: **Kaspersky:** 1. Visit [Kaspersky Threat Intelligence Portal](https://opentip.kaspersky.com/) 2. Upload the `bd.exe` file for analysis 3. Mark it as a false positive 4. Reference: beads is open-source CLI tool ([https://github.com/gastownhall/beads](https://github.com/gastownhall/beads) ) **Windows Defender:** 1. Go to [Microsoft Security Intelligence](https://www.microsoft.com/en-us/wdsi/filesubmission) 2. Submit the file as a false positive 3. Provide details about the legitimate software **Other vendors:** * Check their website for false positive submission forms * Most major vendors have a process for reviewing flagged files [​](https://beads.gascity.com/reference/antivirus#for-developers/distributors) For Developers/Distributors ------------------------------------------------------------------------------------------------------------- If you’re building beads from source or distributing it: ### [​](https://beads.gascity.com/reference/antivirus#current-build-configuration) Current Build Configuration Beads releases are built with multiple optimizations to reduce false positives: ldflags: - -s -w # Strip debug symbols and DWARF info **Windows PE version info**: Release builds embed legitimate PE resource metadata (company name, product name, file description, version, copyright, and an application manifest) into the Windows binary using `go-winres`. This is one of the most effective measures against AV false positives — legitimate software almost always has PE metadata, and AV heuristics use its absence as a suspicion signal. These optimizations are applied automatically in official release builds. ### [​](https://beads.gascity.com/reference/antivirus#code-signing) Code Signing Windows releases are signed with an Authenticode certificate when available. Code signing: * Reduces false positive rates over time * Builds reputation with SmartScreen/antivirus vendors * Provides tamper verification **Verify a signed binary (Windows PowerShell):** # Check if the binary is signed Get-AuthenticodeSignature .\bd.exe # Expected output for signed binary: # SignerCertificate: [Certificate details] # Status: Valid **Verify a signed binary (Linux/macOS with osslsigncode):** # Install osslsigncode if not available # Ubuntu/Debian: apt-get install osslsigncode # macOS: brew install osslsigncode osslsigncode verify -in bd.exe **Note:** Code signing requires an EV (Extended Validation) certificate, which involves a verification process. If a release is not signed, it means the certificate was not available at build time. Follow the checksum verification steps above to verify authenticity. ### [​](https://beads.gascity.com/reference/antivirus#alternative-build-methods) Alternative Build Methods Some users report success with: go build -ldflags "-s -w" -o bd ./cmd/bd However, results vary by antivirus vendor and version. [​](https://beads.gascity.com/reference/antivirus#frequently-asked-questions) Frequently Asked Questions ----------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/antivirus#is-beads-safe-to-use) Is beads safe to use? Yes. Beads is: * Open source (all code is auditable on [GitHub](https://github.com/gastownhall/beads) ) * Releases include checksums for verification * Used by developers worldwide * A simple CLI tool for issue tracking ### [​](https://beads.gascity.com/reference/antivirus#why-don%E2%80%99t-you-just-fix-the-code-to-avoid-detection) Why don’t you just fix the code to avoid detection? The issue isn’t specific to beads’ code - it’s a characteristic of Go binaries in general. Changing code won’t reliably prevent heuristic/behavioral detection. The proper solutions are: 1. Code signing (builds trust over time) 2. Whitelist applications with antivirus vendors 3. User reports of false positives ### [​](https://beads.gascity.com/reference/antivirus#will-this-be-fixed-in-future-releases) Will this be fixed in future releases? We’ve implemented: * **Windows PE version info** embedded in binaries (company name, product name, version, manifest) * **Code signing infrastructure** for Windows releases (requires EV certificate) * **Build optimizations** to reduce heuristic triggers (`-s -w` ldflags) * **Documentation** for users to add exclusions and report false positives Still in progress: * Acquiring an EV code signing certificate * Submitting beads to antivirus vendor whitelists False positives may still occur with new releases until the certificate builds reputation with antivirus vendors. This typically takes several months of consistent signed releases. ### [​](https://beads.gascity.com/reference/antivirus#should-i-disable-my-antivirus) Should I disable my antivirus? **No.** Instead: 1. Verify release checksums before first run 2. Keep your antivirus enabled for other threats 3. Add beads to your antivirus exclusions only after verification if detections persist [​](https://beads.gascity.com/reference/antivirus#reporting-issues) Reporting Issues --------------------------------------------------------------------------------------- If you encounter a new antivirus false positive: 1. Open an issue on [GitHub](https://github.com/gastownhall/beads/issues) 2. Include: * Antivirus software name and version * Detection/threat name * Beads version (`bd version`) * Operating system This helps us track and address false positives across different antivirus vendors. [​](https://beads.gascity.com/reference/antivirus#references) References --------------------------------------------------------------------------- * [Kaspersky False Positive Guide](https://support.kaspersky.com/1870) * [Go Binary False Positives Discussion](https://www.linkedin.com/pulse/go-false-positives-melle-boudewijns) * [Go Project Issue Tracker](https://github.com/golang/go/issues/16292) * [Kaspersky Community Forum](https://forum.kaspersky.com/topic/pdmtrojanwin32generic-54425/) [Troubleshooting](https://beads.gascity.com/reference/troubleshooting) [FAQ](https://beads.gascity.com/reference/faq) ⌘I --- # Observability (OpenTelemetry) - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference/observability#content-area) Beads exports metrics via OTLP HTTP. Telemetry is **disabled by default** — zero overhead when no variable is set. [​](https://beads.gascity.com/reference/observability#recommended-local-stack) Recommended local stack --------------------------------------------------------------------------------------------------------- | Service | Port | Role | | --- | --- | --- | | VictoriaMetrics | 8428 | OTLP metrics storage | | VictoriaLogs | 9428 | Reserved for future OTLP log storage | | Grafana | 9429 | Dashboards | # From your personal stack's opentelemetry/ folder docker compose up -d [​](https://beads.gascity.com/reference/observability#configuration) Configuration ------------------------------------------------------------------------------------- One variable is enough. Add it to your shell profile or workspace `.env`: export BD_OTEL_METRICS_URL=http://localhost:8428/opentelemetry/api/v1/push Every `bd` command will then automatically push its metrics. Log export is not implemented yet. `BD_OTEL_LOGS_URL` is reserved for a future VictoriaLogs exporter and does not activate telemetry today. ### [​](https://beads.gascity.com/reference/observability#shell-profile-recommended) Shell profile (recommended) # ~/.zshrc or ~/.bashrc export BD_OTEL_METRICS_URL=http://localhost:8428/opentelemetry/api/v1/push ### [​](https://beads.gascity.com/reference/observability#environment-variables) Environment variables | Variable | Example | Description | | --- | --- | --- | | `BD_OTEL_METRICS_URL` | `http://localhost:8428/opentelemetry/api/v1/push` | Push metrics to VictoriaMetrics. Activates telemetry. | | `BD_OTEL_LOGS_URL` | `http://localhost:9428/insert/opentelemetry/v1/logs` | Reserved for future log export. Does not activate telemetry today. | | `BD_OTEL_STDOUT` | `true` | Write spans and metrics to stderr (dev/debug). Also activates telemetry. | ### [​](https://beads.gascity.com/reference/observability#local-debug-mode) Local debug mode BD_OTEL_STDOUT=true bd list [​](https://beads.gascity.com/reference/observability#verification) Verification ----------------------------------------------------------------------------------- bd list # triggers metrics → visible in VictoriaMetrics Verification query in Grafana (VictoriaMetrics datasource): bd_storage_operations_total ### [​](https://beads.gascity.com/reference/observability#confirm-storage-instrumentation-locally) Confirm storage instrumentation locally To verify the storage decorator chain is wired up without standing up a collector, run `bd` with stdout exporters and look for `bd.storage.*` records on stderr: BD_OTEL_STDOUT=true bd list 2>&1 | grep -F bd.storage.operations Expect at least one line per storage call (`GetReadyWork`, `GetIssue`, …). If `bd.storage.*` and `bd.issue.count` are absent but `bd.db.pool_*` is present, the storage decorator is not in the chain — check `wireStorageDecorators` in `cmd/bd/storage_chain.go`. * * * [​](https://beads.gascity.com/reference/observability#metrics) Metrics ------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/observability#storage-bd_storage_) Storage (`bd_storage_*`) | Metric | Type | Attributes | Description | | --- | --- | --- | --- | | `bd_storage_operations_total` | Counter | `db.operation` | Storage operations executed | | `bd_storage_operation_duration_ms` | Histogram | `db.operation` | Operation duration (ms) | | `bd_storage_errors_total` | Counter | `db.operation` | Storage errors | > These metrics are emitted by `InstrumentedStorage`, the beads SDK wrapper. ### [​](https://beads.gascity.com/reference/observability#dolt-database-bd_db_) Dolt database (`bd_db_*`) | Metric | Type | Attributes | Description | | --- | --- | --- | --- | | `bd_db_retry_count_total` | Counter | — | SQL retries in server mode | | `bd_db_lock_wait_ms` | Histogram | `dolt_lock_exclusive` | Wait time to acquire database locks | ### [​](https://beads.gascity.com/reference/observability#issues-bd_issue_) Issues (`bd_issue_*`) | Metric | Type | Attributes | Description | | --- | --- | --- | --- | | `bd_issue_count` | Gauge | `status` | Number of issues by status | `status` values: `open`, `in_progress`, `closed`, `deferred`. ### [​](https://beads.gascity.com/reference/observability#ai-bd_ai_) AI (`bd_ai_*`) | Metric | Type | Attributes | Description | | --- | --- | --- | --- | | `bd_ai_input_tokens_total` | Counter | `bd_ai_model` | Anthropic input tokens | | `bd_ai_output_tokens_total` | Counter | `bd_ai_model` | Anthropic output tokens | | `bd_ai_request_duration_ms` | Histogram | `bd_ai_model` | API call latency | * * * [​](https://beads.gascity.com/reference/observability#traces-spans) Traces (spans) ------------------------------------------------------------------------------------- Spans are only exported when `BD_OTEL_STDOUT=true` — there is no trace backend in the recommended local stack. | Span | Source | Description | | --- | --- | --- | | `bd.command.<name>` | CLI | Total duration of the command | | `dolt.exec` / `dolt.query` / `dolt.query_row` | SQL | Each SQL operation | | `dolt.commit` / `dolt.push` / `dolt.pull` / `dolt.merge` | Dolt VC | Version control procedures | | `ephemeral.count` / `ephemeral.nuke` | SQLite | Ephemeral store operations | | `hook.exec` | Hooks | Hook execution (root span, fire-and-forget) | | `tracker.sync` / `tracker.pull` / `tracker.push` | Sync | Tracker sync phases | | `anthropic.messages.new` | AI | Claude API calls | ### [​](https://beads.gascity.com/reference/observability#notable-attributes) Notable attributes **`bd.command.<name>`** | Attribute | Description | | --- | --- | | `bd.command` | Subcommand name (`list`, `create`, …) | | `bd.version` | bd version | | `bd.args` | Raw arguments passed to the command (e.g. “create ‘title’ -p 2”) | | `bd.actor` | Actor (resolved from git config / env) | **`hook.exec`** | Attribute / Event | Description | | --- | --- | | `hook.event` | Event type (`create`, `update`, `close`) | | `hook.path` | Absolute path to the script | | `bd.issue_id` | ID of the triggering issue | | event `hook.stdout` | Script standard output (truncated to 1 024 bytes) | | event `hook.stderr` | Script error output (truncated to 1 024 bytes) | The `hook.stdout` / `hook.stderr` events carry two attributes: `output` (the text) and `bytes` (original size before truncation). * * * [​](https://beads.gascity.com/reference/observability#architecture) Architecture ----------------------------------------------------------------------------------- cmd/bd/main.go └─ telemetry.Init() ├─ BD_OTEL_STDOUT=true → TracerProvider stdout + MeterProvider stdout └─ BD_OTEL_METRICS_URL → MeterProvider HTTP → VictoriaMetrics internal/storage/dolt/ → bd_db_* metrics + dolt.* spans internal/storage/ephemeral/ → ephemeral.* spans internal/hooks/ → hook.exec span internal/tracker/ → tracker.* spans internal/compact/ → bd_ai_* metrics + anthropic.* spans internal/telemetry/storage.go → bd_storage_* metrics (SDK wrapper) When neither variable is set, `telemetry.Init()` installs **no-op** providers: hot paths execute only no-op calls with no memory allocation. [JSON Output Schema Contract](https://beads.gascity.com/reference/json-schema) [Troubleshooting](https://beads.gascity.com/reference/troubleshooting) ⌘I --- # Recovery Playbooks - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/recovery/init-safety#content-area) Last reviewed: 2026-06-09 Freshness source: `cmd/bd/init.go`, `cmd/bd/init_safety.go`, `cmd/bd/init_safety_test.go`, and `cmd/bd/dolt.go`. This document lives next to the ADRs and matches the structure of `bd`’s error messages: each named refusal in `bd init` and `bd dolt push`/`pull` points here to a labeled anchor with step-by-step recovery instructions. See also: `bd help init-safety`, and [ADR 0002 — `bd init` safety invariants](https://github.com/gastownhall/beads/blob/main/engdocs/adr/0002-init-safety-invariants.md) . [​](https://beads.gascity.com/recovery/init-safety#table-of-contents) Table of contents ------------------------------------------------------------------------------------------ * [init-force-refused — `bd init --force`/`--reinit-local` refused because origin has Dolt history](https://beads.gascity.com/recovery/init-safety#init-force-refused) * [init-token-missing — `--discard-remote` refused because `--destroy-token` is missing or wrong](https://beads.gascity.com/recovery/init-safety#init-token-missing) * [init-local-exists — `bd init` refused because local data already exists](https://beads.gascity.com/recovery/init-safety#init-local-exists) * [pk-fork-refused — `bd dolt pull`/`push` refused because a table has different primary keys in its common ancestor](https://beads.gascity.com/recovery/init-safety#pk-fork-refused) * * * [​](https://beads.gascity.com/recovery/init-safety#init-force-refused) init-force-refused -------------------------------------------------------------------------------------------- **Exit code:** `10` (`ExitRemoteDivergenceRefused`) **Symptom** bd init refuses: remote 'origin' already has Dolt history (refs/dolt/data). Why: this init mode would create or reuse local history instead of adopting the remote. ... **Why this happens** `bd init --force` (or `--reinit-local`) tells `bd` to bypass the local data-safety guard. `bd init --from-jsonl` selects a local JSONL export as the source. But the remote already has project history. Proceeding would create an orphan local Dolt branch with no common ancestor on origin. The next `bd dolt push` would either fail (no common ancestor) or — worse, if force-pushed — destroy the team’s data. **Recovery paths** Pick the one that matches your intent. ### [​](https://beads.gascity.com/recovery/init-safety#1-you-want-to-adopt-the-remote%E2%80%99s-history-most-common) 1\. You want to adopt the remote’s history (most common) bd bootstrap This clones the remote’s Dolt database into a fresh local `.beads/`. Your local state is ignored; the team’s history becomes yours. ### [​](https://beads.gascity.com/recovery/init-safety#2-you-want-to-diagnose-what-went-wrong-before-deciding) 2\. You want to diagnose what went wrong before deciding bd doctor bd dolt status `bd doctor` walks the local + remote state and names concrete problems. `bd dolt status` shows the Dolt-level view. Neither modifies anything. ### [​](https://beads.gascity.com/recovery/init-safety#3-you-intentionally-want-to-overwrite-the-remote%E2%80%99s-history-destructive) 3\. You intentionally want to overwrite the remote’s history (destructive) This is a cross-boundary operation that affects every collaborator. You need to pair the local-source init (`--reinit-local` or `--from-jsonl`) with `--discard-remote`. In interactive mode `bd` will prompt for confirmation; in non-interactive mode you must supply a `--destroy-token`. See `bd help init-safety` for the token format. After `bd init --reinit-local --discard-remote`, your next `bd dolt push` must be a history-replacing push. Coordinate with your team before doing this. * * * [​](https://beads.gascity.com/recovery/init-safety#init-token-missing) init-token-missing -------------------------------------------------------------------------------------------- **Exit code:** `12` (`ExitDestroyTokenMissing`) **Symptom** bd init refuses: --discard-remote requires an explicit destroy-token in non-interactive mode. **Why this happens** You’re running non-interactively (CI, agent, piped input) and passed `--discard-remote`. Destructive cross-boundary operations cannot be authorized silently. **Recovery paths** ### [​](https://beads.gascity.com/recovery/init-safety#1-run-interactively) 1\. Run interactively Re-run in a TTY. `bd init --reinit-local --discard-remote` will prompt you to type the destroy-token at confirmation time. ### [​](https://beads.gascity.com/recovery/init-safety#2-supply-the-token-explicitly-ci/automation) 2\. Supply the token explicitly (CI/automation) The token format is `DESTROY-<issue-prefix>`. For a project whose issue prefix is `bd`: bd init --reinit-local --discard-remote --destroy-token=DESTROY-bd Automation should template the token from project state, not from error output. See [ADR 0002 — Invariant 4](https://github.com/gastownhall/beads/blob/main/engdocs/adr/0002-init-safety-invariants.md) for why the token is never echoed in `bd`’s error messages. * * * [​](https://beads.gascity.com/recovery/init-safety#init-local-exists) init-local-exists ------------------------------------------------------------------------------------------ **Exit code:** `11` (`ExitLocalExistsRefused`) **Symptom** Refusing to destroy N issues in non-interactive mode. See 'bd help init-safety' for the required --destroy-token format. Or, in interactive mode, you declined the typed `destroy N issues` confirmation. **Why this happens** Local `.beads/` has existing issues. `bd init --reinit-local` would permanently destroy them. **Recovery paths** ### [​](https://beads.gascity.com/recovery/init-safety#1-export-first-then-proceed) 1\. Export first, then proceed bd export > issue-export.jsonl bd init --reinit-local `issue-export.jsonl` lets you re-import individual issues if needed. It is not a full database backup; use `bd backup` when the Dolt database is healthy enough to create a restorable backup before reinitializing. ### [​](https://beads.gascity.com/recovery/init-safety#2-investigate-why-you-hit-this) 2\. Investigate why you hit this If you did NOT expect `bd init` to be the right command here, run `bd doctor` first — you may be looking at a server config issue that a re-init won’t fix. * * * [​](https://beads.gascity.com/recovery/init-safety#pk-fork-refused) pk-fork-refused -------------------------------------------------------------------------------------- **Symptom** $ bd dolt pull Error: ... cannot merge because table dependencies has different primary keys in its common ancestor (or the variant without `in its common ancestor`). `bd` follows the error with a short version of the recovery recipe below. **Why this happens** The two histories being merged disagree about a table’s _primary key set_ — not about row contents. Dolt can cell-merge rows, but it refuses outright to merge a table whose primary key was reshaped differently on each side (or whose common ancestor had a different primary key than both sides). The refusal happens before any row conflicts materialize, so `bd dolt pull`’s conflict auto-resolver never gets a chance to run. **Retrying never helps**: the histories are permanently un-mergeable. The usual cause is upgrading `bd` independently on two clones while un-synced changes existed on both sides, across a release whose schema migrations reshape a primary key. Concretely: the [#4259](https://github.com/gastownhall/beads/issues/4259) incident — clones straddling the `0041`/`0043`/`0050` reshapes of `dependencies` (v1.0.4 → v1.0.6) hit exactly this on the first post-upgrade pull if both sides had unpushed dependency edits. The remote-migrate prevention gate (v1.0.6+) exists to stop this from being created: it refuses to auto-migrate a remote-backed database and tells you to designate a single migrator. This playbook is for when the fork already exists. **Recovery: bootstrap from one canonical clone** The forked histories cannot be merged, so one side must be chosen as canonical and every other clone re-cloned from it. Issue _data_ survives via JSONL export/import; only the un-mergeable Dolt _history_ is discarded on the non-canonical clones. ### [​](https://beads.gascity.com/recovery/init-safety#1-pick-the-canonical-clone) 1\. Pick the canonical clone Usually the most complete / most recently active clone. To compare, run on each clone (read-only): bd stats bd dolt status ### [​](https://beads.gascity.com/recovery/init-safety#2-on-the-canonical-clone-upgrade-migrate-force-push) 2\. On the canonical clone: upgrade, migrate, force-push bd version # confirm the new bd binary bd doctor # sanity-check before publishing bd dolt push --force # make the remote authoritative (`bd`’s migration gate may block here; that is exactly the designated-migrator case the gate is asking about — follow the guidance it prints on the canonical clone.) ### [​](https://beads.gascity.com/recovery/init-safety#3-on-every-other-clone-save-local-only-work-re-clone-re-apply) 3\. On EVERY other clone: save local-only work, re-clone, re-apply bd export --all -o /tmp/beads-local.jsonl # safety net for un-synced work rm -rf .beads/dolt # discard the un-mergeable history bd bootstrap # re-clone from the remote bd import /tmp/beads-local.jsonl # re-apply local-only work `bd import` has upsert semantics: issues that only existed on this clone are re-created, newer local edits are applied, and rows older than what the remote already has are skipped. Spot-check with `bd stats` afterwards. ### [​](https://beads.gascity.com/recovery/init-safety#prevention-upgrades-across-pk-reshaping-migrations) Prevention (upgrades across PK-reshaping migrations) * **Sync before upgrading**: `bd dolt push` + `bd dolt pull` on every clone while all clones still run the _old_ version, then stop editing. Once the new binary is installed, `bd dolt push`/`bd dolt pull` are gated too, so this must happen first. * **One designated migrator**: upgrade one machine, let it migrate, then `bd dolt push`. * **Every other clone adopts, does not pull**: after the migrator pushes, each other clone upgrades the binary and runs `bd bootstrap` to adopt the migrated database. `bd dolt pull` is _refused_ while the clone still has pending migrations, so do not rely on it; the “sync before” step above is what preserves these clones’ work, because `bd bootstrap` replaces the local database. [Recovery Overview](https://beads.gascity.com/recovery) [Database Corruption](https://beads.gascity.com/recovery/database-corruption) ⌘I --- # JSON Output Schema Contract - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference/json-schema#content-area) Last reviewed: 2026-05-08 Freshness source: `cmd/bd/output.go`, `cmd/bd/errors.go`, and `cmd/bd/protocol/json_contract_test.go`. All `bd` commands that support `--json` output can wrap their response in a uniform envelope by setting `BD_JSON_ENVELOPE=1`. This will become the default format in v2.0. [​](https://beads.gascity.com/reference/json-schema#migration-guide) Migration Guide --------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/json-schema#opt-in-to-the-envelope-format) Opt in to the envelope format export BD_JSON_ENVELOPE=1 ### [​](https://beads.gascity.com/reference/json-schema#envelope-format-bd_json_envelope=1-default-in-v2-0) Envelope format (BD\_JSON\_ENVELOPE=1, default in v2.0) Every `--json` command wraps output as: {"schema_version": 1, "data": <original-payload>} The original payload is untouched inside `.data` — no type corruption, no field injection. Works identically for objects, arrays, and maps. ### [​](https://beads.gascity.com/reference/json-schema#updating-consumers) Updating consumers # Before (legacy): bd list --json | jq '.[0].id' bd show beads-abc --json | jq '.title' # After (envelope): bd list --json | jq '.data[0].id' bd show beads-abc --json | jq '.data.title' # Version check: bd show beads-abc --json | jq '.schema_version' ### [​](https://beads.gascity.com/reference/json-schema#timeline) Timeline * **Current release**: Legacy format is default. Set `BD_JSON_ENVELOPE=1` to opt in. A deprecation notice is printed to stderr when `--json` is used without the env var. * **v2.0**: Envelope becomes the default. `BD_JSON_ENVELOPE=0` available as temporary escape hatch for one release cycle. [​](https://beads.gascity.com/reference/json-schema#schema-version) Schema Version ------------------------------------------------------------------------------------- Current version: **1** The `schema_version` field is an integer that increments when: * Fields are added, renamed, or removed * Output structure changes (e.g., nesting depth) * Field types change (e.g., string to integer) Additive changes (new optional fields) do NOT bump the version. [​](https://beads.gascity.com/reference/json-schema#output-formats) Output Formats ------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/json-schema#envelope-mode-bd_json_envelope=1) Envelope mode (BD\_JSON\_ENVELOPE=1) All commands emit a uniform envelope: { "schema_version": 1, "data": { "id": "beads-abc", "title": "Example issue", "status": "open" } } Arrays are wrapped the same way: { "schema_version": 1, "data": [\ {"id": "beads-abc", "title": "First"},\ {"id": "beads-def", "title": "Second"}\ ] } ### [​](https://beads.gascity.com/reference/json-schema#legacy-mode-default-until-v2-0) Legacy mode (default, until v2.0) ### [​](https://beads.gascity.com/reference/json-schema#object-commands-show-create-close-update-etc) Object commands (show, create, close, update, etc.) Commands that return a single issue or result emit a JSON object with `schema_version` as a top-level field alongside the data: { "schema_version": 1, "id": "beads-abc", "title": "Example issue", "status": "open", "priority": 1, "issue_type": "task", "created_at": "2026-04-20T12:00:00Z" } ### [​](https://beads.gascity.com/reference/json-schema#list-commands-list-ready-search-stale-etc) List commands (list, ready, search, stale, etc.) Commands that return multiple items emit a raw JSON array: [\ {"id": "beads-abc", "title": "First", ...},\ {"id": "beads-def", "title": "Second", ...}\ ] ### [​](https://beads.gascity.com/reference/json-schema#error-output-stderr) Error output (stderr) Errors with `--json` active emit JSON to stderr: { "schema_version": 1, "error": "issue not found: beads-xyz", "code": "not_found" } [​](https://beads.gascity.com/reference/json-schema#field-contracts-by-command) Field Contracts by Command ------------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/json-schema#bd-list-%E2%80%94json) bd list —json Required fields per item: * `id` (string): Issue ID (e.g., “beads-abc”) * `title` (string): Issue title * `status` (string): open, in\_progress, closed, deferred * `priority` (number): 0-4 * `issue_type` (string): bug, feature, task, epic, chore * `created_at` (string): RFC3339 timestamp Optional fields: * `description`, `owner`, `updated_at`, `closed_at` * `labels` (string\[\]): Attached labels * `dependencies` (object\[\]): Dependency records * `dependency_count`, `dependent_count`, `comment_count` (number) * `parent` (string|null): Parent issue ID ### [​](https://beads.gascity.com/reference/json-schema#bd-ready-%E2%80%94json) bd ready —json Same schema as `bd list --json`. Items are filtered to unblocked issues only. Each item includes `dependency_count`, `dependent_count`, `comment_count`, and optional `parent` fields. ### [​](https://beads.gascity.com/reference/json-schema#bd-blocked-%E2%80%94json) bd blocked —json Returns issues that are blocked by unresolved dependencies. Each item includes all standard issue fields plus: * `blocked_by_count` (number): Number of blocking dependencies * `blocked_by` (string\[\]): IDs of blocking issues ### [​](https://beads.gascity.com/reference/json-schema#bd-show-%E2%80%94json) bd show —json Returns a single object (not wrapped in `items`). Same required fields as list items, plus: * `description` (string) * `acceptance_criteria` (string) * `dependencies` (object\[\]): Full dependency records * `comments` (object\[\]): Comment thread — present only with `--include-comments`; the default response returns `comment_count` only (count-only, be-ijck6q) * `comments_omitted` (boolean, optional): `true` only when `comment_count` is nonzero and `comments` was left out of the response (no `--include-comments`). Absent when comments were included or when there are none to omit (ga-clgh) ### [​](https://beads.gascity.com/reference/json-schema#import-json) `import --json` Returns a summary object when `--json` is active: * `source` (string): File path or “stdin” * `created` (number): Issues created * `updated` (number): Existing issues updated * `skipped` (number): Issues skipped (stale rows + dedup) * `dedup_skipped` (number): Issues skipped by `--dedup` title match * `memories` (number): Memory records imported * `ids` (string\[\]): IDs of created issues * `updated_issues` (object\[\]): Per-issue summary of what an update changed * `tie_kept_local_ids` (string\[\]): Equal-`updated_at` rows where local state won * `stale_skipped_ids` (string\[\]): Rows older than the local issue, skipped * `skipped_dependencies` (string\[\]): Dependency edges whose target id was absent * `dry_run` (boolean): Whether `--dry-run` was active ### [​](https://beads.gascity.com/reference/json-schema#bd-export-%E2%80%94json) bd export —json Outputs JSONL (one JSON object per line), not wrapped in an envelope. Each line is a self-contained issue or memory record, discriminated by `_type` (`"issue"` / `"memory"`). Export lines do **not** carry `schema_version` — that field belongs to the `--json` command envelope, not to the interchange stream. The interchange’s own version marker is the optional `_schema` header record (`{"_schema":"beads-jsonl/1"}`), which readers skip. [​](https://beads.gascity.com/reference/json-schema#consumer-guidelines) Consumer Guidelines ----------------------------------------------------------------------------------------------- 1. **Check `schema_version`** on object output. If the version is higher than expected, log a warning but attempt to parse anyway (additive changes are backward-compatible). 2. **For list commands**, parse the output as a JSON array directly. 3. **Ignore unknown fields**. New fields may be added without bumping the schema version. 4. **Use `--json` flag**, not `--format json`. The `--json` flag is the stable contract; `--format` is for human-readable variants. [Advanced Features](https://beads.gascity.com/reference/advanced) [Observability (OpenTelemetry)](https://beads.gascity.com/reference/observability) ⌘I --- # GitHub Copilot - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/github-copilot#content-area) Beads gives Copilot a persistent, structured memory for tracking work: with the MCP server configured, you create, update, and track issues in natural language without leaving the editor. This page covers **Copilot Chat in VS Code via MCP**. For the terminal-based Copilot CLI plugin installed by `bd setup copilot`, see [Copilot CLI](https://beads.gascity.com/integrations/copilot-cli) . [​](https://beads.gascity.com/integrations/github-copilot#prerequisites) Prerequisites ----------------------------------------------------------------------------------------- * VS Code 1.96+ with the GitHub Copilot extension * A GitHub Copilot subscription (Individual, Business, or Enterprise) * The beads CLI installed ([installation guide](https://beads.gascity.com/getting-started/installation) ) * Python 3.10+ or the `uv` package manager [​](https://beads.gascity.com/integrations/github-copilot#setup) Setup ------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/github-copilot#quick-setup) Quick Setup 1. Install beads-mcp: # Using uv (recommended) uv tool install beads-mcp # Or using pip / pipx pip install beads-mcp pipx install beads-mcp 2. Create `.vscode/mcp.json` in your project: { "servers": { "beads": { "command": "beads-mcp" } } } **For all projects:** Add to VS Code user-level MCP config: | Platform | Path | | --- | --- | | macOS | `~/Library/Application Support/Code/User/mcp.json` | | Linux | `~/.config/Code/User/mcp.json` | | Windows | `%APPDATA%\Code\User\mcp.json` | { "servers": { "beads": { "command": "beads-mcp", "args": [] } } } 3. Initialize beads: bd init --quiet This creates a `.beads/` directory with the issue database. 4. Reload VS Code ### [​](https://beads.gascity.com/integrations/github-copilot#verify-setup) Verify Setup Ask Copilot Chat: “What beads issues are ready to work on?” [​](https://beads.gascity.com/integrations/github-copilot#using-natural-language) Using Natural Language ----------------------------------------------------------------------------------------------------------- With MCP configured, interact naturally: You: Create a bug for the login timeout Copilot: Created bd-42: Login timeout bug You: What issues are ready? Copilot: 3 issues ready: bd-42, bd-99, bd-17 You: Claim bd-42, I'll take it Copilot: Claimed bd-42 and started work You: I found a related bug - the session token isn't refreshed. File it, linked to bd-42. Copilot: Created bd-103: Session token not refreshed Linked as discovered-from bd-42 You: Close bd-42 with reason "Fixed timeout handling" Copilot: Closed bd-42: Fixed timeout handling Syncing stays on the CLI: run `bd dolt push` at the end of a session. There is no MCP push tool. [​](https://beads.gascity.com/integrations/github-copilot#mcp-tools) MCP Tools --------------------------------------------------------------------------------- | Tool | Description | You say | | --- | --- | --- | | `ready` | List unblocked issues | ”What can I work on?” | | `list` | List issues with filters | ”Show all open bugs” | | `show` | Show issue details, including dependencies and dependents | ”Show bd-42 details” | | `create` | Create new issue | ”Create a task for refactoring” | | `claim` | Atomically claim an issue (assignee + in\_progress) | “I’ll take bd-42” | | `update` | Update issue fields | ”Set bd-42 to priority 1” | | `close` | Close an issue | ”Complete bd-42” | | `dep` | Add dependency | ”bd-99 blocks bd-42” | | `blocked` | Show blocked issues and their blockers | ”What’s blocking my work?” | | `stats` | Issue counts and average lead time | ”How’s the backlog?” | The server also exposes `reopen`, `comment`, `comments`, `note`, `context`, and `admin`; call `discover_tools` for the full catalog. [​](https://beads.gascity.com/integrations/github-copilot#copilot-instructions) Copilot Instructions ------------------------------------------------------------------------------------------------------- Optionally add `.github/copilot-instructions.md`: ## Issue Tracking This project uses **bd (beads)** for issue tracking. Run `bd prime` for workflow context. Quick reference: - `bd ready` - Find unblocked work - `bd create "Title" --type task --priority 2` - Create issue - `bd close <id>` - Complete work - `bd dolt push` - Push changes to Dolt remote (run at session end) [​](https://beads.gascity.com/integrations/github-copilot#cli-vs-mcp) CLI vs MCP ----------------------------------------------------------------------------------- | Approach | Best for | Trade-off | | --- | --- | --- | | **MCP (Copilot Chat)** | Natural language, discovery | Higher token overhead | | **CLI (terminal)** | Scripting, precision, speed | Requires shell access | Both work against the same database - use MCP for conversational work, the CLI for quick commands. See [MCP Server](https://beads.gascity.com/integrations/mcp-server) for the full trade-off discussion. [​](https://beads.gascity.com/integrations/github-copilot#troubleshooting) Troubleshooting --------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/github-copilot#tools-not-appearing) Tools not appearing 1. Check VS Code 1.96+ 2. Verify mcp.json syntax is valid JSON 3. Reload VS Code window 4. Check Output panel for MCP errors ### [​](https://beads.gascity.com/integrations/github-copilot#%E2%80%9Dbeads-mcp-not-found%E2%80%9D) ”beads-mcp not found” # Check installation which beads-mcp pip show beads-mcp # uv installs to ~/.local/bin - make sure it's on PATH export PATH="$HOME/.local/bin:$PATH" # If installed with pip, find it pip show beads-mcp | grep Location # Reinstall if needed uv tool install beads-mcp --force ### [​](https://beads.gascity.com/integrations/github-copilot#no-database-found) No database found bd init --quiet ### [​](https://beads.gascity.com/integrations/github-copilot#changes-not-persisting) Changes not persisting Push to the Dolt remote at the end of your session, from the terminal: bd dolt push ### [​](https://beads.gascity.com/integrations/github-copilot#organization-policies-blocking-mcp) Organization policies blocking MCP For Copilot Business/Enterprise, your organization must enable the “MCP servers in Copilot” policy. Contact your admin if MCP tools don’t appear despite a correct config. [​](https://beads.gascity.com/integrations/github-copilot#faq) FAQ --------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/github-copilot#do-i-need-to-clone-beads) Do I need to clone beads? **No.** Beads is a system-wide CLI tool. Install once, use everywhere. The `.beads/` directory in your project only contains the issue database. ### [​](https://beads.gascity.com/integrations/github-copilot#what-about-git-hooks) What about git hooks? Git hooks are optional. They refresh exports and legacy fallback checks, while issue sync uses `bd dolt push` / `bd dolt pull`. They never modify your source code; skip them with `bd init --skip-hooks`. ### [​](https://beads.gascity.com/integrations/github-copilot#can-i-use-beads-without-copilot) Can I use beads without Copilot? Yes. The same database works from the terminal, [Claude Code](https://beads.gascity.com/integrations/claude-code) , [Cursor](https://beads.gascity.com/integrations/cursor) , [Aider](https://beads.gascity.com/integrations/aider) , and any editor with MCP or shell access. ### [​](https://beads.gascity.com/integrations/github-copilot#does-this-work-with-copilot-in-other-editors) Does this work with Copilot in other editors? This page covers VS Code. For JetBrains IDEs, check whether your IDE supports MCP; the config location differs. For Neovim, use the CLI directly. For the terminal, see [Copilot CLI](https://beads.gascity.com/integrations/copilot-cli) . [​](https://beads.gascity.com/integrations/github-copilot#see-also) See Also ------------------------------------------------------------------------------- * [MCP Server](https://beads.gascity.com/integrations/mcp-server) - Detailed MCP configuration * [Copilot CLI](https://beads.gascity.com/integrations/copilot-cli) - Terminal-based Copilot integration * [Quickstart](https://beads.gascity.com/getting-started/quickstart) - bd command basics * [Installation](https://beads.gascity.com/getting-started/installation) - Full install guide * [Agent Instructions](https://github.com/gastownhall/beads/blob/main/AGENT_INSTRUCTIONS.md) - Full agent workflow reference [MCP Server](https://beads.gascity.com/integrations/mcp-server) [GitHub Copilot CLI Integration Design](https://beads.gascity.com/integrations/copilot-cli) ⌘I --- # Junie - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/junie#content-area) How to use beads with Junie (JetBrains AI Agent). [​](https://beads.gascity.com/integrations/junie#setup) Setup ---------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/junie#quick-setup) Quick Setup bd setup junie This creates: * **`.junie/guidelines.md`** - Agent instructions for beads workflow * **`.junie/mcp/mcp.json`** - MCP server configuration ### [​](https://beads.gascity.com/integrations/junie#verify-setup) Verify Setup bd setup junie --check [​](https://beads.gascity.com/integrations/junie#how-it-works) How It Works ------------------------------------------------------------------------------ 1. **Session starts** → Junie reads `.junie/guidelines.md` for workflow context 2. **MCP tools available** → Junie can use beads MCP tools directly 3. **You work** → Use `bd` CLI commands or MCP tools 4. **Session ends** → Run `bd dolt push` to push changes to Dolt remote [​](https://beads.gascity.com/integrations/junie#configuration-files) Configuration Files -------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/junie#guidelines-junie/guidelines-md) Guidelines (`.junie/guidelines.md`) Contains workflow instructions that Junie reads automatically: * Core workflow rules * Command reference * Issue types and priorities * MCP tool documentation ### [​](https://beads.gascity.com/integrations/junie#mcp-config-junie/mcp/mcp-json) MCP Config (`.junie/mcp/mcp.json`) `bd setup junie` currently writes an MCP config that invokes `bd mcp`, a command that does not exist in current bd builds — that config will not start a server. Until the recipe is fixed, point Junie at the standalone `beads-mcp` server instead: { "mcpServers": { "beads": { "command": "uvx", "args": ["beads-mcp"] } } } See [MCP Server](https://beads.gascity.com/integrations/mcp-server) for the server’s tool catalog and other install options (pip/pipx). [​](https://beads.gascity.com/integrations/junie#cli-commands) CLI Commands ------------------------------------------------------------------------------ You can also use the `bd` CLI directly: ### [​](https://beads.gascity.com/integrations/junie#creating-issues) Creating Issues # Always include description for context bd create "Fix authentication bug" \ --description="Login fails with special characters in password" \ -t bug -p 1 --json # Link discovered issues bd create "Found SQL injection" \ --description="User input not sanitized in query builder" \ --deps discovered-from:bd-42 --json ### [​](https://beads.gascity.com/integrations/junie#working-on-issues) Working on Issues # Find ready work bd ready --json # Start work bd update bd-42 --claim --json # Complete work bd close bd-42 --reason "Fixed in commit abc123" --json ### [​](https://beads.gascity.com/integrations/junie#querying) Querying # List open issues bd list --status open --json # Show issue details bd show bd-42 --json # Check blocked issues bd blocked --json ### [​](https://beads.gascity.com/integrations/junie#syncing) Syncing # ALWAYS run at session end bd dolt push [​](https://beads.gascity.com/integrations/junie#best-practices) Best Practices ---------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/junie#always-use-json) Always Use `--json` bd list --json # Parse programmatically bd create "Task" --json # Get issue ID from output bd show bd-42 --json # Structured data ### [​](https://beads.gascity.com/integrations/junie#always-include-descriptions) Always Include Descriptions # Good bd create "Fix auth bug" \ --description="Login fails when password contains quotes" \ -t bug -p 1 --json # Bad - no context for future work bd create "Fix auth bug" -t bug -p 1 --json ### [​](https://beads.gascity.com/integrations/junie#link-related-work) Link Related Work # When you discover issues during work bd create "Found related bug" \ --deps discovered-from:bd-current --json ### [​](https://beads.gascity.com/integrations/junie#push-before-session-end) Push Before Session End # ALWAYS run before ending bd dolt push [​](https://beads.gascity.com/integrations/junie#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/integrations/junie#guidelines-not-loaded) Guidelines not loaded # Check setup bd setup junie --check # Reinstall if needed bd setup junie ### [​](https://beads.gascity.com/integrations/junie#mcp-tools-not-available) MCP tools not available # Verify MCP config exists and points at the beads-mcp server cat .junie/mcp/mcp.json # Verify the server package is installed pip show beads-mcp ### [​](https://beads.gascity.com/integrations/junie#changes-not-syncing) Changes not syncing # Force push bd dolt push # Check system health bd doctor ### [​](https://beads.gascity.com/integrations/junie#database-not-found) Database not found # Initialize beads bd init --quiet [​](https://beads.gascity.com/integrations/junie#removing-integration) Removing Integration ---------------------------------------------------------------------------------------------- bd setup junie --remove This removes: * `.junie/guidelines.md` * `.junie/mcp/mcp.json` * Empty `.junie/mcp/` and `.junie/` directories [​](https://beads.gascity.com/integrations/junie#see-also) See Also ---------------------------------------------------------------------- * [MCP Server](https://beads.gascity.com/integrations/mcp-server) - MCP server details * [Claude Code](https://beads.gascity.com/integrations/claude-code) - Similar hook-based integration * [IDE Setup](https://beads.gascity.com/getting-started/ide-setup) - Other editors [Gemini CLI](https://beads.gascity.com/integrations/gemini) [Kilo Code](https://beads.gascity.com/integrations/kilocode) ⌘I --- # Formulas - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/workflows/formulas#content-area) Formulas are declarative workflow templates. [​](https://beads.gascity.com/workflows/formulas#formula-format) Formula Format ---------------------------------------------------------------------------------- Formulas can be written in TOML (preferred) or JSON: ### [​](https://beads.gascity.com/workflows/formulas#toml-format) TOML Format formula = "feature-workflow" description = "Standard feature development workflow" version = 1 type = "workflow" [vars.feature_name] description = "Name of the feature" required = true [[steps]] id = "design" title = "Design {{feature_name}}" type = "human" description = "Create design document" [[steps]] id = "implement" title = "Implement {{feature_name}}" needs = ["design"] [[steps]] id = "review" title = "Code review" needs = ["implement"] type = "human" [[steps]] id = "merge" title = "Merge to main" needs = ["review"] ### [​](https://beads.gascity.com/workflows/formulas#json-format) JSON Format { "formula": "feature-workflow", "description": "Standard feature development workflow", "version": 1, "type": "workflow", "vars": { "feature_name": { "description": "Name of the feature", "required": true } }, "steps": [\ {\ "id": "design",\ "title": "Design {{feature_name}}",\ "type": "human"\ },\ {\ "id": "implement",\ "title": "Implement {{feature_name}}",\ "needs": ["design"]\ }\ ] } [​](https://beads.gascity.com/workflows/formulas#formula-types) Formula Types -------------------------------------------------------------------------------- | Type | Description | | --- | --- | | `workflow` | Standard step sequence | | `expansion` | Template for expansion operator | | `aspect` | Cross-cutting concerns | [​](https://beads.gascity.com/workflows/formulas#variables) Variables ------------------------------------------------------------------------ Define variables with defaults and constraints: [vars.version] description = "Release version" required = true pattern = "^\\d+\\.\\d+\\.\\d+$" [vars.environment] description = "Target environment" default = "staging" enum = ["staging", "production"] Use variables in steps: [[steps]] title = "Deploy {{version}} to {{environment}}" [​](https://beads.gascity.com/workflows/formulas#step-types) Step Types -------------------------------------------------------------------------- A step’s `type` sets the issue type of the bead it creates: `task` (default), `bug`, `feature`, `epic`, or `chore`. Any other value falls back to `task`. Human sign-offs and async waits are expressed with a `[steps.gate]` block, not a step type — see [Gates](https://beads.gascity.com/workflows/gates) . [​](https://beads.gascity.com/workflows/formulas#dependencies) Dependencies ------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/workflows/formulas#sequential) Sequential [[steps]] id = "step1" title = "First step" [[steps]] id = "step2" title = "Second step" needs = ["step1"] ### [​](https://beads.gascity.com/workflows/formulas#parallel-then-join) Parallel then Join [[steps]] id = "test-unit" title = "Unit tests" [[steps]] id = "test-integration" title = "Integration tests" [[steps]] id = "deploy" title = "Deploy" needs = ["test-unit", "test-integration"] # Waits for both [​](https://beads.gascity.com/workflows/formulas#gates) Gates ---------------------------------------------------------------- Add gates for async coordination: [[steps]] id = "approval" title = "Manager approval" type = "human" [steps.gate] type = "human" approvers = ["manager"] [[steps]] id = "deploy" title = "Deploy to production" needs = ["approval"] [​](https://beads.gascity.com/workflows/formulas#aspects-cross-cutting) Aspects (Cross-cutting) -------------------------------------------------------------------------------------------------- Apply transformations to matching steps: formula = "security-scan" type = "aspect" [[advice]] target = "*.deploy" # Match all deploy steps [advice.before] id = "security-scan-{step.id}" title = "Security scan before {step.title}" [​](https://beads.gascity.com/workflows/formulas#formula-locations) Formula Locations ---------------------------------------------------------------------------------------- Formulas are searched in order: 1. `.beads/formulas/` (project-level) 2. `~/.beads/formulas/` (user-level) `bd formula list` shows everything visible on the search paths. [​](https://beads.gascity.com/workflows/formulas#using-formulas) Using Formulas ---------------------------------------------------------------------------------- # List available formulas bd formula list # Cook the formula into a proto, then pour it into a molecule bd cook <formula-file> bd mol pour <proto-id> --var key=value # Preview what would be created bd mol pour <proto-id> --dry-run [​](https://beads.gascity.com/workflows/formulas#creating-custom-formulas) Creating Custom Formulas ------------------------------------------------------------------------------------------------------ 1. Create file: `.beads/formulas/my-workflow.formula.toml` 2. Define structure (see examples above) 3. Use with: `bd cook my-workflow` then `bd mol pour <proto-id>` [​](https://beads.gascity.com/workflows/formulas#example-release-formula) Example: Release Formula ----------------------------------------------------------------------------------------------------- formula = "release" description = "Standard release workflow" version = 1 [vars.version] required = true pattern = "^\\d+\\.\\d+\\.\\d+$" [[steps]] id = "bump-version" title = "Bump version to {{version}}" [[steps]] id = "changelog" title = "Update CHANGELOG" needs = ["bump-version"] [[steps]] id = "test" title = "Run full test suite" needs = ["changelog"] [[steps]] id = "build" title = "Build release artifacts" needs = ["test"] [[steps]] id = "tag" title = "Create git tag v{{version}}" needs = ["build"] [[steps]] id = "publish" title = "Publish release" needs = ["tag"] type = "human" [Molecules](https://beads.gascity.com/workflows/molecules) [Gates](https://beads.gascity.com/workflows/gates) ⌘I --- # Claude Code - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/claude-code#content-area) How to use beads with Claude Code. [​](https://beads.gascity.com/integrations/claude-code#setup) Setup ---------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/claude-code#quick-setup) Quick Setup bd setup claude This installs: * **SessionStart hook** - Runs `bd prime --hook-json` when a session starts. SessionStart also fires after context compaction, so the same hook refreshes context automatically. * **CLAUDE.md pointer** - A minimal beads section in your project’s `CLAUDE.md` (skipped if `CLAUDE.md` is a symlink). By default the hook is written to the project’s `.claude/settings.json`. Variants: bd setup claude --global # Install to ~/.claude/settings.json instead bd setup claude --stealth # Stealth mode: flush only, no git operations bd setup claude --remove # Remove the hook and the CLAUDE.md section If the [beads plugin](https://beads.gascity.com/integrations/claude-code-plugin) is enabled, `bd setup claude` skips writing hooks - the plugin provides its own, and duplicates would run `bd prime` twice per session. ### [​](https://beads.gascity.com/integrations/claude-code#manual-setup) Manual Setup Add to `.claude/settings.json` (project) or `~/.claude/settings.json` (global): { "hooks": { "SessionStart": [\ {\ "matcher": "",\ "hooks": [\ { "type": "command", "command": "bd prime --hook-json" }\ ]\ }\ ] } } The `--hook-json` flag wraps the output in the hook JSON envelope Claude Code expects. No `PreCompact` hook is needed - SessionStart fires again after compaction. ### [​](https://beads.gascity.com/integrations/claude-code#verify-setup) Verify Setup bd setup claude --check [​](https://beads.gascity.com/integrations/claude-code#how-it-works) How It Works ------------------------------------------------------------------------------------ 1. **Session starts** → `bd prime` injects ~1-2k tokens of context 2. **You work** → Use `bd` CLI commands directly 3. **Session compacts** → SessionStart fires again and `bd prime` refreshes workflow context 4. **Session ends** → `bd dolt push` syncs changes ### [​](https://beads.gascity.com/integrations/claude-code#why-cli-+-hooks-instead-of-mcp) Why CLI + hooks instead of MCP? Context efficiency. MCP tool schemas can add 10-50k tokens to every request; `bd prime` adds ~1-2k tokens of workflow context - 10-50x less overhead, which means lower cost, lower latency, and better model attention. Prefer CLI + hooks in any environment with shell access; use the [MCP server](https://beads.gascity.com/integrations/mcp-server) only where the CLI is unavailable, such as Claude Desktop. ### [​](https://beads.gascity.com/integrations/claude-code#why-not-claude-skills) Why not Claude Skills? Beads doesn’t ship or require Claude Skills (`.claude/skills/`). `bd prime` already delivers the workflow context, and the workflow fits a simple command set (ready → create → update → close → sync). Skills are also Claude-specific, which would break beads’ editor-agnostic approach - the same CLI works in Cursor, Windsurf, and every other shell-capable editor. You can create your own Skills on top of beads, but none are needed. [​](https://beads.gascity.com/integrations/claude-code#essential-commands-for-agents) Essential Commands for Agents ---------------------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/claude-code#creating-issues) Creating Issues # Always include description for context bd create "Fix authentication bug" \ --description="Login fails with special characters in password" \ -t bug -p 1 --json # Link discovered issues bd create "Found SQL injection" \ --description="User input not sanitized in query builder" \ --deps discovered-from:bd-42 --json ### [​](https://beads.gascity.com/integrations/claude-code#working-on-issues) Working on Issues # Find ready work bd ready --json # Start work bd update bd-42 --claim --json # Complete work bd close bd-42 --reason "Fixed in commit abc123" --json ### [​](https://beads.gascity.com/integrations/claude-code#querying) Querying # List open issues bd list --status open --json # Show issue details bd show bd-42 --json # Check blocked issues bd blocked --json ### [​](https://beads.gascity.com/integrations/claude-code#syncing) Syncing # ALWAYS run at session end bd dolt push [​](https://beads.gascity.com/integrations/claude-code#best-practices) Best Practices ---------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/claude-code#always-use-json) Always Use `--json` bd list --json # Parse programmatically bd create "Task" --json # Get issue ID from output bd show bd-42 --json # Structured data ### [​](https://beads.gascity.com/integrations/claude-code#always-include-descriptions) Always Include Descriptions # Good bd create "Fix auth bug" \ --description="Login fails when password contains quotes" \ -t bug -p 1 --json # Bad - no context for future work bd create "Fix auth bug" -t bug -p 1 --json ### [​](https://beads.gascity.com/integrations/claude-code#link-related-work) Link Related Work # When you discover issues during work bd create "Found related bug" \ --deps discovered-from:bd-current --json ### [​](https://beads.gascity.com/integrations/claude-code#push-before-session-end) Push Before Session End # ALWAYS run before ending bd dolt push [​](https://beads.gascity.com/integrations/claude-code#plugin-optional) Plugin (Optional) -------------------------------------------------------------------------------------------- For slash commands and enhanced UX, install the [beads plugin](https://beads.gascity.com/integrations/claude-code-plugin) : # In Claude Code /plugin marketplace add gastownhall/beads /plugin install beads # Restart Claude Code Adds slash commands: * `/beads:ready` - Show ready work * `/beads:create` - Create issue * `/beads:show` - Show issue * `/beads:update` - Update issue * `/beads:close` - Close issue [​](https://beads.gascity.com/integrations/claude-code#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/integrations/claude-code#context-not-injected) Context not injected # Check hook setup bd setup claude --check # Manually prime bd prime ### [​](https://beads.gascity.com/integrations/claude-code#changes-not-syncing) Changes not syncing # Force push bd dolt push # Check system health bd doctor ### [​](https://beads.gascity.com/integrations/claude-code#database-not-found) Database not found # Initialize beads bd init --quiet [​](https://beads.gascity.com/integrations/claude-code#see-also) See Also ---------------------------------------------------------------------------- * [Beads Claude Code Plugin](https://beads.gascity.com/integrations/claude-code-plugin) - Packaged plugin with slash commands * [MCP Server](https://beads.gascity.com/integrations/mcp-server) - For MCP-only environments * [IDE Setup](https://beads.gascity.com/getting-started/ide-setup) - Other editors [Aider](https://beads.gascity.com/integrations/aider) [Beads Claude Code Plugin](https://beads.gascity.com/integrations/claude-code-plugin) ⌘I --- # Community Tools - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/community-tools#content-area) A curated list of community-built UIs, extensions, and integrations for Beads. Ranked by activity and maturity. > **Note:** Beads uses a Dolt SQL database for storage. Tools should use the `bd` CLI (`bd list --json`, etc.) to access data. Tools that read the old `.beads/issues.jsonl` format directly are not compatible with current versions. [​](https://beads.gascity.com/community-tools#terminal-uis) Terminal UIs --------------------------------------------------------------------------- * **[Mardi Gras](https://github.com/quietpublish/mardi-gras) ** - Parade-themed terminal UI with real-time updates, multi-agent orchestration, tmux integration, and Claude Code dispatch. Uses `bd list --json`. Built by [@matt-wright86](https://github.com/matt-wright86) . (Go) * **[perles](https://github.com/zjrosen/perles) ** - Terminal UI search, dependency and kanban viewer powered by a custom BQL (Beads Query Language). Built by [@zjrosen](https://github.com/zjrosen) . (Go) [​](https://beads.gascity.com/community-tools#web-uis) Web UIs ----------------------------------------------------------------- * **[bd-board](https://github.com/jeanpfs/bd-board) ** - Local-first web dashboard for browsing Beads projects, viewing kanban boards by status or epic swimlanes, and filtering by priority, text search, or sort order. Uses the `bd` CLI for Dolt compatibility, with writes disabled unless explicitly enabled. Built by [@jeanpfs](https://github.com/jeanpfs) . (TanStack Start/React) * **[beads-ui](https://github.com/mantoni/beads-ui) ** - Local web interface with live updates and kanban board. Uses the `bd` CLI for Dolt compatibility. Run with `npx beads-ui start`. Built by [@mantoni](https://github.com/mantoni) . (Node.js) * **[BeadBoard](https://github.com/zenchantlive/beadboard) ** - Multi-agent orchestration and communication system with a live dashboard. Agent-to-agent messaging (HANDOFF/BLOCKED/DECISION/INFO), DAG dependency graph, swarm coordination with archetypes and templates, scope-based work reservations, and an embedded execution runtime (bb-pi) built on [Pi](https://github.com/badlogic/pi-mono) that spawns typed worker agents. Cross-platform (macOS, Linux, Windows). Includes the `beadboard-driver` skill for agent integration (`npx skills add zenchantlive/beadboard --skill beadboard-driver`). Built by [@zenchantlive](https://github.com/zenchantlive) . (Next.js/TypeScript) * **[beads-web](https://github.com/weselow/beads-web) ** - Actively maintained fork of beads-kanban-ui. Cross-platform single-binary distribution (macOS, Linux, Windows), 7 visual themes, Dolt direct SQL integration, Windows multi-drive path support, drag-and-drop status updates. Download from [GitHub Releases](https://github.com/weselow/beads-web/releases) . Built by [@weselow](https://github.com/weselow) . (TypeScript/Rust) * **[Bead Me Up, Scotty](https://github.com/brendan-appstart/bead-me-up-scotty) ** - Polished multi-project web UI for creating, updating, and prioritizing beads across all your repos from one place. Kanban board with drag-and-drop status changes and reordering, plus list, epics (with progress bars), and dependency-graph views; faceted filtering and full-text search; live updates via SSE that react the moment `.beads/` changes; and human-vs-agent attribution throughout. Uses the `bd` CLI for full Dolt compatibility. Global install (`scotty`) opens the current directory’s project in your browser, and a built-in Publish view generates a shareable static showcase site from your beads. Live demo at [beadmeupscotty.com](https://beadmeupscotty.com/) . Built by [@brendan-appstart](https://github.com/brendan-appstart) . (Next.js/TypeScript) [​](https://beads.gascity.com/community-tools#editor-extensions) Editor Extensions ------------------------------------------------------------------------------------- * **[vscode-beads](https://marketplace.visualstudio.com/items?itemName=planet57.vscode-beads) ** - VS Code extension with issues panel and server management. Built by [@jdillon](https://github.com/jdillon) . (TypeScript) * **[opencode-beads](https://github.com/joshuadavidthomas/opencode-beads) ** - OpenCode plugin with automatic context injection, `/bd-*` slash commands, and autonomous task agent. Built by [@joshuadavidthomas](https://github.com/joshuadavidthomas) . (Node.js) * **[Lista Beads](https://marketplace.visualstudio.com/items?itemName=ListaDev.lista-beads) ** - Full-featured VS Code extension: filterable tree view, issue detail panel, dashboard with metrics, dependency graph, Dolt push/pull, CodeLens for bead references, wisps & formula support, stale issue management, and multi-tracker sync (Azure DevOps, GitHub, Jira, Linear, GitLab). Built by [@harry-miller-trimble](https://github.com/harry-miller-trimble) . (TypeScript) * **[nvim-beads (fancypantalons)](https://github.com/fancypantalons/nvim-beads) ** - Neovim plugin for managing Beads issues. By [@fancypantalons](https://github.com/fancypantalons) . (Lua) * **[beads.nvim](https://github.com/tomfordweb/beads.nvim) ** - Neovim UI for managing Beads issues — ready queue, editable floating detail view, create/quick-capture, Telescope pickers, memories, and dependency graph. Uses the `bd` CLI for Dolt compatibility. By [@tomfordweb](https://github.com/tomfordweb) . (Lua) * **[beads-manager](https://plugins.jetbrains.com/plugin/30089-beads-manager) ** - Jetbrains IDE plugin to manage and view bead details. Maintained by [@developmeh](https://github.com/developmeh) . (Kotlin) [​](https://beads.gascity.com/community-tools#native-apps) Native Apps ------------------------------------------------------------------------- * **[Beads Task-Issue Tracker](https://github.com/w3dev33/beads-task-issue-tracker) ** - Cross-platform desktop application (macOS, Windows, Linux) for browsing, creating, and managing Beads issues with a visual interface. Features multi-project support with favorites, image attachments, dashboard with statistics, advanced filtering, and dark/light theme. Built by [@w3dev33](https://github.com/w3dev33) . (Tauri/Vue) * **[Beadbox](https://github.com/beadbox/beadbox) ** - Native macOS dashboard with real-time sync, epic tree progress bars, multi-workspace support, and inline editing. Install with `brew tap beadbox/cask && brew install --cask beadbox`. Built by [@nmelo](https://github.com/nmelo) . (Tauri/Next.js) * **[BeadSpec](https://github.com/boardthatpowder/BeadSpec) ** - Cross-platform native desktop app (macOS, Windows, Linux) with first-class [OpenSpec](https://github.com/gastownhall/openspec) integration — the only Beads GUI that surfaces in-flight change proposals alongside the task list, lets you open spec artifacts in side-by-side tabs, imports a change’s task list to Beads in one click, and shows which OpenSpec change each issue was imported from. Also includes an interactive dependency graph (React Flow + Cytoscape), IDE-style workspace tabs with split panes, a global quick-capture shortcut, system tray, command palette, TipTap Markdown description editor, human decision queue, and optional [Ruflo](https://github.com/gastownhall/ruflo) memory integration. Reads Dolt SQL directly for speed; writes through `bd` to preserve hook logic and ID assignment. Download from [GitHub Releases](https://github.com/boardthatpowder/BeadSpec/releases) . Built by [@boardthatpowder](https://github.com/boardthatpowder) . (Tauri/React/TypeScript) * **[Beadazzle](https://github.com/Mosnar/beadazzle) ** - Fully native, fully open-source macOS app (SwiftUI, macOS 14+) for browsing and managing Beads issues, tuned for large embedded-mode projects. Unlike the Tauri-based clients, it’s built directly on SwiftUI/AppKit for a fast, dense, Linear-inspired desktop UI. Features a sidebar/list/detail layout with outline mode, search, filtering, sorting, and multi-selection; full detail editing with rich Markdown editing and live preview (title, description, design, acceptance criteria, notes, labels, status, priority, assignee, dates); a dedicated gate queue with approve/reject and gate-aware blockers; parent/sub-issue hierarchies with breadcrumbs and inline child creation; fast dependency pickers with quick-create; and a project storage view for Dolt remote health, explicit pull/push, and snapshot freshness. Requires a current Dolt-backed project in embedded, server, or shared-server mode, resolved through `bd context` — legacy SQLite-backed projects are intentionally unsupported. Reads by asking `bd export` for a readable JSONL snapshot in the tracker directory `bd` reports — creating one if none exists, and re-exporting after mutations and manual refreshes — then indexes it in memory for responsive navigation; all writes route through `bd` to preserve Beads hooks, history, and validation. Zero telemetry, analytics, or crash reporting — everything stays local on your machine. Ships as a signed and notarized DMG with Sparkle auto-updates. Built by [@Mosnar](https://github.com/Mosnar) . (Native macOS/SwiftUI) [​](https://beads.gascity.com/community-tools#data-source-middleware) Data Source Middleware ----------------------------------------------------------------------------------------------- * **[stringer](https://github.com/davetashner/stringer) ** - Codebase archaeology CLI that mines git repos for TODOs, churn hotspots, lottery-risk files, dependency health, and more. Outputs JSONL compatible with `bd init --from-jsonl`. Install with `brew install davetashner/tap/stringer`. Built by [@davetashner](https://github.com/davetashner) . (Go) [​](https://beads.gascity.com/community-tools#analytics-&-observability) Analytics & Observability ----------------------------------------------------------------------------------------------------- * **[Thread](https://github.com/jklenk/thread) ** - Read-only forensics and analytics layer for Beads. Reads local Dolt history and produces fidelity scores, rework cost metrics, session compliance scoring, and a self-contained HTML report. Add `Run 'thread prime --json' at session start` to your `AGENTS.md` to give agents project health context before they claim their first bead. Install with `uv tool install git+https://github.com/jklenk/thread`. Built by [@jklenk](https://github.com/jklenk) . (Python/DuckDB) * **[emBEADings](https://github.com/DyrtyJax/embeadings) ** - Technical-preview, read-only coordination CLI that turns typed Beads relationships, local semantic retrieval, and active Git worktree changes into bounded, deterministic review leads. Reads the live tracker through allowlisted `bd --readonly ... --json` commands, embeds issue text locally, and has no tracker-write operations. Install from [PyPI](https://pypi.org/project/embeadings/) with `pipx install embeadings` or `uv tool install embeadings`. Built by [@DyrtyJax](https://github.com/DyrtyJax) . (Python) [​](https://beads.gascity.com/community-tools#sdks-&-libraries) SDKs & Libraries ----------------------------------------------------------------------------------- * **[beads-sdk](https://github.com/HerbCaudill/beads-sdk) ** - Typed TypeScript SDK with zero runtime dependencies. High-level `BeadsClient` for CRUD, filtering, search, labels, dependencies, comments, epics, and sync. Install with `pnpm add @herbcaudill/beads-sdk`. Built by [@HerbCaudill](https://github.com/HerbCaudill) . (TypeScript) [​](https://beads.gascity.com/community-tools#claude-code-orchestration) Claude Code Orchestration ----------------------------------------------------------------------------------------------------- * **[Foolery](https://github.com/acartine/foolery) ** - Local web UI that sits on top of Beads, giving you a visual control surface for organizing, orchestrating, and reviewing AI agent work. Features dependency-aware wave planning, a built-in terminal for live agent monitoring, a verification queue for reviewing completed beats, and keyboard-first navigation. Install with `curl -fsSL https://raw.githubusercontent.com/acartine/foolery/main/scripts/install.sh | bash`. Built by [@acartine](https://github.com/acartine) . (Next.js/TypeScript) * **[beads-compound](https://github.com/roberto-mello/beads-compound-plugin) ** - Claude Code plugin marketplace with persistent memory and compound-engineering workflows. Hooks auto-capture knowledge from `bd comments add` at session end and inject relevant entries at session start based on open beads. Includes 28 specialized agents, 26 commands, and 15 skills for planning, review, research, and parallel work. Also supports OpenCode and Gemini CLI. Built by [@roberto-mello](https://github.com/roberto-mello) . (Bash/TypeScript) * **[claude-handoff](https://github.com/REMvisual/claude-handoff) ** - Session handoff skills for Claude Code. Captures decisions, failed approaches, measurements, and next steps into structured files so the next session picks up where you left off. Uses bead IDs as chain tags for multi-session continuity, auto-detects active beads, and updates bead notes on close. Includes `/handoff`, `/handoffplan`, and a PreCompact safety-net hook. Built by [@REMvisual](https://github.com/REMvisual) . (Markdown/Bash) * **[claude-workspace-snapshot](https://github.com/REMvisual/claude-workspace-snapshot) ** - Snapshot and restore live Claude Code sessions as named, color-coded Windows Terminal tabs. Detects running sessions via process inspection and .jsonl file activity. Restores tab layout after any restart. Pairs with claude-handoff for full session continuity. Built by [@REMvisual](https://github.com/REMvisual) . (PowerShell/Batch) * **[claude-protocol](https://github.com/weselow/claude-protocol) ** - Actively maintained fork of beads-orchestration. Ground-up rewrite optimized for Claude 4.6 family models: trigger-based dev rules (TDD, logging, resilience), cross-platform Node.js hooks (replaced 19 bash scripts with 8 .cjs hooks), mandatory checklist verification, session-start dashboard, knowledge base with auto-capture. Install via `npx claude-protocol init`. Built by [@weselow](https://github.com/weselow) . (Node.js/Python) * **[LoopTroop](https://github.com/looptroop-ai/LoopTroop) ** - Local AI coding orchestrator for automated task planning, execution, and feedback loops. Uses a Beads-inspired methodology with LLM Council consensus and worktree isolation. Built by [@looptroop-ai](https://github.com/looptroop-ai) . (Node.js/TypeScript) [​](https://beads.gascity.com/community-tools#coordination-servers) Coordination Servers ------------------------------------------------------------------------------------------- * **[BeadHub](https://github.com/beadhub/beadhub) ** - Open-source coordination server for AI agent teams running beads. The `bdh` CLI is a transparent wrapper over `bd` that adds work claiming, file reservation, presence awareness, and inter-agent messaging (async mail and sync chat). Includes a web dashboard. Free hosted at beadhub.ai for open-source projects. Built by [@juanre](https://github.com/juanre) . (Python/TypeScript) [​](https://beads.gascity.com/community-tools#historical-/-stale) Historical / Stale --------------------------------------------------------------------------------------- * **[bdui](https://github.com/assimelha/bdui) ** - Real-time terminal UI with tree view, dependency graph, and vim-style navigation. Built by [@assimelha](https://github.com/assimelha) . (Node.js) * **[beads.el](https://codeberg.org/ctietze/beads.el) ** - Emacs UI to browse, edit, and manage beads. Built by [@ctietze](https://codeberg.org/ctietze) . (Elisp) * **[lazybeads](https://github.com/codegangsta/lazybeads) ** - Lightweight terminal UI built with Bubble Tea for browsing and managing beads issues. Built by [@codegangsta](https://github.com/codegangsta) . (Go) * **[bsv](https://github.com/bglenden/bsv) ** - Simple two-panel terminal (TUI) viewer with tree navigation organized by epic/task/sub-task, markdown rendering, and mouse support. Built by [@bglenden](https://github.com/bglenden) . (Rust) * **[abacus](https://github.com/ChrisEdwards/abacus) ** - A powerful terminal UI for visualizing and navigating Beads issue tracking databases. * **[beads-viz-prototype](https://github.com/mattbeane/beads-viz-prototype) ** - Web-based visualization generating interactive HTML from `bd export`. Built by [@mattbeane](https://github.com/mattbeane) . (Python) * **[beads-dashboard](https://github.com/rhydlewis/beads-dashboard) ** - A local, lean metrics dashboard for your beads data. Provides insights into lead time, throughput and other continuous improvement metrics. Includes a filterable table view of “all issues”. Built by [@rhydlewis](https://github.com/rhydlewis) . (Node.js/React) * **[beads-kanban-ui](https://github.com/AvivK5498/Beads-Kanban-UI) ** - Visual Kanban board with git branch status tracking, epic/subtask management, design doc viewer, and activity timeline. Install via npm: `npm install -g beads-kanban-ui`. Built by [@AvivK5498](https://github.com/AvivK5498) . (TypeScript/Rust) * **[beads-pm-ui](https://github.com/qosha1/beads-pm-ui) ** - Gantt chart timeline view, project / team based filtering (via folder structure), quarterly goal setting and dependency chain visualization. Inline editable. Built by [@qosha1](https://github.com/qosha1) . (Nextjs/Typscript) * **[Beadspace](https://github.com/cameronsjo/beadspace) ** - Drop-in GitHub Pages dashboard with triage suggestions, priority/status breakdowns, and searchable issue table. Single HTML file, zero build dependencies, auto-deploys via GitHub Action. Built by [@cameronsjo](https://github.com/cameronsjo) . (HTML/CSS/JS) * **[beadsmap](https://github.com/dariye/beadsmap) ** - Interactive roadmap visualization with timeline (Gantt), list, and table views. Multi-source support, dependency arrows, milestone grouping, GitHub integration via OAuth device flow, and light/dark/system themes. Ships as a single `index.html`. Built by [@dariye](https://github.com/dariye) . (Svelte/TypeScript) * **[Agent Native Abstraction Layer for Beads](https://marketplace.visualstudio.com/items?itemName=AgentNativeAbstractionLayer.agent-native-kanban) ** (ANAL Beads) - VS Code Kanban board. Maintained by [@sebcook-ctrl](https://github.com/sebcook-ctrl) . (Node.js) * **[Beads-Kanban](https://github.com/davidcforbes/Beads-Kanban) ** - VS Code Kanban board for Beads issue tracking. Maintained by [@davidcforbes](https://github.com/davidcforbes) . (TypeScript) * **[nvim-beads](https://github.com/joeblubaugh/nvim-beads) ** - Neovim plugin for managing beads. Built by [@joeblubaugh](https://github.com/joeblubaugh) . (Lua) * **[Beadster](https://github.com/beadster/beadster) ** - macOS app for browsing and managing issues from `.beads/` directories in git repositories. Built by [@podviaznikov](https://github.com/podviaznikov) . (Swift) * **[Parade](https://github.com/JeremyKalmus/parade) ** - Electron app for workflow orchestration with visual Kanban board, discovery wizard, and task visualization. Run with `npx parade-init`. Built by [@JeremyKalmus](https://github.com/JeremyKalmus) . (Electron/React) * **[jira-beads-sync](https://github.com/conallob/jira-beads-sync) ** - CLI tool & Claude Code plugin to sync tasks from Jira into beads and publish beads task states back to Jira. Built by [@conallob](https://github.com/conallob) . (Go) * **[beads-orchestration](https://github.com/AvivK5498/Claude-Code-Beads-Orchestration) ** - Multi-agent orchestration skill for Claude Code. Orchestrator investigates issues, manages beads tasks automatically, and delegates to tech-specific supervisors on isolated branches. Includes hooks for workflow enforcement, epic/subtask support, and optional external provider delegation (Codex/Gemini). Install via npm: `npm install -g @avivkaplan/beads-orchestration`. Built by [@AvivK5498](https://github.com/AvivK5498) . (Node.js/Python) * **[beads\_viewer](https://github.com/Dicklesworthstone/beads_viewer) ** - Terminal interface with tree navigation and vim-style commands. Not compatible with Dolt-based beads (v0.50+); see [issue #121](https://github.com/Dicklesworthstone/beads_viewer/issues/121) . Built by [@Dicklesworthstone](https://github.com/Dicklesworthstone) . (Go) * **[beady](https://github.com/maphew/beady) ** - Early prototype effort, now stale. Built by [@maphew](https://github.com/maphew) . (Go) [​](https://beads.gascity.com/community-tools#discussion) Discussion ----------------------------------------------------------------------- See [GitHub Discussions #276](https://github.com/gastownhall/beads/discussions/276) for ongoing UI development conversations, design decisions, and community contributions. [​](https://beads.gascity.com/community-tools#contributing) Contributing --------------------------------------------------------------------------- Found or built a tool? Open a PR to add it to this list or comment on discussion #276. [Azure DevOps (ADO) Integration Configuration](https://beads.gascity.com/integrations/azure-devops) [Related Projects](https://beads.gascity.com/related-projects) ⌘I --- # Adaptive ID Length - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/core-concepts/adaptive-ids#content-area) Beads uses adaptive hash ID lengths that automatically scale based on database size, optimizing for readability in small databases while preventing collisions as databases grow. [​](https://beads.gascity.com/core-concepts/adaptive-ids#motivation) Motivation ---------------------------------------------------------------------------------- * **Small databases** (0-500 issues): Very short, readable IDs like `bd-a3f2` (4 chars) * **Medium databases** (500-1500 issues): Slightly longer IDs like `bd-7f3a8` (5 chars) * **Large databases** (1500+ issues): Standard IDs like `bd-7f3a86` (6 chars) Users who actively archive old issues can keep their IDs shorter over time. [​](https://beads.gascity.com/core-concepts/adaptive-ids#how-it-works) How It Works -------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#birthday-paradox-math) Birthday Paradox Math The collision probability is calculated using: P(collision) ≈ 1 - e^(-n²/2N) Where: * `n` = number of issues in database * `N` = total possible IDs (36^length for lowercase alphanumeric) ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#default-thresholds-25%-max-collision) Default Thresholds (25% max collision) | Database Size | ID Length | Collision Probability | | --- | --- | --- | | 0-500 | 4 chars | ~7% at 500 | | 501-1500 | 5 chars | ~2% at 1500 | | 1501+ | 6 chars | continues scaling | ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#collision-resolution) Collision Resolution If a collision occurs (rare), the algorithm automatically tries: 1. Base length (e.g., 4 chars) 2. Base + 1 (e.g., 5 chars) 3. Base + 2 (e.g., 6 chars) With 10 nonces per length, giving 30 attempts total. [​](https://beads.gascity.com/core-concepts/adaptive-ids#configuration) Configuration ---------------------------------------------------------------------------------------- Adaptive ID length is automatically enabled when using `id_mode=hash`. You can customize the behavior: ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#max-collision-probability) Max Collision Probability Default: 25% (0.25) # More lenient (allow up to 50% collision probability) bd config set max_collision_prob "0.50" # Stricter (only allow 1% collision probability) bd config set max_collision_prob "0.01" ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#minimum-hash-length) Minimum Hash Length Default: 4 chars # Start with 5-char IDs minimum bd config set min_hash_length "5" # Very short IDs (use with caution) bd config set min_hash_length "3" ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#maximum-hash-length) Maximum Hash Length Default: 8 chars # Allow even longer IDs for huge databases bd config set max_hash_length "10" [​](https://beads.gascity.com/core-concepts/adaptive-ids#examples) Examples ------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#default-configuration) Default Configuration # Initialize with hash IDs bd init --id-mode hash --prefix myproject # First 500 issues get 4-char IDs bd create "Fix bug" -p 1 # → myproject-a3f2 # After 1000 issues, switches to 5-char IDs bd create "Add feature" -p 1 # → myproject-7f3a8c # At 10,000 issues, uses 6-char IDs bd create "Refactor" -p 1 # → myproject-b9d1e4 ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#custom-configuration) Custom Configuration # Very strict collision tolerance bd config set max_collision_prob "0.01" # With 1% threshold and 100 issues, uses 4-char IDs # (collision probability is ~0.3% with 4 chars) # Force minimum 5-char IDs for consistency bd config set min_hash_length "5" # All IDs will be at least 5 chars now bd create "Task" -p 1 # → myproject-7f3a8 [​](https://beads.gascity.com/core-concepts/adaptive-ids#collision-probability-table) Collision Probability Table -------------------------------------------------------------------------------------------------------------------- Use `scripts/collision-calculator.go` to explore collision probabilities: go run scripts/collision-calculator.go Output shows: * Collision probabilities for different database sizes and ID lengths * Recommended ID lengths for different thresholds * Expected number of collisions * Adaptive scaling strategy [​](https://beads.gascity.com/core-concepts/adaptive-ids#implementation-details) Implementation Details ---------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#location) Location * Algorithm: `internal/storage/dolt/adaptive_length.go` * ID generation: `internal/storage/dolt/dolt.go` (`generateHashID`) * Tests: `internal/storage/dolt/adaptive_length_test.go` * E2E tests: `internal/storage/dolt/adaptive_e2e_test.go` ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#database-schema) Database Schema Configuration is stored in the `config` table: INSERT INTO config (key, value) VALUES ('max_collision_prob', '0.25'); INSERT INTO config (key, value) VALUES ('min_hash_length', '4'); INSERT INTO config (key, value) VALUES ('max_hash_length', '8'); ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#performance) Performance * Collision probability calculation: ~10ns per call * ID generation with adaptive length: ~300ns (same as before) * Database query to count issues: ~100μs [​](https://beads.gascity.com/core-concepts/adaptive-ids#migration) Migration -------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#existing-databases) Existing Databases Existing databases with 6-char IDs will: 1. Continue using 6-char IDs by default 2. Can opt into adaptive mode by setting config (new IDs will use adaptive length) 3. Old IDs remain unchanged ### [​](https://beads.gascity.com/core-concepts/adaptive-ids#sequential-to-hash-migration) Sequential to Hash Migration When migrating from sequential IDs to hash IDs with `bd migrate --to-hash-ids`: * Uses adaptive length algorithm for new IDs * Preserves existing sequential IDs * References are automatically updated [​](https://beads.gascity.com/core-concepts/adaptive-ids#best-practices) Best Practices ------------------------------------------------------------------------------------------ 1. **Default is good**: The 25% threshold works well for most use cases 2. **Active archival**: Delete closed issues to keep database small and IDs short 3. **Consistency**: Set `min_hash_length` if you want all IDs to be same length 4. **Monitoring**: Run collision calculator periodically to check health [​](https://beads.gascity.com/core-concepts/adaptive-ids#future-enhancements) Future Enhancements ---------------------------------------------------------------------------------------------------- Potential improvements (not yet implemented): * **Automatic scaling notifications**: Warn when approaching threshold * **Per-workspace thresholds**: Different configs for different projects * **Dynamic adjustment**: Auto-adjust threshold based on observed collision rate * **Compaction-aware**: Don’t count compacted issues in collision calculation [​](https://beads.gascity.com/core-concepts/adaptive-ids#alternative-sequential-counter-ids) Alternative: Sequential Counter IDs ----------------------------------------------------------------------------------------------------------------------------------- Adaptive hash IDs are the default, but beads also supports sequential integer IDs (`bd-1`, `bd-2`, …) for projects that prefer human-readable numbering. Counter mode is controlled by the `issue_id_mode` config key: # Switch to sequential IDs bd config set issue_id_mode counter # Revert to hash IDs (default) bd config set issue_id_mode hash **Tradeoff:** * **Hash IDs** (this document): Collision-free across parallel branches and agents; IDs are less predictable but always unique. * **Counter IDs**: Human-friendly and sequential; require care in multi-branch workflows where counters can diverge. See [Configuration](https://beads.gascity.com/reference/configuration) for full documentation on `issue_id_mode=counter`, including migration guidance and per-prefix counter isolation. [​](https://beads.gascity.com/core-concepts/adaptive-ids#related) Related ---------------------------------------------------------------------------- * [Migration Guide](https://github.com/gastownhall/beads/blob/main/README.md#migration) - Converting from sequential to hash IDs * [Configuration](https://beads.gascity.com/reference/configuration) - All configuration options [Hash-based IDs](https://beads.gascity.com/core-concepts/hash-ids) [Graph Links in Beads](https://beads.gascity.com/core-concepts/graph-links) ⌘I --- # Advanced Features - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference/advanced#content-area) Advanced beads functionality. [​](https://beads.gascity.com/reference/advanced#issue-rename) Issue Rename ------------------------------------------------------------------------------ Rename issues while preserving references: bd rename bd-42 bd-new-id bd rename bd-42 bd-new-id --dry-run # Preview Updates: * All dependencies pointing to old ID * All references in other issues * Comments and descriptions [​](https://beads.gascity.com/reference/advanced#prefix-rename) Prefix Rename -------------------------------------------------------------------------------- Change the issue prefix for every issue in the database — for example, shortening `knowledge-work-` to `kw-`: bd rename-prefix kw- --dry-run # Preview without applying bd rename-prefix kw- # Every knowledge-work-* ID becomes kw-* The rename updates all issue IDs and all text references across all fields. Prefixes are lowercase letters, numbers, and hyphens, must start with a letter, and must end with a hyphen. If a corrupted database contains issues with multiple prefixes, `bd rename-prefix <prefix> --repair` consolidates them. See [bd rename-prefix](https://beads.gascity.com/cli-reference/rename-prefix) . [​](https://beads.gascity.com/reference/advanced#duplicate-detection-and-merge) Duplicate Detection and Merge ---------------------------------------------------------------------------------------------------------------- Find issues with identical content (title, description, design, acceptance criteria) and consolidate them: bd duplicates # Report duplicate groups with suggested actions bd duplicates --dry-run # Preview what --auto-merge would do bd duplicates --auto-merge # Merge every duplicate group Issues are grouped by content hash, and only when their statuses match (open with open, closed with closed). The merge target is the most-referenced issue in each group, falling back to the smallest ID. For each group, `--auto-merge`: * Re-parents children of the duplicates onto the target * Closes the duplicates with reason `Duplicate of <target>` * Links each duplicate to the target with a `related` dependency To mark a single known duplicate manually: bd duplicate bd-42 --of bd-41 # Close bd-42 as a duplicate of bd-41 Closing is permanent, but Dolt version history preserves the original state. Verify results with `bd show bd-41` and `bd dep tree bd-41`. [​](https://beads.gascity.com/reference/advanced#database-compaction) Database Compaction -------------------------------------------------------------------------------------------- Reduce database size by compacting old issues: # View compaction statistics bd admin compact --stats # Preview candidates (30+ days closed) bd admin compact --analyze --json # Apply agent-generated summary bd admin compact --apply --id bd-42 --summary summary.txt # Immediate deletion (CAUTION!) bd admin cleanup --force **When to compact:** * Database > 10MB with old closed issues * After major milestones * Before archiving project phase [​](https://beads.gascity.com/reference/advanced#restore-from-history) Restore from History ---------------------------------------------------------------------------------------------- Recover the pre-compaction content of a compacted issue: bd restore bd-42 # Display the archived original content bd restore bd-42 --apply # Write the original content back into the issue If no archived snapshot exists, `bd restore` falls back to a best-effort reconstruction from Dolt version history, which can only be displayed, not applied. [​](https://beads.gascity.com/reference/advanced#database-inspection) Database Inspection -------------------------------------------------------------------------------------------- `bd sql` requires Dolt server mode (`bd dolt start`, see Performance Tuning below); it is not available against the default embedded-mode database. # Schema info bd info --schema --json # Raw database query (server mode only) bd sql "SELECT * FROM issues LIMIT 5" [​](https://beads.gascity.com/reference/advanced#database-redirects) Database Redirects ------------------------------------------------------------------------------------------ Multiple git clones can share one beads database — useful when several agents or checkout directories work the same issues. Create a `.beads/redirect` file in the secondary clone containing a single path (relative or absolute) to the target `.beads` directory: # In the secondary clone mkdir -p .beads echo "../main-clone/.beads" > .beads/redirect Check which database is actually in use: bd where # Active .beads location, including redirect info bd where --json Limitations and guidance: * Redirect chains are not followed — only a single level works, so a redirect must point directly at the real `.beads` directory. * The target directory must exist and contain a valid database. * Give separate projects and long-lived forks their own databases instead of redirects. * Git worktrees don’t need redirects — linked worktrees discover the repository’s `.beads` workspace automatically. See [Git Worktrees](https://beads.gascity.com/reference/worktrees) . [​](https://beads.gascity.com/reference/advanced#extensible-database) Extensible Database -------------------------------------------------------------------------------------------- For Dolt-backed projects, keep extension state outside the beads database and connect it to beads through stable CLI surfaces: # Query issues for integration workflows bd list --json bd query "status=open AND priority<=2" --json # Run direct SQL for inspection (server mode only) bd sql "SELECT id, title, status FROM issues LIMIT 5" Custom tables through direct storage access are a legacy SQLite-only pattern. See the [bd-example-extension-go example](https://github.com/gastownhall/beads/blob/main/examples/bd-example-extension-go/README.md) only if you are maintaining a SQLite-backed extension. [​](https://beads.gascity.com/reference/advanced#audit-data) Audit Data -------------------------------------------------------------------------- Beads records issue lifecycle events in the database for audit and recovery workflows. There is no standalone `bd events` command; inspect current issue state through JSON output, or query the audit tables directly when needed: # Current issue state bd show bd-a1b2 --json # Recent stored events for one issue (server mode only) bd sql "SELECT event_type, actor, created_at FROM events WHERE issue_id = 'bd-a1b2' ORDER BY created_at DESC LIMIT 20" Events: * `issue.created` * `issue.updated` * `issue.closed` * `dependency.added` * `sync.completed` [​](https://beads.gascity.com/reference/advanced#batch-operations) Batch Operations -------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/advanced#create-multiple) Create Multiple Bootstrap a new database from a JSONL export: # In the source project bd export -o issues.jsonl # In the new project: place the export at .beads/issues.jsonl # (or the configured import.path), then initialize from it bd init --from-jsonl Importing records whose IDs already exist updates those issues in place — hash IDs are content-derived and stable, so a matching ID is an update, not a collision. ### [​](https://beads.gascity.com/reference/advanced#update-multiple) Update Multiple bd list --status open --priority 4 --json | \ jq -r '.[].id' | \ xargs -I {} bd update {} --priority 3 ### [​](https://beads.gascity.com/reference/advanced#close-multiple) Close Multiple bd list --label "sprint-1" --status open --json | \ jq -r '.[].id' | \ xargs -I {} bd close {} --reason "Sprint complete" [​](https://beads.gascity.com/reference/advanced#integration-access) Integration Access ------------------------------------------------------------------------------------------ Use the CLI as the supported integration boundary: # Machine-readable issue data bd show bd-a1b2 --json # Ready-work queue for automation bd ready --json # Direct SQL inspection against the active Dolt database (server mode only) bd sql "SELECT id, priority, status FROM issues WHERE status != 'closed'" The storage packages under `internal/` are not a public Go API. The [MCP server](https://beads.gascity.com/integrations/mcp-server) is a stateless adapter over the same boundary: it translates MCP calls into `bd` CLI invocations and routes each call to the correct `.beads` workspace based on the working directory. It never caches or stores issue data itself. [​](https://beads.gascity.com/reference/advanced#performance-tuning) Performance Tuning ------------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/reference/advanced#large-databases) Large Databases # Summarize old closed issues (see Database Compaction above) bd admin compact --stats # Reclaim disk space with Dolt garbage collection bd admin compact --dolt # Squash Dolt commits older than 30 days (preview first) bd compact --dry-run bd compact --force ### [​](https://beads.gascity.com/reference/advanced#many-concurrent-agents) Many Concurrent Agents Beads uses Dolt server mode to handle concurrent access from multiple agents. The server manages transaction isolation automatically. # Start the Dolt server bd dolt start # Check server health bd doctor ### [​](https://beads.gascity.com/reference/advanced#ci/cd-optimization) CI/CD Optimization In CI/CD environments, beads uses embedded mode by default (no server required): # Just run commands directly — no special flags needed bd list [Protected Branches](https://beads.gascity.com/reference/protected-branches) [JSON Output Schema Contract](https://beads.gascity.com/reference/json-schema) ⌘I --- # Git Integration - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference/git-integration#content-area) How beads integrates with git. [​](https://beads.gascity.com/reference/git-integration#overview) Overview ----------------------------------------------------------------------------- Beads uses git for: * **Project hosting** - Your code repository also hosts beads configuration * **Hooks** - Auto-sync on git operations Data storage and sync are handled by Dolt (a version-controlled SQL database) — see [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts) for how issue data moves between machines. [​](https://beads.gascity.com/reference/git-integration#file-structure) File Structure ----------------------------------------------------------------------------------------- .beads/ ├── config.yaml # Project config (git-tracked) ├── metadata.json # Backend metadata (git-tracked) ├── .gitignore # Written by bd init (git-tracked) ├── embeddeddolt/ # Dolt database — embedded mode, the default (gitignored) └── dolt/ # Dolt database — server mode (gitignored) `bd init` writes `.beads/.gitignore` to keep the database directory and runtime files out of git — no manual gitignore rules are needed. Never track the database directory (`.beads/embeddeddolt/` or `.beads/dolt/`) in git or via Git LFS. [​](https://beads.gascity.com/reference/git-integration#git-hooks) Git Hooks ------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/git-integration#installation) Installation `bd init` installs hooks by default (skip with `bd init --skip-hooks`). To install or refresh them manually: bd hooks install Installed hooks are thin shims that call `bd hooks run <hook-name>`, so upgrading `bd` automatically updates hook behavior: | Hook | What it does | | --- | --- | | `pre-commit` | Runs chained hooks; when `export.auto` is enabled, exports `.beads/issues.jsonl` so it lands in the same commit | | `post-merge` | Runs chained hooks; imports JSONL only as a legacy fallback when no Dolt remote is configured — with `sync.remote` set, `bd dolt pull` is the canonical sync | | `pre-push` | Runs chained hooks before push | | `post-checkout` | Runs chained hooks after branch checkout | | `prepare-commit-msg` | Adds an `Executed-By:` agent identity trailer when an agent (`BD_ACTOR`) makes the commit | The shims use section markers to coexist with existing hooks — content outside the markers is preserved across installs and upgrades. Install variants: bd hooks install --beads # Install to .beads/hooks/ (recommended for the Dolt backend) bd hooks install --shared # Install to .beads-hooks/ (versioned, shareable with the team) bd hooks install --chain # Run existing hooks before bd hooks Hook installation is worktree-aware: `bd` resolves the shared git directory, so installing from a linked worktree works. ### [​](https://beads.gascity.com/reference/git-integration#status) Status bd hooks list ### [​](https://beads.gascity.com/reference/git-integration#uninstall) Uninstall bd hooks uninstall ### [​](https://beads.gascity.com/reference/git-integration#external-hook-managers) External Hook Managers bd detects these external git hook managers and checks whether their config calls `bd hooks run`: * [lefthook](https://lefthook.dev/) — YAML/TOML/JSON config * [husky](https://typicode.github.io/husky/) — `.husky/` directory scripts * [pre-commit](https://pre-commit.com/) — `.pre-commit-config.yaml` * [prek](https://prek.j178.dev/) — Rust-based pre-commit alternative (same config) * [hk](https://hk.jdx.dev/) — fast hook manager using Pkl config * [overcommit](https://github.com/sds/overcommit) — Ruby-based (detection only) * yorkie — detection only * [simple-git-hooks](https://github.com/toplenboren/simple-git-hooks) — lightweight JS (detection only) `bd doctor` reports whether a detected manager is integrated with bd, and `bd doctor --fix` reinstalls the hooks with `--chain` so the manager’s existing hooks keep running. For config-driven managers, add bd steps directly. Example `hk.pkl`: hooks { ["pre-commit"] { steps { ["bd-pre-commit"] { check = "bd hooks run pre-commit" } } } ["post-merge"] { steps { ["bd-post-merge"] { check = "bd hooks run post-merge" } } } ["pre-push"] { steps { ["bd-pre-push"] { check = "bd hooks run pre-push \"$@\"" } } } } ### [​](https://beads.gascity.com/reference/git-integration#hook-timeout) Hook Timeout The hook shim wraps `bd hooks run` with an OS-level `timeout` so hooks cannot hang git operations indefinitely. The default is **300 seconds** (5 minutes), which accommodates chained pre-commit pipelines (eslint, prettier, TypeScript compilation). Override it with the `BEADS_HOOK_TIMEOUT` environment variable: # Set a longer timeout (in seconds) export BEADS_HOOK_TIMEOUT=600 # 10 minutes # Or set it per-invocation BEADS_HOOK_TIMEOUT=600 git commit -m "..." When the timeout is reached, beads prints a warning and lets the git operation proceed — the commit or push is not blocked. [​](https://beads.gascity.com/reference/git-integration#conflict-resolution) Conflict Resolution --------------------------------------------------------------------------------------------------- Dolt handles merge conflicts at the database level using its built-in merge capabilities. When conflicts arise during sync, Dolt identifies conflicting rows and allows resolution through SQL. # Check for and fix conflicts bd doctor --fix [​](https://beads.gascity.com/reference/git-integration#protected-branches) Protected Branches ------------------------------------------------------------------------------------------------- Dolt stores data under `refs/dolt/data`, separate from Git refs. This means beads data does not conflict with protected Git branches, and no separate `beads-sync` branch or protected-branch exception is needed. On new projects with a Git `origin`, `bd init` configures that origin as the Dolt remote automatically. See [Protected Branches](https://beads.gascity.com/reference/protected-branches) for the full workflow, including legacy `beads-sync` cleanup. [​](https://beads.gascity.com/reference/git-integration#git-worktrees) Git Worktrees --------------------------------------------------------------------------------------- Beads works in Git worktrees without extra setup. Linked worktrees discover the repository’s `.beads` workspace and sync issue data through Dolt: # In a linked worktree bd create "Task" bd list bd dolt pull bd dolt push All worktrees share the repository’s `.beads` workspace: discovery follows `BEADS_DIR` if set, then the main repository’s `.beads`, preventing database duplication across worktrees. Use `bd where` as the authoritative check for which workspace is active — a local `./.beads` may legitimately be absent in a worktree. Embedded mode (the default) serves one writer at a time; for concurrent writers across worktrees, use server mode. See [Git Worktrees](https://beads.gascity.com/reference/worktrees) for the full guide. Older beads versions documented a `sync.branch` workflow that created hidden Git worktrees. That workflow has been removed; current sync uses Dolt remotes. [​](https://beads.gascity.com/reference/git-integration#branch-workflows) Branch Workflows --------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/git-integration#feature-branch) Feature Branch git checkout -b feature-x bd create "Feature X" -t feature # Work... bd dolt push git push ### [​](https://beads.gascity.com/reference/git-integration#fork-workflow) Fork Workflow # In fork bd init --contributor # Interactive wizard # Work in separate planning repo... bd dolt push The contributor wizard keeps issue data in a separate planning repository, leaving the upstream repo without any `.beads/`. Best for open source contributors, solo developers, and private task tracking on public repos. `bd init` auto-detects forks and offers to configure `.git/info/exclude` (`--setup-exclude`) so beads files stay local. Set the role without prompting via `--role contributor` or `--role maintainer` (the default in non-interactive mode). ### [​](https://beads.gascity.com/reference/git-integration#team-workflow) Team Workflow bd init --team # All team members share the Dolt database bd dolt pull # Pull latest changes from Dolt remote bd dolt push # Push your changes to Dolt remote Best for teams on protected branches and review-before-merge policies. See [Multi-Repo Migration](https://beads.gascity.com/multi-agent/multi-repo-migration) for multi-repo patterns. ### [​](https://beads.gascity.com/reference/git-integration#duplicate-detection) Duplicate Detection After merging branches: bd duplicates --auto-merge [​](https://beads.gascity.com/reference/git-integration#branchless-workflows-jujutsu-/-jj) Branchless Workflows (Jujutsu / jj) --------------------------------------------------------------------------------------------------------------------------------- Beads works with branchless VCS tools like [Jujutsu (jj)](https://martinvonz.github.io/jj/) . Since beads data is stored in Dolt (not git branches), there is no dependency on the “current branch” concept. ### [​](https://beads.gascity.com/reference/git-integration#what-works-without-hooks) What Works Without Hooks All core beads functionality works without git hooks: | Feature | Hooks Required? | Notes | | --- | --- | --- | | `bd create`, `bd update`, `bd close` | No | Core CRUD uses Dolt directly | | `bd ready`, `bd list`, `bd show` | No | Read-only queries | | `bd dolt push` / `bd dolt pull` | No | Dolt-native sync, independent of git | | `bd onboard`, `bd doctor` | No | Diagnostics and onboarding | | Agent identity trailers | Yes | `prepare-commit-msg` hook adds `Executed-By:` to commits | | Hook chaining | Yes | Preserves existing pre-commit, post-merge hooks | To skip hooks entirely during init: bd init --skip-hooks ### [​](https://beads.gascity.com/reference/git-integration#what-works-without-agents-md) What Works Without AGENTS.md The AGENTS.md file generated by `bd init` provides AI agent instructions. If you manage your own agent instructions or don’t want beads to modify tracked files: bd init --skip-agents # Skip AGENTS.md and Claude/Codex setup generation bd init --stealth # Full invisible mode (also skips hooks + agents) ### [​](https://beads.gascity.com/reference/git-integration#jujutsu-setup) Jujutsu Setup **Colocated repos** (`jj git init --colocate`): Git hooks work normally. Beads installs simplified hooks (`pre-commit` and `post-merge` only, no staging logic). **Pure jj repos** (no git): Since jj doesn’t have native hooks yet, set up push aliases: # ~/.config/jj/config.toml [aliases] push = ["util", "exec", "--", "sh", "-c", "bd dolt commit && bd dolt push && jj git push \"$@\"", ""] Then use `jj push` instead of `jj git push`. [​](https://beads.gascity.com/reference/git-integration#best-practices) Best Practices ----------------------------------------------------------------------------------------- 1. **Install hooks** - `bd hooks install` 2. **Push regularly** - `bd dolt push` at session end 3. **Pull before work** - `bd dolt pull` to get latest issues 4. **Use normal Git worktrees** - no sync branch is required [Configuration](https://beads.gascity.com/reference/configuration) [Git Worktrees Guide](https://beads.gascity.com/reference/worktrees) ⌘I --- # Federation Setup Guide - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/multi-agent/federation#content-area) Federation enables peer-to-peer synchronization of beads databases between multiple workspaces using Dolt remotes. Each workspace maintains its own database while sharing work items with configured peers. [​](https://beads.gascity.com/multi-agent/federation#overview) Overview -------------------------------------------------------------------------- Federation uses Dolt’s distributed version control capabilities to sync issue data between independent teams or locations. Key benefits: * **Peer-to-peer**: No central server required; each town is autonomous * **Database-native versioning**: Built on Dolt’s version control, not file exports * **Flexible infrastructure**: Works with DoltHub, S3, GCS, local paths, or SSH * **Data sovereignty**: Configurable tiers for compliance (GDPR, regional laws) [​](https://beads.gascity.com/multi-agent/federation#prerequisites) Prerequisites ------------------------------------------------------------------------------------ 1. **Dolt backend**: Federation requires the Dolt storage backend (the only supported backend) [​](https://beads.gascity.com/multi-agent/federation#configuration) Configuration ------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/multi-agent/federation#enable-federation-compatible-sync) Enable Federation-Compatible Sync Edit `.beads/config.yaml` or `~/.config/bd/config.yaml`: federation: remote: dolthub://myorg/beads # Primary remote (optional) sovereignty: T2 # Data sovereignty tier Or via environment variables: export BD_FEDERATION_REMOTE="dolthub://myorg/beads" export BD_FEDERATION_SOVEREIGNTY="T2" ### [​](https://beads.gascity.com/multi-agent/federation#data-sovereignty-tiers) Data Sovereignty Tiers | Tier | Description | Use Case | | --- | --- | --- | | T1 | No restrictions | Public data | | T2 | Organization-level | Regional/company compliance | | T3 | Pseudonymous | Identifiers removed | | T4 | Anonymous | Maximum privacy | [​](https://beads.gascity.com/multi-agent/federation#adding-federation-peers) Adding Federation Peers -------------------------------------------------------------------------------------------------------- Use `bd federation add-peer` to register remote peers: bd federation add-peer <name> <endpoint> ### [​](https://beads.gascity.com/multi-agent/federation#peer-name-rules) Peer Name Rules * Must start with a letter * Alphanumeric, dash, and underscore only * Maximum 64 characters ### [​](https://beads.gascity.com/multi-agent/federation#supported-endpoint-formats) Supported Endpoint Formats | Format | Example | Description | | --- | --- | --- | | DoltHub | `dolthub://org/repo` | DoltHub hosted repository | | Google Cloud | `gs://bucket/path` | Google Cloud Storage | | Amazon S3 | `s3://bucket/path` | Amazon S3 | | Local | `file:///path/to/backup` | Local filesystem | | HTTPS | `https://host/path` | HTTPS remote | | SSH | `ssh://host/path` | SSH remote | | Git SSH | `git@host:path` | Git SSH shorthand | ### [​](https://beads.gascity.com/multi-agent/federation#examples) Examples # Add a staging environment on DoltHub bd federation add-peer staging dolthub://myorg/staging-beads # Add a cloud backup bd federation add-peer backup gs://mybucket/beads-backup bd federation add-peer backup-s3 s3://mybucket/beads-backup # Add a local backup bd federation add-peer local file:///home/user/beads-backup # Add a partner organization bd federation add-peer partner-town dolthub://partner-org/beads ### [​](https://beads.gascity.com/multi-agent/federation#credentials) Credentials Peers configured with `--user` (and optionally `--password`, otherwise prompted interactively) store SQL credentials AES-256 encrypted, locally. Stored credentials are used automatically during sync: bd federation add-peer town-gamma 192.168.1.100:3306/beads --user sync-bot ### [​](https://beads.gascity.com/multi-agent/federation#json-output) JSON Output For scripting, use the `--json` flag: bd --json federation add-peer staging dolthub://myorg/staging-beads # {"added":"staging","url":"dolthub://myorg/staging-beads","has_auth":false,"sovereignty":""} ### [​](https://beads.gascity.com/multi-agent/federation#verify-configuration) Verify Configuration List configured peers: bd federation list-peers [​](https://beads.gascity.com/multi-agent/federation#syncing-with-peers) Syncing with Peers ---------------------------------------------------------------------------------------------- Use `bd federation sync` to pull from and push to peer towns, and `bd federation status` to check sync state without transferring data. # Sync with all peers bd federation sync # Sync with a specific peer bd federation sync --peer town-beta # Handle conflicts bd federation sync --strategy theirs # or 'ours' # Check status (ahead/behind, reachability, conflicts) bd federation status bd federation status --peer town-beta Without `--strategy`, a sync that hits merge conflicts pauses and reports the conflicting tables for manual resolution instead of auto-resolving. ### [​](https://beads.gascity.com/multi-agent/federation#topologies) Topologies | Pattern | Description | Use Case | | --- | --- | --- | | Hub-spoke | Central hub, satellites sync to hub | Team with central coordination | | Mesh | All peers sync with each other | Decentralized collaboration | | Hierarchical | Tree of hubs | Multi-team organizations | [​](https://beads.gascity.com/multi-agent/federation#architecture-notes) Architecture Notes ---------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/federation#how-it-works) How It Works 1. Each workspace has its own Dolt database 2. `add-peer` registers a Dolt remote (similar to `git remote add`) 3. `bd federation sync` pushes and pulls commits between peers 4. Conflict resolution follows the configured strategy When run against a Dolt SQL server, federation uses two ports: MySQL (3306) for multi-writer SQL access, and remotesapi (8080) for peer-to-peer push/pull: ┌─────────────────┐ ┌─────────────────┐ │ Workspace A │◄───────►│ Workspace B │ │ dolt sql-server│ sync │ dolt sql-server│ │ :3306 (sql) │ │ :3306 (sql) │ │ :8080 (remote) │ │ :8080 (remote) │ └─────────────────┘ └─────────────────┘ ### [​](https://beads.gascity.com/multi-agent/federation#multi-repo-support) Multi-Repo Support Issues track their `SourceSystem` to identify which federated system created them. This enables proper attribution and trust chains across organizations. ### [​](https://beads.gascity.com/multi-agent/federation#connectivity) Connectivity Remote connectivity is validated on first push/pull operation, not when adding the peer. This allows configuring remotes before infrastructure is ready. ### [​](https://beads.gascity.com/multi-agent/federation#leases-are-per-replica) Leases are per-replica A claim lease (`bd ready --claim` + `bd heartbeat`, reaped by `bd reclaim`) is only meaningful on the replica that granted it. The `leases` table is clone-local and never replicates; what crosses the bridge is the claim’s _visibility_ — `status`/`assignee` on the issue row — and that is stale on every other replica by up to one sync interval. Two rules follow, and a federated deployment owes both: 1. **Grace window > sync interval, and lease TTL > sync interval.** A TTL or `bd reclaim --older-than` grace shorter than the cadence at which replicas exchange state is meaningless across the bridge: the remote view is a full interval old by construction, so a reaper over there would be judging liveness from data older than the lease itself. `bd reclaim` defaults its grace to 2× the lease TTL; raise the TTL (or the grace) above your sync interval, never shrink the interval to fit them. 2. **Reclaim belongs to the granting replica.** Each lease records the replica that granted it, and `bd reclaim` skips a lease granted elsewhere, naming it on stderr. Reap dead workers on the machine that hired them. The guard is **opt-in**: it arms only where you name this replica. export BEADS_NODE_ID=mini # per-machine; or `bd config set node_id mini` Two rules about what to name, both load-bearing: * **`node_id` names the STORE, not the host.** One value per beads _database_. Hosts that are clients of the _same_ dolt sql-server (`BEADS_DOLT_SERVER_HOST`, a systemd/Docker server, Hosted Dolt, a VPS) are **one replica** no matter how many machines they are — give them all the same value, or leave it unset. Give them distinct ids and you rebuild the very fail-closed regression described below: a supervisor would match no worker’s lease and reclaim 0 forever. Name a replica only where there is a real sync interval between it and the others. * **`node_id` is per-machine, so it must never be committed.** The project `.beads/config.yaml` is a git-**tracked** file. A `node_id` committed there propagates one machine’s identity to every clone that pulls it, and then every comparison matches: the guard is fully _armed_ and fully _inert_, and `laptop` reaps `mini`’s leases exactly as if they were local — the precise hazard this feature exists to close, now happening while you believe you are protected. That is worse than not setting it at all. `bd config set node_id` therefore writes the **user-global** `~/.config/bd/config.yaml`, alongside the other per-machine state (`sync-state.json`, `push-state.json`, `redirect`). Use the env var or that command; never hand-add `node_id` to `.beads/config.yaml`. There is deliberately no hostname fallback. The hostname answers the wrong question — it names the client _process’s_ machine, not the store — and guessing gets it wrong in the topologies that most need automated reclaim: with a shared or remote dolt sql-server (`BEADS_DOLT_SERVER_HOST`, Hosted Dolt, a VPS) many hosts are clients of ONE store with no sync interval between them, so a per-hostname identity would stop a supervisor reaping any worker’s lease at all; in a container the hostname is a per-run container ID; on macOS the transient hostname follows the network. Each of those would strand work on a deployment with no federation at all — a worse failure than the one this guard prevents. So an unset identity degrades to the old behavior (every lease treated as local) rather than failing closed: an upgrade, and any single-store deployment, can never strand a lease the reaper could previously recover. Leases granted before this feature landed likewise carry no replica and stay reclaimable until a heartbeat re-stamps them with a configured node. `bd reclaim --any-replica` disarms the guard. It is for a replica that is permanently gone (or a node that was renamed and now sees its own old leases as foreign) — not a normal setting, since only the granting machine has a first-hand view of whether the holder is alive. [​](https://beads.gascity.com/multi-agent/federation#planned-features) Planned Features ------------------------------------------------------------------------------------------ The following operation has infrastructure support but is not yet exposed as a command: * `bd federation push <peer>` / `bd federation pull <peer>` - single-direction sync with one peer. `bd federation sync` already covers the bidirectional case. [​](https://beads.gascity.com/multi-agent/federation#troubleshooting) Troubleshooting ---------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/federation#%E2%80%9Drequires-direct-database-access%E2%80%9D) ”requires direct database access” Federation commands require the Dolt backend with direct database access. Ensure you have the Dolt backend configured for federation operations. ### [​](https://beads.gascity.com/multi-agent/federation#%E2%80%9Dpeer-already-exists%E2%80%9D) ”peer already exists” A peer with that name is already configured. Use a different name or check existing peers with `bd federation list-peers`. ### [​](https://beads.gascity.com/multi-agent/federation#invalid-endpoint-format) Invalid endpoint format Ensure your endpoint matches one of the supported formats above. The scheme must be one of: `dolthub://`, `gs://`, `s3://`, `file://`, `https://`, `ssh://`, or git SSH format (`git@host:path`). ### [​](https://beads.gascity.com/multi-agent/federation#general-health-check) General health check bd doctor --deep [​](https://beads.gascity.com/multi-agent/federation#reference) Reference ---------------------------------------------------------------------------- * Configuration: See [Configuration](https://beads.gascity.com/reference/configuration) for all federation settings * Source: `cmd/bd/federation.go` * Storage interfaces: `internal/storage/versioned.go` * Dolt implementation: `internal/storage/dolt/store.go` [Agent Coordination](https://beads.gascity.com/multi-agent/coordination) [Multi-Repo Migration Guide](https://beads.gascity.com/multi-agent/multi-repo-migration) ⌘I --- # Graph Links in Beads - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/core-concepts/graph-links#content-area) Beads supports several types of links between issues to create a knowledge graph. These links enable rich querying and traversal beyond simple blocking dependencies. [​](https://beads.gascity.com/core-concepts/graph-links#link-types) Link Types --------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/graph-links#replies-to-conversation-threading) replies-to - Conversation Threading Creates message threads, similar to email or chat conversations. **Created by:** * Orchestrator mail reply commands (orchestrator handles messaging) * `bd dep add <new-id> <original-id> --type replies-to` (manual linking) **Use cases:** * Agent-to-agent message threads * Discussion chains on issues * Follow-up communications **Example:** # Original message (via orchestrator mail) # orchestrator mail send worker/ -s "Review needed" -m "Please review issue-xyz" # Creates: msg-a1b2 # Reply (automatically sets replies-to) # orchestrator mail reply msg-a1b2 -m "Done! Approved with minor comments." # Creates: msg-c3d4 with replies-to: msg-a1b2 **Viewing threads:** bd show gt-a1b2 --thread ### [​](https://beads.gascity.com/core-concepts/graph-links#relates-to-loose-associations) relates-to - Loose Associations Bidirectional “see also” links between related issues. Not blocking, not hierarchical - just related. **Created by:** * `bd dep relate <id1> <id2>` - Links both issues to each other **Removed by:** * `bd dep unrelate <id1> <id2>` - Removes link in both directions **Use cases:** * Cross-referencing related features * Linking bugs to associated tasks * Building knowledge graphs * “See also” connections **Example:** # Link two related issues bd dep relate bd-auth bd-security # Result: bd-auth.relates-to includes bd-security # bd-security.relates-to includes bd-auth # View related issues bd show bd-auth # Shows: Related: bd-security # Remove the link bd dep unrelate bd-auth bd-security **Multiple links:** An issue can have multiple relates-to links: bd dep relate bd-api bd-auth bd dep relate bd-api bd-docs bd dep relate bd-api bd-tests # bd-api now relates to 3 issues ### [​](https://beads.gascity.com/core-concepts/graph-links#duplicates-deduplication) duplicates - Deduplication Marks an issue as a duplicate of a canonical issue. The duplicate is automatically closed. **Created by:** * `bd duplicate <id> --of <canonical>` **Use cases:** * Consolidating duplicate bug reports * Merging similar feature requests * Database deduplication at scale **Example:** # Two similar bug reports exist bd show bd-bug1 # "Login fails on Safari" bd show bd-bug2 # "Safari login broken" # Mark bug2 as duplicate of bug1 bd duplicate bd-bug2 --of bd-bug1 # Result: bd-bug2 is closed with duplicate_of: bd-bug1 # View shows the relationship bd show bd-bug2 # Status: closed # Duplicate of: bd-bug1 **Behavior:** * Duplicate issue is automatically closed * Original (canonical) issue remains open * `duplicate_of` field stores the canonical ID ### [​](https://beads.gascity.com/core-concepts/graph-links#supersedes-version-chains) supersedes - Version Chains Marks an issue as superseded by a newer version. The old issue is automatically closed. **Created by:** * `bd supersede <old-id> --with <new-id>` **Use cases:** * Design document versions * Spec evolution * Artifact versioning * RFC chains **Example:** # Original design doc bd create --title "Design Doc v1" --type task # Creates: bd-doc1 # Later, create updated version bd create --title "Design Doc v2" --type task # Creates: bd-doc2 # Mark v1 as superseded bd supersede bd-doc1 --with bd-doc2 # Result: bd-doc1 closed with superseded_by: bd-doc2 # View shows the chain bd show bd-doc1 # Status: closed # Superseded by: bd-doc2 **Behavior:** * Old issue is automatically closed * New issue remains in its current state * `superseded_by` field stores the replacement ID [​](https://beads.gascity.com/core-concepts/graph-links#schema-fields) Schema Fields --------------------------------------------------------------------------------------- These fields are added to issues: | Field | Type | Description | | --- | --- | --- | | `replies-to` | string | ID of parent message (threading) | | `relates-to` | \[\]string | IDs of related issues (bidirectional) | | `duplicate_of` | string | ID of canonical issue | | `superseded_by` | string | ID of replacement issue | [​](https://beads.gascity.com/core-concepts/graph-links#querying-links) Querying Links ----------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/graph-links#view-issue-details) View Issue Details bd show <id> Shows all link types for an issue: bd-auth: Implement authentication Status: open Priority: P1 Related to (3): bd-security: Security audit bd-users: User management bd-sessions: Session handling ### [​](https://beads.gascity.com/core-concepts/graph-links#view-threads) View Threads bd show <id> --thread Follows `replies-to` chain to show conversation history. ### [​](https://beads.gascity.com/core-concepts/graph-links#json-output) JSON Output bd show <id> --json Returns all fields including graph links: { "id": "bd-auth", "title": "Implement authentication", "relates-to": ["bd-security", "bd-users", "bd-sessions"], "duplicate_of": "", "superseded_by": "" } [​](https://beads.gascity.com/core-concepts/graph-links#comparison-with-dependencies) Comparison with Dependencies --------------------------------------------------------------------------------------------------------------------- | Link Type | Blocking? | Hierarchical? | Direction | | --- | --- | --- | --- | | `blocks` | Yes | No | One-way | | `parent_id` | No | Yes | One-way | | `relates-to` | No | No | Bidirectional | | `replies-to` | No | No | One-way | | `duplicate_of` | No | No | One-way | | `superseded_by` | No | No | One-way | [​](https://beads.gascity.com/core-concepts/graph-links#use-cases) Use Cases ------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/graph-links#knowledge-base) Knowledge Base Link related documentation: bd dep relate bd-api-ref bd-quickstart bd dep relate bd-api-ref bd-examples bd dep relate bd-quickstart bd-install ### [​](https://beads.gascity.com/core-concepts/graph-links#bug-triage) Bug Triage Consolidate duplicate reports: # Find potential duplicates bd duplicates # Merge duplicates bd duplicate bd-bug42 --of bd-bug17 bd duplicate bd-bug58 --of bd-bug17 ### [​](https://beads.gascity.com/core-concepts/graph-links#version-history) Version History Track document evolution: bd supersede bd-rfc1 --with bd-rfc2 bd supersede bd-rfc2 --with bd-rfc3 # bd-rfc3 is now the current version ### [​](https://beads.gascity.com/core-concepts/graph-links#message-threading) Message Threading Build conversation chains (via orchestrator mail): # orchestrator mail send dev/ -s "Question" -m "How does X work?" # orchestrator mail reply msg-q1 -m "X works by..." # orchestrator mail reply msg-q1.reply -m "Thanks!" [​](https://beads.gascity.com/core-concepts/graph-links#best-practices) Best Practices ----------------------------------------------------------------------------------------- 1. **Use relates-to sparingly** - Too many links become noise 2. **Prefer specific link types** - `duplicates` is clearer than generic relates-to 3. **Keep threads shallow** - Deep reply chains are hard to follow 4. **Document supersedes chains** - Note why version changed 5. **Query before creating duplicates** - `bd search` first [​](https://beads.gascity.com/core-concepts/graph-links#see-also) See Also ----------------------------------------------------------------------------- * [Messaging](https://github.com/gastownhall/beads/blob/main/engdocs/messaging.md) - Mail commands and threading * [Dependencies](https://beads.gascity.com/getting-started/quickstart#add-dependencies) - Blocking dependencies * [CLI Reference](https://beads.gascity.com/cli-reference/index) - All commands [Adaptive ID Length](https://beads.gascity.com/core-concepts/adaptive-ids) [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts) ⌘I --- # Sync Setup Guide - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/getting-started/sync-setup#content-area) Set up beads with Dolt sync so your issues follow you across computers. [​](https://beads.gascity.com/getting-started/sync-setup#prerequisites) Prerequisites ---------------------------------------------------------------------------------------- You need two tools installed on every machine: | Tool | Minimum Version | Install | | --- | --- | --- | | **bd** (beads CLI) | 0.59.0+ | See [Installation](https://beads.gascity.com/getting-started/installation) | | **Dolt** | 2.2.0+ | `brew install dolt` or [dolt install script](https://github.com/dolthub/dolt/releases/latest/download/install.sh) | Verify both are installed: bd version # must be 0.59.0+ dolt version # must be 2.2.0+ [​](https://beads.gascity.com/getting-started/sync-setup#initial-setup-first-computer) Initial Setup (First Computer) ------------------------------------------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/getting-started/sync-setup#1-initialize-beads) 1\. Initialize beads cd your-project bd init This creates the `.beads/` directory with a Dolt database. If the git repo has an `origin` remote, `bd init` also configures a Dolt remote named `origin` pointing at that same git URL. Dolt stores issue data under `refs/dolt/data`, separate from normal source branches. ### [​](https://beads.gascity.com/getting-started/sync-setup#2-create-some-issues) 2\. Create some issues bd create "Set up CI pipeline" -p 1 -t task bd create "Add authentication" -p 2 -t feature bd list ### [​](https://beads.gascity.com/getting-started/sync-setup#3-verify-or-add-a-dolt-remote) 3\. Verify or add a Dolt remote In a normal git repo with `origin`, this should already be configured: bd dolt remote list # Expected: origin <your git origin URL> If the repo had no `origin` during init, point beads at your Git remote for sync: # GitHub (SSH — recommended) bd dolt remote add origin git+ssh://git@github.com/org/repo.git # GitHub (HTTPS) bd dolt remote add origin git+https://github.com/org/repo.git # Other options: DoltHub, S3, GCS, local path # See DOLT.md for all remote types ### [​](https://beads.gascity.com/getting-started/sync-setup#4-push-your-issues) 4\. Push your issues bd dolt push Verify the push worked: git ls-remote origin | grep dolt # Expected: <hash> refs/dolt/data [​](https://beads.gascity.com/getting-started/sync-setup#existing-projects-without-a-dolt-remote) Existing Projects Without a Dolt Remote -------------------------------------------------------------------------------------------------------------------------------------------- Projects initialized by older versions of `bd init` may have a local embedded Dolt database and a committed `.beads/issues.jsonl`, but no Dolt remote. Fix that from the machine whose local database is authoritative: bd dolt remote list bd export -o .beads/issues.pre-remote.jsonl # optional issue audit export bd dolt remote add origin git+ssh://git@github.com/org/repo.git bd dolt push `bd dolt remote add origin ...` writes `sync.remote` to `.beads/config.yaml`. Commit and push that config file with your normal git workflow. Other clones can then run `bd bootstrap` if their database is missing/stale, or `bd dolt pull` when they already have the right database. [​](https://beads.gascity.com/getting-started/sync-setup#cloning-to-a-new-computer) Cloning to a New Computer ---------------------------------------------------------------------------------------------------------------- When you clone a repo that already has beads data on the remote, a standard `git clone` does **not** fetch `refs/dolt/data`. You need to bootstrap the Dolt database. ### [​](https://beads.gascity.com/getting-started/sync-setup#quick-path-bd-bootstrap) Quick path: bd bootstrap On recent versions of bd, `bd bootstrap` handles everything automatically: git clone git@github.com:org/repo.git cd repo bd bootstrap `bd bootstrap` auto-detects `refs/dolt/data` on origin, clones the Dolt database, and configures the remote. Verify with: bd list # should show your issues bd history # should show recent issue history If `bd bootstrap` succeeds, you’re done — skip to [Day-to-day Sync](https://beads.gascity.com/getting-started/sync-setup#day-to-day-sync) . ### [​](https://beads.gascity.com/getting-started/sync-setup#manual-path-if-bootstrap-fails) Manual path (if bootstrap fails) If `bd bootstrap` doesn’t work (older bd versions, unusual remote configs), follow these steps: **Step 1: Confirm the remote has beads data** git ls-remote origin | grep dolt # Expected: <hash> refs/dolt/data # If missing, the remote has no beads data — use bd init normally. **Step 2: Initialize beads** bd init This creates `.beads/` with an empty database. Ignore any warnings about `bd bootstrap` — we’ll replace the empty database manually. **Step 3: Stop the Dolt server** bd dolt stop **Step 4: Find your database name and remove the empty database** # Check your database name cat .beads/metadata.json # look for "dolt_database" The `dolt_database` field is your `<dbname>` (typically the repo name). # Remove the empty database rm -rf .beads/dolt/<dbname>/ **Step 5: Clone the Dolt data from the remote** cd .beads/dolt dolt clone git@github.com:org/repo.git <dbname> cd ../.. **Step 6: Start the server and migrate** bd dolt start bd migrate --yes **Step 7: Ensure the remote is registered** bd dolt remote add origin git+ssh://git@github.com/org/repo.git If you see “remote already exists”, that’s fine — `dolt clone` already set it up. **Step 8: Verify** bd dolt remote list # should show origin bd list # should show your issues [​](https://beads.gascity.com/getting-started/sync-setup#day-to-day-sync) Day-to-day Sync -------------------------------------------------------------------------------------------- Once set up on both machines, sync is two commands: # Push your changes to the remote bd dolt push # Pull changes from the remote bd dolt pull ### [​](https://beads.gascity.com/getting-started/sync-setup#typical-workflow) Typical workflow Machine A Machine B ───────── ───────── bd create "New task" -p 1 bd dolt push bd dolt pull bd update bd-a1b2 --claim bd close bd-a1b2 --reason "Done" bd dolt push bd dolt pull bd list # sees the closed task ### [​](https://beads.gascity.com/getting-started/sync-setup#important-rules) Important rules * **Always use `bd dolt ...` commands** — never run raw `dolt` CLI commands while the Dolt server is running. It causes journal corruption. * **Commit before pulling** — if you have uncommitted working set changes, `bd dolt pull` will fail with “cannot merge with uncommitted changes”. Run `bd dolt commit` first. * **Push before switching machines** — unpushed changes only exist locally. * **Do not use JSONL as sync** — `.beads/issues.jsonl` is an export for viewers and interchange. It is not the source of truth, not a full database backup, and cannot safely reconcile deletes or pruning. [​](https://beads.gascity.com/getting-started/sync-setup#troubleshooting) Troubleshooting -------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/getting-started/sync-setup#%E2%80%9Dno-common-ancestor%E2%80%9D-on-push) ”no common ancestor” on push A stale `refs/dolt/data` from a previous database is conflicting. Clear it and retry: git update-ref -d refs/dolt/data bd dolt push ### [​](https://beads.gascity.com/getting-started/sync-setup#%E2%80%9Ccannot-merge-with-uncommitted-changes%E2%80%9D-on-pull) “cannot merge with uncommitted changes” on pull Commit your working set first: bd dolt commit bd dolt pull ### [​](https://beads.gascity.com/getting-started/sync-setup#%E2%80%9Cno-store-available%E2%80%9D-on-push-or-commit) “no store available” on push or commit This was a bug in bd < 0.59.0. Upgrade bd: brew upgrade beads # or re-run the install script ### [​](https://beads.gascity.com/getting-started/sync-setup#bd-list-shows-nothing-after-clone) bd list shows nothing after clone The Dolt database wasn’t bootstrapped. Either run `bd bootstrap` or follow the [manual path](https://beads.gascity.com/getting-started/sync-setup#manual-path-if-bootstrap-fails) above. ### [​](https://beads.gascity.com/getting-started/sync-setup#stale-lock-files-after-crash) Stale lock files after crash bd doctor --fix --yes **WARNING**: Do NOT manually remove files inside `.dolt/` directories (including `noms/LOCK`). These are Dolt-internal files and removing them **will cause unrecoverable data corruption**. Dolt manages these files itself. ### [​](https://beads.gascity.com/getting-started/sync-setup#%E2%80%9Dfatal-unable-to-read-current-working-directory%E2%80%9D) ”fatal: Unable to read current working directory” The Dolt server’s working directory no longer exists (common after branch switches). Restart it: bd dolt stop bd dolt start [​](https://beads.gascity.com/getting-started/sync-setup#see-also) See Also ------------------------------------------------------------------------------ * [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts) — The conceptual model behind this setup (why Dolt is the source of truth, what JSONL is for) * [Quick Start](https://beads.gascity.com/getting-started/quickstart) — Getting started with beads * [Dolt Backend for Beads](https://beads.gascity.com/architecture/dolt) — Dolt backend details, server modes, federation, remote types, and sync modes * [Installation](https://beads.gascity.com/getting-started/installation) — Installation for all platforms [​](https://beads.gascity.com/getting-started/sync-setup#attribution) Attribution ------------------------------------------------------------------------------------ This guide was inspired by [@leonletto](https://github.com/leonletto) ’s community setup guide at [leonletto.github.io/thrum](https://leonletto.github.io/thrum/docs.html#guides/beads-setup.html) , which documented the end-to-end setup and sync process including the manual bootstrap workflow. Thanks for contributing to the beads community! [IDE Setup](https://beads.gascity.com/getting-started/ide-setup) [Upgrading](https://beads.gascity.com/getting-started/upgrading) ⌘I --- # Molecules - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/workflows/molecules#content-area) Molecules are work graphs: epics whose children flow through `bd ready` as dependency-ordered steps. They are usually instantiated from formulas, but a formula is optional — any epic with children is a molecule. [​](https://beads.gascity.com/workflows/molecules#what-is-a-molecule) What is a Molecule? -------------------------------------------------------------------------------------------- A molecule is a persistent instance of a proto (a cooked formula): * Contains steps with dependencies * Persistent beads in the issue database, synced like any other bead * Steps map to issues with parent-child relationships Under the hood, **a molecule is just an epic** — a parent bead with children — plus workflow semantics: | Term | Meaning | When to use | | --- | --- | --- | | **Epic** | Parent issue with children | General term for hierarchical work | | **Molecule** | Epic with execution intent | When discussing workflow traversal | | **Proto** | Epic with the `template` label | Reusable pattern (optional) | Protos and formulas are optional layers for reusable patterns and complex composition — most work needs only epics and dependencies. [​](https://beads.gascity.com/workflows/molecules#creating-molecules) Creating Molecules ------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/workflows/molecules#from-a-formula) From a Formula # Cook the formula into a proto, then pour the proto into a molecule bd cook release.formula.toml bd mol pour release --var version=1.0.0 This creates: * Parent issue: `bd-xyz` (the molecule root) * Child issues: `bd-xyz.1`, `bd-xyz.2`, etc. (the steps) ### [​](https://beads.gascity.com/workflows/molecules#without-a-formula) Without a Formula Create the epic and wire the dependencies directly: bd create "Feature X" -t epic bd create "Design" -t task --parent <epic-id> bd create "Implement" -t task --parent <epic-id> bd create "Test" -t task --parent <epic-id> bd dep add <implement-id> <design-id> # implement needs design bd dep add <test-id> <implement-id> # test needs implement If an ad-hoc epic turns out to be worth repeating, extract a reusable formula from it with `bd mol distill <epic-id> <formula-name>`. ### [​](https://beads.gascity.com/workflows/molecules#finding-molecules) Finding Molecules bd mol current # Where you are in the molecule you're working bd mol stale # Complete-but-still-open molecules bd mol wisp list # Ephemeral molecules (wisps) ### [​](https://beads.gascity.com/workflows/molecules#viewing-a-molecule) Viewing a Molecule bd mol show <molecule-id> # Structure and variables bd mol show <molecule-id> --parallel # Highlight steps that can run concurrently bd dep tree <molecule-id> # Shows full hierarchy [​](https://beads.gascity.com/workflows/molecules#working-with-molecules) Working with Molecules --------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/workflows/molecules#the-execution-model) The Execution Model An agent picks up a molecule and executes ready children in parallel until everything closes: epic-root (assigned to agent) ├── child.1 (no deps → ready) ← execute in parallel ├── child.2 (no deps → ready) ← execute in parallel ├── child.3 (needs child.1) → blocked until child.1 closes └── child.4 (needs child.2, child.3) → blocked until both close **Children are parallel by default.** Only explicit dependencies create sequence. The multi-session loop: 1. Get ready work: `bd ready --mol <molecule-id>` 2. Claim it: `bd update <id> --claim` 3. Do the work 4. Close it: `bd close <id>` 5. Repeat until the molecule is done ### [​](https://beads.gascity.com/workflows/molecules#dependency-types) Dependency Types Only some dependency types block execution: | Type | Semantics | Use case | | --- | --- | --- | | `blocks` | B can’t start until A closes | Sequencing work | | `parent-child` | If the parent is blocked, children are blocked | Hierarchy (children parallel by default) | | `conditional-blocks` | B runs only if A fails | Error-handling paths | | `waits-for` | B waits for all of A’s dynamic children | Fan-in gates — see [Gates](https://beads.gascity.com/workflows/gates) | Non-blocking types (`related`, `discovered-from`, `replies-to`) link issues without affecting execution. ### [​](https://beads.gascity.com/workflows/molecules#step-dependencies) Step Dependencies In a formula, steps declare `needs`: [[steps]] id = "implement" title = "Implement feature" needs = ["design"] # Must complete design first On live issues, add the edge directly — the dependent comes first: bd dep add <B-id> <A-id> # B depends on A (B needs A) The `bd ready` command respects these: bd ready --mol <molecule-id> # Only shows steps with completed dependencies ### [​](https://beads.gascity.com/workflows/molecules#progressing-through-steps) Progressing Through Steps # Start a step bd update bd-xyz.1 --claim # Complete a step bd close bd-xyz.1 --reason "Done" # Check what's ready next bd ready --mol bd-xyz ### [​](https://beads.gascity.com/workflows/molecules#viewing-progress) Viewing Progress # See blocked steps bd blocked # Step-by-step status: [done] / [current] / [ready] / [blocked] / [pending] bd mol current <molecule-id> # Progress summary: completed/total, rate, ETA bd mol progress <molecule-id> [​](https://beads.gascity.com/workflows/molecules#molecule-lifecycle) Molecule Lifecycle ------------------------------------------------------------------------------------------- Formula (template source) ↓ bd cook Proto (template epic) ↓ bd mol pour Molecule (instance) ↓ work steps Completed Molecule ↓ optional cleanup Closed / Squashed / Burned Closing the last child does not close the molecule root — epics stay open as close-eligible work until closed explicitly (`bd epic close-eligible` sweeps them). For cleanup of the beads themselves: * `bd mol squash <id>` condenses a molecule’s ephemeral children into a permanent digest issue. * `bd mol burn <id>` deletes a molecule outright, no digest — for abandoned or test runs. See [Wisps](https://beads.gascity.com/workflows/wisps) for the ephemeral lifecycle these commands usually serve. [​](https://beads.gascity.com/workflows/molecules#bonding-connecting-work-graphs) Bonding: Connecting Work Graphs -------------------------------------------------------------------------------------------------------------------- **Bond** means creating a dependency between two work graphs. When molecule A blocks molecule B, completing A unblocks B and an agent can continue from A into B — one compound workflow that can span days. bd mol bond A B # B depends on A (sequential by default) bd mol bond A B --type parallel # B runs alongside A bd mol bond A B --type conditional # B runs only if A fails The command is polymorphic over its operands: | Operands | What happens | | --- | --- | | proto + proto | Compound proto (reusable template) | | proto + molecule | Spawns the proto as new issues, attached to the molecule | | molecule + molecule | Joins them into a compound molecule | | formula + anything | The formula is cooked inline first | Spawned issues follow the target’s phase (persistent or ephemeral) by default. Override with `--pour` (force persistent) or `--ephemeral` (force ephemeral) — see [Wisps](https://beads.gascity.com/workflows/wisps) . ### [​](https://beads.gascity.com/workflows/molecules#dynamic-bonding) Dynamic Bonding When the number of children isn’t known until runtime, bond in a loop with `--ref` to get readable child IDs instead of random hashes: # One arm per discovered worker bd mol bond mol-worker-arm bd-patrol --ref arm-{{name}} --var name=ace # Creates: bd-patrol.arm-ace (and children like bd-patrol.arm-ace.capture) [​](https://beads.gascity.com/workflows/molecules#advanced-features) Advanced Features ----------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/workflows/molecules#bond-points) Bond Points Formulas can define bond points — named attachment sites for composition. Each names a step to attach `before_step` or `after_step` (with optional `parallel = true`): [[compose.bond_points]] id = "entry" description = "Attach setup work here" before_step = "design" ### [​](https://beads.gascity.com/workflows/molecules#hooks) Hooks Step-completion hooks are not currently exposed as runnable formula actions. The historical `on_complete.run` example was invalid: `run` is not a formula field, and `on_complete` runtime expansion is tracked separately until it is wired end to end. ### [​](https://beads.gascity.com/workflows/molecules#assigning-molecules) Assigning Molecules Assign the molecule root to an agent at pour time, then track where each agent is: bd mol pour mol-feature --assignee <agent> # Assign on creation bd mol current --for <agent> # Where that agent is [​](https://beads.gascity.com/workflows/molecules#agent-pitfalls) Agent Pitfalls ----------------------------------------------------------------------------------- 1. **Temporal language inverts dependencies.** “Phase 1 comes before Phase 2” tempts `bd dep add phase1 phase2` — backwards. Use requirement language: “Phase 2 needs Phase 1” is `bd dep add phase2 phase1`. Verify with `bd blocked`. 2. **Numbered steps don’t create sequence.** Steps named “Step 1/2/3” still run in parallel until you add dependencies between them. 3. **Forgetting to close work.** Blocked issues stay blocked forever if their blockers aren’t closed: `bd close <id> --reason "Done"`. [​](https://beads.gascity.com/workflows/molecules#example-workflow) Example Workflow --------------------------------------------------------------------------------------- # 1. Create molecule from formula bd cook feature-workflow.formula.toml bd mol pour feature-workflow --var name="dark-mode" # 2. View structure bd dep tree bd-xyz # 3. Start first step bd update bd-xyz.1 --claim # 4. Complete and progress bd close bd-xyz.1 bd ready --mol bd-xyz # Shows next steps # 5. Continue until complete [​](https://beads.gascity.com/workflows/molecules#see-also) See Also ----------------------------------------------------------------------- * [Formulas](https://beads.gascity.com/workflows/formulas) - Creating templates * [Gates](https://beads.gascity.com/workflows/gates) - Async coordination * [Wisps](https://beads.gascity.com/workflows/wisps) - Ephemeral workflows [Workflows](https://beads.gascity.com/workflows) [Formulas](https://beads.gascity.com/workflows/formulas) ⌘I --- # Azure DevOps (ADO) Integration Configuration - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/azure-devops#content-area) Last reviewed: 2026-05-08 Freshness source: `cmd/bd/ado*.go` and `internal/ado/`. This guide covers all configuration options for the `bd ado sync` command, which synchronizes beads issues with Azure DevOps work items. [​](https://beads.gascity.com/integrations/azure-devops#quick-start) Quick Start ----------------------------------------------------------------------------------- # Set required config bd config set ado.pat "your-personal-access-token" bd config set ado.org "your-organization" bd config set ado.project "your-project" # Or use environment variables export AZURE_DEVOPS_PAT="your-personal-access-token" export AZURE_DEVOPS_ORG="your-organization" export AZURE_DEVOPS_PROJECT="your-project" # Sync (bidirectional) bd ado sync # Pull only (import from ADO) bd ado sync --pull-only # Push only (export to ADO) bd ado sync --push-only # Preview without making changes bd ado sync --dry-run [​](https://beads.gascity.com/integrations/azure-devops#connection-configuration) Connection Configuration ------------------------------------------------------------------------------------------------------------- | Config Key | Env Variable | Required | Description | | --- | --- | --- | --- | | `ado.pat` | `AZURE_DEVOPS_PAT` | Yes | Personal Access Token | | `ado.org` | `AZURE_DEVOPS_ORG` | Conditional¹ | Organization name (e.g., `myorg`) | | `ado.url` | `AZURE_DEVOPS_URL` | Conditional¹ | Custom base URL (on-prem ADO Server) | | `ado.project` | `AZURE_DEVOPS_PROJECT` | Conditional² | Single project name | | `ado.projects` | `AZURE_DEVOPS_PROJECTS` | Conditional² | Comma-separated project names | ¹ Either `ado.org` or `ado.url` must be set. Use `ado.url` for on-premises Azure DevOps Server. ² At least one project must be configured via `ado.project` or `ado.projects`. **Config vs env var precedence:** Config keys (set via `bd config set`) take priority over environment variables. ### [​](https://beads.gascity.com/integrations/azure-devops#on-premises-ado-server) On-Premises ADO Server For Azure DevOps Server (on-prem), use `ado.url` instead of `ado.org`: bd config set ado.url "https://tfs.company.com/DefaultCollection" bd config set ado.project "MyProject" ### [​](https://beads.gascity.com/integrations/azure-devops#multi-project-sync) Multi-Project Sync Sync across multiple projects in a single command: bd config set ado.projects "ProjectA,ProjectB,ProjectC" The first project is used as the primary for URL construction. WIQL queries use `TeamProject IN (...)` for multi-project support. [​](https://beads.gascity.com/integrations/azure-devops#filter-configuration) Filter Configuration ----------------------------------------------------------------------------------------------------- Filters control which ADO work items are included in sync operations. | Config Key | CLI Flag | Description | Example | | --- | --- | --- | --- | | `ado.filter.area_path` | `--area-path` | Area path (uses UNDER) | `Project\Team` | | `ado.filter.iteration_path` | `--iteration-path` | Sprint/iteration path | `Project\Sprint 1` | | `ado.filter.types` | `--types` | Work item types (comma-separated) | `Bug,Task,User Story` | | `ado.filter.states` | `--states` | ADO states (comma-separated) | `New,Active,Resolved` | CLI flags override config values for that sync run. **WIQL query example** (generated from filters): SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = 'MyProject' AND [System.IsDeleted] = false AND [System.AreaPath] UNDER 'Project\Team' AND [System.WorkItemType] IN ('Bug', 'Task') AND [System.State] IN ('New', 'Active') ORDER BY [System.ChangedDate] ASC [​](https://beads.gascity.com/integrations/azure-devops#default-mappings) Default Mappings --------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/azure-devops#priority-mapping) Priority Mapping Priority mapping is bidirectional but **lossy for P3/P4**: | Beads Priority | ADO Priority | Direction | Notes | | --- | --- | --- | --- | | 0 (Critical) | 1 | ↔ | | | 1 (High) | 2 | ↔ | | | 2 (Medium) | 3 | ↔ | Default for unknown values | | 3 (Low) | 4 | → | | | 4 (Backlog) | 4 | → | **Lossy**: becomes P3 on pull | > **Note:** Beads P3 and P4 both map to ADO priority 4. On a fresh pull into an empty database, ADO 4 maps back to beads P3. The original priority is not preserved across a full round-trip for P4 issues. For Bug-type work items, ADO also requires a Severity field: | Beads Priority | ADO Severity | | --- | --- | | 0 | 1 - Critical | | 1 | 2 - High | | 2 | 3 - Medium | | 3, 4 | 4 - Low | ### [​](https://beads.gascity.com/integrations/azure-devops#status-mapping) Status Mapping | Beads Status | Default ADO State | Config Key | | --- | --- | --- | | `open` | `New` | `ado.state_map.open` | | `in_progress` | `Active` | `ado.state_map.in_progress` | | `blocked` | `Active` + `beads:blocked` tag | `ado.state_map.blocked` | | `deferred` | `Removed` | `ado.state_map.deferred` | | `closed` | `Closed` | `ado.state_map.closed` | **Blocked status:** ADO has no native blocked state. beads maps blocked to `Active` and adds a `beads:blocked` tag. On pull, `Active` + `beads:blocked` tag restores `StatusBlocked`. Override defaults for your process template: # Example: Scrum template bd config set ado.state_map.open "To Do" bd config set ado.state_map.in_progress "In Progress" bd config set ado.state_map.closed "Done" ### [​](https://beads.gascity.com/integrations/azure-devops#type-mapping) Type Mapping | Beads Type | Default ADO Type | Config Key | | --- | --- | --- | | `bug` | `Bug` | `ado.type_map.bug` | | `feature` | `User Story` | `ado.type_map.feature` | | `task` | `Task` | `ado.type_map.task` | | `epic` | `Epic` | `ado.type_map.epic` | | `chore` | `Task` | `ado.type_map.chore` | Reverse mapping (ADO → beads) also recognizes: * `Product Backlog Item` → `feature` (Scrum template) * `Issue` → `task` Override for your process template: # Example: Scrum template bd config set ado.type_map.feature "Product Backlog Item" [​](https://beads.gascity.com/integrations/azure-devops#process-template-configuration) Process Template Configuration ------------------------------------------------------------------------------------------------------------------------- ADO supports multiple process templates with different work item types and state transitions. The defaults assume the **Agile** template. Override mappings for other templates. ### [​](https://beads.gascity.com/integrations/azure-devops#agile-default) Agile (Default) No configuration needed. Default mappings work out of the box. State transitions: Bug: New → Active → Resolved → Closed Task: New → Active → Closed User Story: New → Active → Resolved → Closed Epic: New → Active → Resolved → Closed ### [​](https://beads.gascity.com/integrations/azure-devops#scrum) Scrum bd config set ado.type_map.feature "Product Backlog Item" bd config set ado.state_map.open "New" bd config set ado.state_map.in_progress "Committed" bd config set ado.state_map.closed "Done" State transitions: Product Backlog Item: New → Approved → Committed → Done Task: To Do → In Progress → Done Bug: New → Approved → Committed → Done ### [​](https://beads.gascity.com/integrations/azure-devops#cmmi) CMMI bd config set ado.type_map.feature "Requirement" bd config set ado.state_map.open "Proposed" bd config set ado.state_map.in_progress "Active" bd config set ado.state_map.closed "Closed" State transitions: Requirement: Proposed → Active → Resolved → Closed Task: Proposed → Active → Closed Bug: Proposed → Active → Resolved → Closed ### [​](https://beads.gascity.com/integrations/azure-devops#state-transition-handling) State Transition Handling When creating a work item in a non-initial state (e.g., pushing a closed issue), beads: 1. Creates the item in the initial state (e.g., `New`) 2. Transitions through intermediate states to reach the target 3. Example: Creating a closed Bug → `New → Active → Resolved → Closed` If a direct transition fails (ADO returns 400), beads automatically walks the known transition path for the work item type and process template. [​](https://beads.gascity.com/integrations/azure-devops#sync-options) Sync Options ------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/azure-devops#direction) Direction | Flag | Description | | --- | --- | | (none) | Bidirectional: pull then push | | `--pull-only` | Import from ADO only | | `--push-only` | Export to ADO only | ### [​](https://beads.gascity.com/integrations/azure-devops#conflict-resolution) Conflict Resolution When the same issue has been modified both locally and in ADO: | Flag | Description | | --- | --- | | `--prefer-newer` | Most recently updated version wins (default) | | `--prefer-local` | Local beads version always wins | | `--prefer-ado` | ADO version always wins | ### [​](https://beads.gascity.com/integrations/azure-devops#additional-flags) Additional Flags | Flag | Description | | --- | --- | | `--dry-run` | Preview sync without making changes | | `--no-create` | Only update existing items, never create new ones | | `--bootstrap-match` | Enable heuristic title matching for first sync | | `--reconcile` | Force reconciliation scan for deleted items | | `--issues` | Sync specific issues by bead ID or ADO work item ID | | `--states` | Filter by work item states (comma-separated) | | `--types` | Filter by work item types (comma-separated) | | `--issues` | Sync specific beads by ID | [​](https://beads.gascity.com/integrations/azure-devops#pat-permissions) PAT Permissions ------------------------------------------------------------------------------------------- The Personal Access Token needs these scopes: | Scope | Access | Required For | | --- | --- | --- | | Work Items | Read & Write | Creating and updating work items | Generate a PAT at: `https://dev.azure.com/{org}/_usersettings/tokens` [​](https://beads.gascity.com/integrations/azure-devops#metadata-preserved) Metadata Preserved ------------------------------------------------------------------------------------------------- beads stores ADO-specific metadata for round-trip fidelity: | Metadata Key | Description | | --- | --- | | `ado.rev` | ADO revision number | | `ado.area_path` | Area path | | `ado.iteration_path` | Iteration/sprint path | | `ado.story_points` | Story points estimate | | `ado.remaining_work` | Remaining work hours | | `ado.severity` | Bug severity value | [​](https://beads.gascity.com/integrations/azure-devops#description-conversion) Description Conversion --------------------------------------------------------------------------------------------------------- * **Push (beads → ADO):** Markdown converted to HTML * **Pull (ADO → beads):** HTML converted to Markdown [​](https://beads.gascity.com/integrations/azure-devops#tags-and-labels) Tags and Labels ------------------------------------------------------------------------------------------- * ADO tags are semicolon-separated; beads labels use arrays * User labels round-trip through ADO tags * Internal `beads:*` tags (e.g., `beads:blocked`) are filtered on pull — they don’t appear as user labels [​](https://beads.gascity.com/integrations/azure-devops#api-limits) API Limits --------------------------------------------------------------------------------- | Limit | Value | | --- | --- | | Max batch size | 200 work items per GET request | | Max response size | 50 MB | | Request timeout | 30 seconds | | Max retries | 3 (GET and WIQL only) | | Retry backoff | Exponential with jitter, respects `Retry-After` header | [​](https://beads.gascity.com/integrations/azure-devops#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/azure-devops#common-errors) Common Errors **`ado.pat not configured: set via 'bd config set ado.pat <token>' or AZURE_DEVOPS_PAT env var`** bd config set ado.pat "your-pat-here" # or export AZURE_DEVOPS_PAT="your-pat-here" **“ado.organization not configured”** bd config set ado.org "your-org" # or for on-prem: bd config set ado.url "https://tfs.company.com/DefaultCollection" **State transition errors (400 Bad Request)** This usually means the process template doesn’t support a direct state change. Check your `ado.state_map.*` config matches your actual process template. **Type not found errors** Verify your `ado.type_map.*` config matches the work item types available in your project. Use `--types` filter to restrict which types are synced. ### [​](https://beads.gascity.com/integrations/azure-devops#debugging) Debugging # Preview what would happen bd ado sync --dry-run # Check current config bd config get ado.pat bd config get ado.org bd config get ado.project [GitHub Copilot CLI Integration Design](https://beads.gascity.com/integrations/copilot-cli) [Community Tools](https://beads.gascity.com/community-tools) ⌘I --- # Upgrading - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/getting-started/upgrading#content-area) How to upgrade bd and keep your projects in sync. [​](https://beads.gascity.com/getting-started/upgrading#checking-for-updates) Checking for Updates ----------------------------------------------------------------------------------------------------- # Current version bd version # What's new in recent versions bd info --whats-new bd info --whats-new --json # Machine-readable [​](https://beads.gascity.com/getting-started/upgrading#short-version) Short Version --------------------------------------------------------------------------------------- 1. With your current `bd`, sync remote-backed databases before installing the new binary: `bd dolt push` `bd dolt pull` 2. Back up before migration: `bd export --all -o .beads/backup/pre-migrate-$(date +%Y%m%d).jsonl` 3. Upgrade using the command that matches your install method. 4. After upgrading: `bd info --whats-new` `bd hooks install` `bd version` 5. If crossing a schema migration on a remote-backed database, only the designated migrator runs: `bd migrate` `bd dolt push` Other clones should install the new binary and run `bd bootstrap`, not independently migrate. The full procedure is below. [​](https://beads.gascity.com/getting-started/upgrading#upgrading) Upgrading ------------------------------------------------------------------------------- Use the command that matches your install method. | Install method | Platforms | Command | | --- | --- | --- | | Quick install script | macOS, Linux, FreeBSD | `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh \| bash` | | PowerShell installer | Windows | `irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 \| iex` | | Homebrew | macOS, Linux | `brew upgrade beads` | | go install (server-mode only) | macOS, Linux, FreeBSD, Windows | `CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest` | | go install (embedded-capable) | macOS, Linux, Windows | `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest` | | npm | macOS, Linux, Windows | `npm update -g @beads/bd` | | bun | macOS, Linux, Windows | `bun install -g --trust @beads/bd` | | From source (Unix shell) | macOS, Linux, FreeBSD | `git pull && make build` | ### [​](https://beads.gascity.com/getting-started/upgrading#quick-install-script-macos/linux/freebsd) Quick install script (macOS/Linux/FreeBSD) curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ### [​](https://beads.gascity.com/getting-started/upgrading#powershell-installer-windows) PowerShell installer (Windows) irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex ### [​](https://beads.gascity.com/getting-started/upgrading#homebrew) Homebrew brew upgrade beads If you still have the old tap formula installed as `bd`, switch to the Homebrew core formula: brew uninstall bd brew untap gastownhall/beads 2>/dev/null || true brew untap steveyegge/beads 2>/dev/null || true brew install beads ### [​](https://beads.gascity.com/getting-started/upgrading#go-install) go install # Server-mode only CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest # Embedded-capable CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ### [​](https://beads.gascity.com/getting-started/upgrading#from-source) From Source cd beads git pull make build sudo mv bd /usr/local/bin/ [​](https://beads.gascity.com/getting-started/upgrading#after-upgrading) After Upgrading ------------------------------------------------------------------------------------------- **Important:** After upgrading, update your hooks: # 1. Check what changed bd info --whats-new # 2. Update git hooks to match new version bd hooks install # 3. Check for any outdated hooks bd info # Shows warnings if hooks are outdated # 4. If using Dolt backend, restart the server bd dolt stop && bd dolt start **Why update hooks?** Git hooks are versioned with bd. Outdated hooks may miss export refresh, legacy fallback, or safety fixes. [​](https://beads.gascity.com/getting-started/upgrading#database-migrations) Database Migrations --------------------------------------------------------------------------------------------------- After major upgrades, check for database migrations: # Inspect migration plan (AI agents) bd migrate --inspect --json # Preview migration changes bd migrate --dry-run # Apply migrations bd migrate # Migrate and clean up old files bd migrate --yes ### [​](https://beads.gascity.com/getting-started/upgrading#remote-backed-databases-and-multiple-clones) Remote-backed databases and multiple clones `bd` refuses to silently apply pending schema migrations to a database that has a Dolt remote configured. Migrating more than one clone of a shared remote independently forks the schema, after which `bd dolt pull` can no longer merge — the break is silent and, across a primary-key-reshaping migration, unrecoverable ([#4259](https://github.com/gastownhall/beads/issues/4259) ). The supported flow is: one machine migrates and publishes; every other clone re-clones the migrated database. This applies to **every** upgrade that crosses a pending migration on a remote-backed database — the same procedure whether you are moving to a prerelease or to a stable release. The gate is **state-aware by default** ([#4516](https://github.com/gastownhall/beads/issues/4516) ): before blocking, `bd` consults the remote’s _cached_ schema state and * **auto-migrates** when the remote is at the same schema version as this clone — no one has migrated yet, so this clone is a safe first-mover (concurrent first-movers converge to identical tables). It reminds you to `bd dolt push` afterwards. * **stops and directs you to adopt** (`bd bootstrap`) when the remote has already been migrated by another clone. * **stops for a human decision** when this clone and the remote applied different content for the same migration (a genuine fork), or when the remote’s schema state cannot be read from the cached ref. Set `BD_SMART_GATE=0` to opt out and make the gate block unconditionally. The recipes below are the explicit path and work the same in either mode. **Important ordering:** once the new binary is installed, a database with pending migrations is gated on **every** open — `bd dolt push` and `bd dolt pull` are refused too, not just `bd migrate`. So do all syncing with your **current** binary, _before_ you install the new one. **Back up before you migrate.** Schema migrations assume the database matches the shape the previous migrations left behind; real databases sometimes drift (interrupted writes, tooling bugs, very old bootstraps). A JSONL export is cheap, issue-complete, and importable by any bd version: bd export --all -o .beads/backup/pre-migrate-$(date +%Y%m%d).jsonl `bd export` captures issues, not Dolt history or config — for a full snapshot also copy the `.beads` directory (or `dolt backup` in server mode) while no `bd` command is running. **Single clone (including a solo user with a remote):** bd dolt push # 1. CURRENT binary: publish all local work bd export --all -o .beads/backup/pre-migrate.jsonl # 2. backup (see above) # 3. install the new binary (see Upgrading above) bd migrate # 4. migrate as the designated migrator bd dolt push # 5. publish the migrated schema bd version # 6. confirm the new version is active If `bd`’s remote-migrate gate blocks the run, it prints the available options — migrating here as the designated migrator, adopting the remote’s already-migrated database, or recovering a fork — and asks for an explicit operator decision. Follow the guidance it prints. For scripted or CI upgrades where nobody reads the prompt, `BD_ALLOW_REMOTE_MIGRATE=1 bd migrate` (any boolean true value works) declares this clone the designated migrator and bypasses the gate entirely — including its already-forked checks — so wire it into exactly one clone’s upgrade job, never all of them. **Multiple clones sharing one remote:** # 1. With your CURRENT (old) binary, on EVERY clone: publish all work and get in # sync, then stop editing until the upgrade is done. bd dolt push bd dolt pull # 2. Designated migrator ONLY: back up, install the new binary, then migrate # and publish. bd export --all -o .beads/backup/pre-migrate.jsonl bd migrate bd dolt push # 3. Every OTHER clone: install the new binary, then ADOPT the migrated database. # (bd dolt pull is refused here — the clone still has pending migrations — so # re-clone instead. Safe because step 1 already pushed all work.) bd bootstrap `bd bootstrap` replaces the local database, so any work not pushed in step 1 is lost — that is why step 1 publishes everything first. If a clone was instead migrated independently and `bd dolt pull` later fails with `cannot merge because table dependencies has different primary keys in its common ancestor`, the schema has already forked — follow the recovery playbook: [the pk-fork-refused runbook](https://beads.gascity.com/recovery/init-safety#pk-fork-refused) . `bd doctor` includes a migration-content-skew check that flags a forked schema against the cached remote ref — a useful post-upgrade verification. It runs in both server and embedded modes. [​](https://beads.gascity.com/getting-started/upgrading#cross-era-upgrades) Cross-era Upgrades ------------------------------------------------------------------------------------------------- If you’re upgrading from a much older version of bd, your project may use a different storage backend. bd has gone through several storage eras: Identify your installation’s era by what lives under `.beads/`: | Era | Storage layout | | --- | --- | | SQLite (pre-Dolt, up to ~v0.50) | `.beads/beads.db` | | Dolt server | `.beads/dolt/` | | Embedded Dolt (the default since its introduction) | `.beads/embeddeddolt/` | ### [​](https://beads.gascity.com/getting-started/upgrading#from-v0-63-3+-current-era) From v0.63.3+ (current era) Upgrade the binary and run: bd migrate If the project was initialized before `bd init` automatically wired git origin as the Dolt remote, verify the remote after upgrading: bd dolt remote list When the list is empty, fix it on the machine whose local database is authoritative: bd export -o .beads/issues.pre-remote.jsonl # optional issue audit export bd dolt remote add origin git+ssh://git@github.com/org/repo.git bd dolt push Commit the resulting `.beads/config.yaml` change so other clones can run `bd bootstrap` or `bd dolt pull`. ### [​](https://beads.gascity.com/getting-started/upgrading#from-v0-59%E2%80%93v0-63-2-old-embedded) From v0.59–v0.63.2 (old embedded) Direct upgrade works automatically: # Just use the new binary — it handles the conversion bd list ### [​](https://beads.gascity.com/getting-started/upgrading#from-v0-50%E2%80%93v0-58-dolt-server-era) From v0.50–v0.58 (Dolt server era) The old binary used an external Dolt SQL server. The new binary uses an embedded engine. # 1. Export your data while the old binary still works bd list --json -n 0 --all > .beads/issues.jsonl # 2. Stop the Dolt server # stop the dolt sql-server process (kill its PID; there is no --stop flag) # 3. Remove stale server metadata and old storage directories rm -f .beads/metadata.json .beads/config.json rm -rf .beads/dolt .beads/embeddeddolt # 4. Initialize with the new binary bd init --from-jsonl --quiet # 5. Verify bd list --all ### [​](https://beads.gascity.com/getting-started/upgrading#from-v0-30%E2%80%93v0-50-sqlite-era) From v0.30–v0.50 (SQLite era) The old binary stored data in SQLite. The new binary uses Dolt. **Recommended: use the migration script** (requires `sqlite3` and `jq`): # Download the script from the beads repo curl -fsSLO https://raw.githubusercontent.com/gastownhall/beads/main/scripts/migrate-sqlite-to-current.sh chmod +x migrate-sqlite-to-current.sh # Run it in your project directory ./migrate-sqlite-to-current.sh The script exports issues, dependencies, and labels from SQLite, handles type normalization, and imports everything into the new Dolt backend. **Alternative: manual export with the old binary.** Old binaries are always available on [GitHub Releases](https://github.com/gastownhall/beads/releases) . Download the version that matches your project, then: # 1. Export with the old binary ./bd-old list --json -n 0 --all > .beads/issues.jsonl # 2. Import with the current binary bd init --from-jsonl --quiet # 3. Verify bd list --all > **Note:** The manual export preserves issue content but not dependencies or labels. Use the migration script for a more complete transfer. [​](https://beads.gascity.com/getting-started/upgrading#troubleshooting-upgrades) Troubleshooting Upgrades ------------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/getting-started/upgrading#hooks-out-of-date) Hooks out of date bd hooks install ### [​](https://beads.gascity.com/getting-started/upgrading#database-schema-changed) Database schema changed bd migrate --dry-run bd migrate ### [​](https://beads.gascity.com/getting-started/upgrading#recovery-after-upgrade) Recovery after upgrade If you need to restore from a backup: bd init bd backup restore [path] --force Or pull from a Dolt remote: bd dolt pull [Sync Setup Guide](https://beads.gascity.com/getting-started/sync-setup) [How Beads Works](https://beads.gascity.com/core-concepts) ⌘I --- # Beads Claude Code Plugin - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/integrations/claude-code-plugin#content-area) AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with slash commands, a bundled skill, and lifecycle hooks. [​](https://beads.gascity.com/integrations/claude-code-plugin#what-is-beads) What is Beads? ---------------------------------------------------------------------------------------------- Beads (`bd`) is an issue tracker designed specifically for AI-supervised coding workflows. It helps AI agents and developers: * Track work with a simple CLI * Discover and link related tasks during development * Maintain context across coding sessions * Sync issues via Dolt remotes for distributed workflows [​](https://beads.gascity.com/integrations/claude-code-plugin#installation) Installation ------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/claude-code-plugin#prerequisites) Prerequisites 1. Install beads CLI: curl -sSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ### [​](https://beads.gascity.com/integrations/claude-code-plugin#install-plugin) Install Plugin There are two ways to install the beads plugin: #### [​](https://beads.gascity.com/integrations/claude-code-plugin#option-1-from-github-recommended) Option 1: From GitHub (Recommended) # In Claude Code /plugin marketplace add gastownhall/beads /plugin install beads #### [​](https://beads.gascity.com/integrations/claude-code-plugin#option-2-local-development) Option 2: Local Development # Clone the repository (shell command) git clone https://github.com/gastownhall/beads cd beads Then in Claude Code: # Add local marketplace (Claude Code command) /plugin marketplace add ./beads # Install plugin /plugin install beads **Note:** If you want to install the plugin from a different repo, first `cd` to that repo’s directory in your terminal, then use `./beads` (or the relative path to the beads directory) in Claude Code. ### [​](https://beads.gascity.com/integrations/claude-code-plugin#restart-claude-code) Restart Claude Code After installation, restart Claude Code to load the plugin’s commands and hooks. [​](https://beads.gascity.com/integrations/claude-code-plugin#quick-start) Quick Start ----------------------------------------------------------------------------------------- # Initialize beads in your project /beads:init # Create your first issue /beads:create "Set up project structure" feature 1 # See what's ready to work on /beads:ready # Show full workflow guide /beads:workflow [​](https://beads.gascity.com/integrations/claude-code-plugin#available-commands) Available Commands ------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/claude-code-plugin#version-management) Version Management * **`/beads:version`** - Check bd CLI and plugin versions ### [​](https://beads.gascity.com/integrations/claude-code-plugin#core-workflow-commands) Core Workflow Commands * **`/beads:ready`** - Find tasks with no blockers, ready to work on * **`/beads:create [title] [type] [priority]`** - Create a new issue interactively * **`/beads:show [issue-id]`** - Show detailed information about an issue * **`/beads:update [issue-id] [status]`** - Update issue status or other fields * **`/beads:close [issue-id] [reason]`** - Close a completed issue ### [​](https://beads.gascity.com/integrations/claude-code-plugin#project-management) Project Management * **`/beads:init`** - Initialize beads in the current project * **`/beads:workflow`** - Show the AI-supervised issue workflow guide * **`/beads:stats`** - Show project statistics and progress ### [​](https://beads.gascity.com/integrations/claude-code-plugin#agents) Agents * **`@task-agent`** - Autonomous agent that finds and completes ready tasks [​](https://beads.gascity.com/integrations/claude-code-plugin#mcp-tools) MCP Tools ------------------------------------------------------------------------------------- The plugin does not bundle an MCP server — it works through the bd CLI, which Claude Code drives directly (lower token overhead than MCP tool schemas). If you want MCP tools as well — for example in MCP-only surfaces — configure the standalone `beads-mcp` server alongside the plugin; see [MCP Server](https://beads.gascity.com/integrations/mcp-server) for its install options and full tool catalog. [​](https://beads.gascity.com/integrations/claude-code-plugin#workflow) Workflow ----------------------------------------------------------------------------------- The beads workflow is designed for AI agents but works great for humans too: 1. **Find ready work**: `/beads:ready` 2. **Claim your task**: `/beads:update <id> in_progress` 3. **Work on it**: Implement, test, document 4. **Discover new work**: Create issues for bugs/TODOs found during work 5. **Complete**: `/beads:close <id> "Done: <summary>"` 6. **Repeat**: Check for newly unblocked tasks [​](https://beads.gascity.com/integrations/claude-code-plugin#issue-types) Issue Types ----------------------------------------------------------------------------------------- * **`bug`** - Something broken that needs fixing * **`feature`** - New functionality * **`task`** - Work item (tests, docs, refactoring) * **`epic`** - Large feature composed of multiple issues * **`chore`** - Maintenance work (dependencies, tooling) [​](https://beads.gascity.com/integrations/claude-code-plugin#priority-levels) Priority Levels ------------------------------------------------------------------------------------------------- * **`0`** - Critical (security, data loss, broken builds) * **`1`** - High (major features, important bugs) * **`2`** - Medium (nice-to-have features, minor bugs) * **`3`** - Low (polish, optimization) * **`4`** - Backlog (future ideas) [​](https://beads.gascity.com/integrations/claude-code-plugin#dependency-types) Dependency Types --------------------------------------------------------------------------------------------------- * **`blocks`** - Hard dependency (issue X blocks issue Y from starting) * **`related`** - Soft relationship (issues are connected) * **`parent-child`** - Epic/subtask relationship * **`discovered-from`** - Track issues discovered during work Only `blocks` dependencies affect the ready work queue. [​](https://beads.gascity.com/integrations/claude-code-plugin#configuration) Configuration --------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/claude-code-plugin#auto-approval-configuration) Auto-Approval Configuration These settings apply if you configure the standalone [beads-mcp server](https://beads.gascity.com/integrations/mcp-server) alongside the plugin. By default, Claude Code asks for confirmation every time an MCP server wants to run a command. This is a security feature, but it can disrupt workflow during active development. **Available Options:** #### [​](https://beads.gascity.com/integrations/claude-code-plugin#1-auto-approve-all-beads-tools-recommended-for-trusted-projects) 1\. Auto-Approve All Beads Tools (Recommended for Trusted Projects) Add to your Claude Code `settings.json`: { "enabledMcpjsonServers": ["beads"] } This auto-approves all beads commands without prompting. #### [​](https://beads.gascity.com/integrations/claude-code-plugin#2-auto-approve-project-mcp-servers) 2\. Auto-Approve Project MCP Servers Add to your Claude Code `settings.json`: { "enableAllProjectMcpServers": true } This auto-approves all MCP servers defined in your project’s `.mcp.json` file. Useful when working across multiple projects with different MCP requirements. #### [​](https://beads.gascity.com/integrations/claude-code-plugin#3-manual-approval-default) 3\. Manual Approval (Default) No configuration needed. Claude Code will prompt for approval on each MCP tool invocation. **Security Trade-offs:** * **Manual approval (default)**: Maximum safety, but interrupts workflow frequently * **Server-level auto-approval**: Convenient for trusted projects, but allows any beads operation without confirmation * **Project-level auto-approval**: Good balance for multi-project workflows with project-specific trust levels **Limitation:** Claude Code doesn’t currently support per-tool approval granularity. You cannot auto-approve only read operations (like `bd ready`, `bd show`) while requiring confirmation for mutations (like `bd create`, `bd update`). It’s all-or-nothing at the server level. **Recommended Configuration:** For active development on trusted projects where you’re frequently using beads: { "enabledMcpjsonServers": ["beads"] } For more information, see the [Claude Code settings documentation](https://docs.claude.com/en/docs/claude-code/settings) . [​](https://beads.gascity.com/integrations/claude-code-plugin#examples) Examples ----------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/claude-code-plugin#basic-task-management) Basic Task Management # Create a high-priority bug /beads:create "Fix authentication" bug 1 # See ready work /beads:ready # Start working on bd-10 /beads:update bd-10 in_progress # Complete the task /beads:close bd-10 "Fixed auth token validation" ### [​](https://beads.gascity.com/integrations/claude-code-plugin#discovering-work-during-development) Discovering Work During Development # Working on bd-10, found a related bug /beads:create "Add rate limiting to API" feature 2 # Link it to current work bd dep add bd-11 bd-10 --type discovered-from # Close original task /beads:close bd-10 "Done, discovered bd-11 for rate limiting" ### [​](https://beads.gascity.com/integrations/claude-code-plugin#using-the-task-agent) Using the Task Agent # Let the agent find and complete ready work @task-agent # The agent will: # 1. Find ready work with `ready` tool # 2. Claim a task by updating status # 3. Execute the work # 4. Create issues for discoveries # 5. Close when complete # 6. Repeat [​](https://beads.gascity.com/integrations/claude-code-plugin#auto-sync-with-dolt) Auto-Sync with Dolt --------------------------------------------------------------------------------------------------------- Beads automatically commits changes to Dolt history after every write operation. This enables seamless collaboration: # Make changes bd create "Add feature" -p 1 # Changes are automatically committed to Dolt history # Sync with remotes when ready: bd dolt push # Pull changes from collaborators: bd dolt pull bd ready # Shows issues ready to work on (with fresh data) [​](https://beads.gascity.com/integrations/claude-code-plugin#updating) Updating ----------------------------------------------------------------------------------- The beads plugin has three components that may need updating: ### [​](https://beads.gascity.com/integrations/claude-code-plugin#1-plugin-updates) 1\. Plugin Updates Check for plugin updates: /plugin update beads Claude Code will pull the latest version from GitHub. After updating, **restart Claude Code** to apply plugin changes. ### [​](https://beads.gascity.com/integrations/claude-code-plugin#2-bd-cli-updates) 2\. bd CLI Updates The plugin requires the `bd` CLI to be installed. Update it separately: # Quick update curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash # Or with Go (server-mode only) CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest # Or with Go (embedded-capable) CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ### [​](https://beads.gascity.com/integrations/claude-code-plugin#3-version-compatibility) 3\. Version Compatibility The MCP server **automatically checks** bd CLI version on startup and will fail with a clear error if your version is too old. Check version compatibility manually: /beads:version This will show: * bd CLI version * Plugin version * MCP server status * Compatibility warnings if versions mismatch **Recommended update workflow:** 1. Check versions: `/beads:version` 2. Update bd CLI if needed (see above) 3. Update plugin: `/plugin update beads` 4. Restart Claude Code 5. Verify: `/beads:version` ### [​](https://beads.gascity.com/integrations/claude-code-plugin#version-numbering) Version Numbering Beads follows semantic versioning. The plugin version tracks the bd CLI version; major version bumps may introduce breaking changes — check CHANGELOG.md for release notes. [​](https://beads.gascity.com/integrations/claude-code-plugin#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/integrations/claude-code-plugin#plugin-not-appearing) Plugin not appearing 1. Check installation: `/plugin list` 2. Restart Claude Code 3. Verify `bd` is in PATH: `which bd` 4. Check uv is installed: `which uv` ### [​](https://beads.gascity.com/integrations/claude-code-plugin#mcp-server-not-connecting) MCP server not connecting 1. Check MCP server list: `/mcp` 2. Look for “beads” server with plugin indicator 3. Restart Claude Code to reload MCP servers 4. Check logs for errors ### [​](https://beads.gascity.com/integrations/claude-code-plugin#commands-not-working) Commands not working 1. Make sure you’re in a project with beads initialized: `/beads:init` 2. Check if database exists: `ls -la .beads/` 3. Try direct MCP tool access instead of slash commands 4. Check the beads CLI works: `bd --help` ### [​](https://beads.gascity.com/integrations/claude-code-plugin#mcp-tool-errors) MCP tool errors 1. Verify `bd` executable location: `BEADS_PATH` env var 2. Check `bd` works in terminal: `bd stats` 3. Review MCP server logs in Claude Code 4. Try reinitializing: `/beads:init` [​](https://beads.gascity.com/integrations/claude-code-plugin#learn-more) Learn More --------------------------------------------------------------------------------------- * **GitHub**: [https://github.com/gastownhall/beads](https://github.com/gastownhall/beads) * **Documentation**: See README.md in the repository * **Examples**: Check `examples/` directory for integration patterns * **MCP Server**: See `integrations/beads-mcp/` for server details [​](https://beads.gascity.com/integrations/claude-code-plugin#contributing) Contributing ------------------------------------------------------------------------------------------- Found a bug or have a feature idea? Create an issue in the beads repository! [​](https://beads.gascity.com/integrations/claude-code-plugin#license) License --------------------------------------------------------------------------------- MIT License - see LICENSE file in the repository. [Claude Code](https://beads.gascity.com/integrations/claude-code) [Codex](https://beads.gascity.com/integrations/codex) ⌘I --- # IDE Setup - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/getting-started/ide-setup#content-area) Configure your IDE or coding agent for optimal beads integration. Last reviewed: 2026-07-10 Freshness source: `cmd/bd/setup*.go` and `internal/recipes/`. [​](https://beads.gascity.com/getting-started/ide-setup#how-bd-setup-works) How `bd setup` Works --------------------------------------------------------------------------------------------------- The `bd setup` command uses a **recipe-based architecture**: recipes define where beads workflow instructions are written. Built-in recipes cover popular tools, and you can add custom recipes for any other tool (see Custom Recipes below). Integrations complement each other — you can install several at once. bd setup --list # Show all available recipes bd setup claude # Install an integration (claude, cursor, gemini, ...) bd setup claude --check # Verify installation bd setup claude --remove # Uninstall | Recipe | Files written | Details | | --- | --- | --- | | `claude` | `.claude/settings.json` (or `~/.claude/settings.json` with `--global`) + `CLAUDE.md` section | [Claude Code](https://beads.gascity.com/integrations/claude-code) | | `cursor` | `.cursor/rules/beads.mdc` | [Cursor](https://beads.gascity.com/integrations/cursor) | | `gemini` | `~/.gemini/settings.json` (or `.gemini/settings.json` with `--project`) + `GEMINI.md` section | [Gemini CLI](https://beads.gascity.com/integrations/gemini) | | `copilot` | `.copilot-plugin/plugin.json` + `.github/copilot-instructions.md` | [Copilot CLI](https://beads.gascity.com/integrations/copilot-cli) | | `codex` | `.agents/skills/beads/` + `AGENTS.md` section + `.codex/` hooks | [Codex](https://beads.gascity.com/integrations/codex) | | `factory` | `AGENTS.md` section | [Factory.ai Droid](https://beads.gascity.com/integrations/factory) | | `mux` | `AGENTS.md` section (+ `.mux/` layers with `--project`/`--global`) | [Mux](https://beads.gascity.com/integrations/mux) | | `opencode` | `AGENTS.md` section | [OpenCode](https://beads.gascity.com/integrations/opencode) | | `aider` | `.aider.conf.yml` + `.aider/BEADS.md` + `.aider/README.md` | [Aider](https://beads.gascity.com/integrations/aider) | | `junie` | `.junie/guidelines.md` + `.junie/mcp/mcp.json` | [Junie](https://beads.gascity.com/integrations/junie) | | `windsurf` | `.windsurf/rules/beads.md` | [Windsurf](https://beads.gascity.com/integrations/windsurf) | | `cody` | `.cody/rules/beads.md` | [Cody](https://beads.gascity.com/integrations/cody) | | `kilocode` | `.kilocode/rules/beads.md` | [Kilo Code](https://beads.gascity.com/integrations/kilocode) | `bd prime` is the single source of truth for operational workflow commands. Each integration’s instruction file either points to `bd prime` (hook-enabled agents) or carries the full command reference (AGENTS-first agents). Commit the instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, as applicable) to git so all team members and AI tools get the same instructions. ### [​](https://beads.gascity.com/getting-started/ide-setup#template-profiles) Template Profiles Each integration writes one of two **profiles** that control how much content goes into the tool’s instruction file (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `.github/copilot-instructions.md`): | Profile | Used by | Content | | --- | --- | --- | | `full` | Factory, Mux, OpenCode | Complete command reference, issue types, priorities, workflow | | `minimal` | Claude Code, GitHub Copilot CLI, Gemini CLI | Pointer to `bd prime`, quick reference only (~60% smaller) | Hook-enabled agents use the `minimal` profile because `bd prime` injects full context at session start. AGENTS-first agents use the `full` profile because their instruction file remains the primary integration surface. Codex is skill-based instead: it uses `.agents/skills/beads/SKILL.md`, with managed `AGENTS.md` guidance telling Codex when to use the skill. **Profile precedence:** if a file already has a `full` profile section and a `minimal` profile tool installs to the same file (for example via symlinks), the `full` profile is preserved to avoid information loss. ### [​](https://beads.gascity.com/getting-started/ide-setup#policy-profiles) Policy Profiles Template profiles control how much text gets installed. Policy profiles control what an agent is authorized to do at handoff: | Policy | Default scope | Commit/push guidance | | --- | --- | --- | | `conservative` | Standalone projects, unknown projects, and one-off assistance | Use `bd` for task tracking, then report changed files, validation, and proposed commands. Do not commit, push, or run Dolt remote sync without explicit user or orchestrator approval. | | `minimal` | Hook-first integrations where `bd prime` carries the detailed workflow | Same git authority as conservative; the installed file stays short and points to `bd prime`. | | `team-maintainer` | Repositories that explicitly delegate session close to agents | Agents may close beads, run quality gates, commit, run `bd dolt push`, and `git push` as part of routine work. Current “do not commit” or “do not push” instructions still override the profile. | The generated beads section and `bd prime` default to conservative git authority. Set the profile explicitly with the `agent.profile` config key or the `BD_AGENT_PROFILE` environment variable (values: `conservative`, `minimal`, `team-maintainer`; the env var takes precedence; an unrecognized value falls back to `conservative`): bd config set agent.profile team-maintainer # or, for a single session/process: BD_AGENT_PROFILE=team-maintainer bd prime `bd prime` layers this explicit knob on top of its per-branch git-authority checks (stealth mode, no git remote, ephemeral branch, `no-push`); those hard constraints still take precedence, and `team-maintainer` remains subordinate to any explicit “do not commit”/“do not push” instruction. Beads never infers team-maintainer authority merely because a remote exists — it must be set via this knob (or, for tools without config access, via top-level project instructions). ### [​](https://beads.gascity.com/getting-started/ide-setup#managed-sections) Managed Sections `bd setup factory`, `bd setup mux`, and `bd setup opencode` append a beads section to `AGENTS.md`, wrapped in `BEGIN/END BEADS INTEGRATION` HTML-comment markers. The begin marker carries version, profile, and hash metadata (e.g. `<!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:19cc25d9 -->`) so `--check` can report `missing`, `stale`, or `current`; legacy markers without metadata are auto-upgraded on the next install or update. Re-running setup updates the existing section in place (idempotent), and `--remove` deletes only the managed section — the rest of your `AGENTS.md` is untouched. `bd setup codex` uses its own marker pair (`BEGIN/END BEADS CODEX SETUP`). Running it alongside `bd setup factory` or `bd setup mux` against the same `AGENTS.md` leaves two managed sections side by side; each recipe’s `--check` inspects only its own section, and each `--remove` removes only its own section. One `AGENTS.md` works across many tools — Factory Droid, Mux, OpenCode, Cursor, Zed, Jules, and other AGENTS.md-aware assistants — so `bd setup factory` is a good starting point when your team mixes AI tools. [​](https://beads.gascity.com/getting-started/ide-setup#claude-code) Claude Code ----------------------------------------------------------------------------------- The recommended approach for Claude Code: bd setup claude # Project install: .claude/settings.json bd setup claude --global # Global install: ~/.claude/settings.json This installs: * **SessionStart hook** - Runs `bd prime --hook-json`, which wraps the workflow context in the JSON envelope Claude Code expects. SessionStart fires when a session starts, resumes, or clears, and again after context compaction — no separate compaction hook is needed. * **Minimal beads section in `CLAUDE.md`** - A pointer to `bd prime`, managed with hash/version markers for safe updates and `--check` freshness detection. If the [beads Claude Code plugin](https://beads.gascity.com/integrations/claude-code-plugin) is installed, hooks are plugin-managed and `bd setup claude` skips writing them, so `bd prime` doesn’t fire twice per session. **How it works:** 1. SessionStart hook runs `bd prime --hook-json` automatically 2. `bd prime` injects ~1-2k tokens of workflow context 3. You use `bd` CLI commands directly 4. Git hooks refresh exports and legacy fallbacks; Dolt remotes handle sync **Flags:** | Flag | Description | | --- | --- | | `--check` | Check both hooks and the managed `CLAUDE.md` beads section | | `--remove` | Remove beads hooks and the managed `CLAUDE.md` beads section | | `--global` | Install to `~/.claude/settings.json` instead of the project | | `--stealth` | Use `bd prime --stealth --hook-json` (flush only, no git operations) — useful in CI/CD where git operations might fail | Restart Claude Code after installation for the hooks to take effect. **Verify installation:** bd setup claude --check ### [​](https://beads.gascity.com/getting-started/ide-setup#manual-setup) Manual Setup If you prefer manual configuration, add the hook to your Claude Code settings: { "hooks": { "SessionStart": [\ {\ "matcher": "",\ "hooks": [\ { "type": "command", "command": "bd prime --hook-json" }\ ]\ }\ ] } } [​](https://beads.gascity.com/getting-started/ide-setup#cursor-ide) Cursor IDE --------------------------------------------------------------------------------- bd setup cursor # Always-applied rules file This creates `.cursor/rules/beads.mdc` with beads-aware rules that Cursor re-includes every turn. **Verify:** bd setup cursor --check See [Cursor](https://beads.gascity.com/integrations/cursor) for details. [​](https://beads.gascity.com/getting-started/ide-setup#gemini-cli) Gemini CLI --------------------------------------------------------------------------------- bd setup gemini # Global hooks in ~/.gemini/settings.json bd setup gemini --project # Project hooks in .gemini/settings.json This installs a SessionStart hook running `bd prime --hook-json` — Gemini requires hook stdout to be valid JSON, and `--hook-json` wraps the markdown in the required envelope — plus a minimal beads section in `GEMINI.md`. `--stealth` works the same as for Claude Code; `--check` and `--remove` cover both the hooks and the managed `GEMINI.md` section. **Verify:** bd setup gemini --check See [Gemini CLI](https://beads.gascity.com/integrations/gemini) for details. [​](https://beads.gascity.com/getting-started/ide-setup#aider) Aider ----------------------------------------------------------------------- # Setup Aider integration bd setup aider This writes three files: | File | Purpose | | --- | --- | | `.aider.conf.yml` | Points Aider to read the instructions file | | `.aider/BEADS.md` | Workflow instructions for the AI | | `.aider/README.md` | Quick reference for humans | Aider is human-in-the-loop: the AI **suggests** `bd` commands, and you run them with `/run`. See [Aider](https://beads.gascity.com/integrations/aider) for the workflow. **Verify:** bd setup aider --check [​](https://beads.gascity.com/getting-started/ide-setup#agents-md-tools-factory-mux-opencode-codex) AGENTS.md Tools: Factory, Mux, OpenCode, Codex ----------------------------------------------------------------------------------------------------------------------------------------------------- bd setup factory # Factory.ai Droid — AGENTS.md section bd setup mux # Mux — AGENTS.md section (+ --project/--global layers) bd setup opencode # OpenCode — AGENTS.md section bd setup codex # Codex — beads skill + AGENTS.md guidance + native hooks These create or update a managed section in `AGENTS.md` (see Managed Sections above). `bd init` runs the project Codex setup automatically unless `--skip-agents` or `--stealth` is used. In worktree, shared, or `BEADS_DIR` setups, use `bd where` to confirm the resolved workspace — these integrations do not require a local `./.beads`. Restart the tool after setup if it is already running. Details: [Factory.ai Droid](https://beads.gascity.com/integrations/factory) , [Mux](https://beads.gascity.com/integrations/mux) , [OpenCode](https://beads.gascity.com/integrations/opencode) , [Codex](https://beads.gascity.com/integrations/codex) . [​](https://beads.gascity.com/getting-started/ide-setup#github-copilot) GitHub Copilot ----------------------------------------------------------------------------------------- **Copilot CLI:** bd setup copilot This installs a native Copilot CLI plugin manifest (`.copilot-plugin/plugin.json`, which registers `bd prime` hooks) and repository instructions (`.github/copilot-instructions.md`). See [Copilot CLI](https://beads.gascity.com/integrations/copilot-cli) . **For VS Code with GitHub Copilot**, use the MCP server: # Install MCP server uv tool install beads-mcp Create `.vscode/mcp.json` in your project: { "servers": { "beads": { "command": "beads-mcp" } } } **For all projects:** Add to VS Code user-level MCP config: | Platform | Path | | --- | --- | | macOS | `~/Library/Application Support/Code/User/mcp.json` | | Linux | `~/.config/Code/User/mcp.json` | | Windows | `%APPDATA%\Code\User\mcp.json` | { "servers": { "beads": { "command": "beads-mcp", "args": [] } } } Initialize beads and reload VS Code: bd init --quiet See [GitHub Copilot Integration](https://beads.gascity.com/integrations/github-copilot) for detailed setup. [​](https://beads.gascity.com/getting-started/ide-setup#context-injection-with-bd-prime) Context Injection with `bd prime` ----------------------------------------------------------------------------------------------------------------------------- All integrations use `bd prime` to inject context: bd prime This outputs a compact (~1-2k tokens) workflow reference including: * Available commands * Current project status * Workflow patterns * Best practices * Persistent memories from `bd remember` `bd prime` prints memories near the top and starts with a truncation warning. If your host stores the full hook output in a file and only shows a preview, have the agent read the full file before continuing. In hook contexts, `bd prime --hook-json` wraps the output in the SessionStart JSON envelope (Claude Code, Gemini CLI, Codex). For memory-only hooks: bd prime --memories-only **Why context efficiency matters:** * Compute cost scales with tokens * Latency increases with context size * Models attend better to smaller, focused contexts [​](https://beads.gascity.com/getting-started/ide-setup#mcp-server-alternative) MCP Server (Alternative) ----------------------------------------------------------------------------------------------------------- For MCP-only environments (Claude Desktop, no shell access): # Install MCP server pip install beads-mcp Add to Claude Desktop config: { "mcpServers": { "beads": { "command": "beads-mcp" } } } **Trade-offs:** * Works in MCP-only environments * Higher context overhead (10-50k tokens for tool schemas) * Additional latency from MCP protocol See [MCP Server](https://beads.gascity.com/integrations/mcp-server) for detailed configuration. [​](https://beads.gascity.com/getting-started/ide-setup#custom-recipes) Custom Recipes ----------------------------------------------------------------------------------------- For editors or tools without a built-in recipe: bd setup --add myeditor .myeditor/rules.md # Save a custom recipe bd setup myeditor # Install it bd setup myeditor --check # Check it bd setup myeditor --remove # Remove it Custom recipes are stored in `.beads/recipes.toml` (adding one requires an active beads workspace): [recipes.myeditor] name = "myeditor" path = ".myeditor/rules.md" type = "file" For a one-off install without saving a recipe, write the template to any path — or inspect it first: bd setup -o .my-custom-location/beads.md bd setup --print **Recipe types:** | Type | Description | Used by | | --- | --- | --- | | `file` | Write the template to a single file | windsurf, cody, kilocode | | `hooks` | Modify JSON settings to add hooks | claude, gemini | | `section` | Inject a marked section into an existing file | factory, codex, mux, opencode | | `multifile` | Write multiple files | aider, copilot, junie | Custom recipes added via `--add` are always type `file`. [​](https://beads.gascity.com/getting-started/ide-setup#git-hooks) Git Hooks ------------------------------------------------------------------------------- Ensure git hooks are installed for export refresh and legacy fallback behavior: bd hooks install This installs: * **pre-commit** - Runs chained hooks before commit * **post-merge** - Runs chained hooks after pull/merge * **pre-push** - Runs chained hooks before push * **post-checkout** - Runs chained hooks after branch checkout * **prepare-commit-msg** - Adds agent identity trailers for forensics **Check hook status:** bd hooks list # Installed, outdated, or missing bd info # Shows warnings if hooks are outdated [​](https://beads.gascity.com/getting-started/ide-setup#verifying-your-setup) Verifying Your Setup ----------------------------------------------------------------------------------------------------- Run a complete health check: # Check version bd version # Check project health (includes integration status) bd doctor # Check git hooks bd hooks list # Check editor integration bd setup claude --check # or cursor, gemini, aider, ... **Troubleshooting:** * _Hooks not working?_ Restart your AI tool after installation, then re-run `bd setup claude --check` (or your tool’s recipe) and check `bd doctor` output for integration status. * _Context not appearing?_ Make sure `bd prime` works standalone; if it fails, fix the underlying beads issue first. [Quick Start](https://beads.gascity.com/getting-started/quickstart) [Sync Setup Guide](https://beads.gascity.com/getting-started/sync-setup) ⌘I --- # How Beads Works - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/core-concepts#content-area) Coding agents lose their memory every time a session ends. Markdown plans rot, TODO comments scatter, and a crashed agent takes its context with it. Beads replaces that with a **persistent, structured work graph**: every unit of work is a **bead** (an issue) in a version-controlled database, connected by dependencies, and `bd ready` computes exactly what can be worked on right now. Work survives the agent; the next session picks up where the last one died. The loop above is the whole product in miniature: creating and closing beads reshapes the graph, and the graph — not a human dispatcher — decides what is workable next. [​](https://beads.gascity.com/core-concepts#beads-and-dependencies) Beads and dependencies --------------------------------------------------------------------------------------------- A **bead** is one tracked unit of work: a hash ID (`bd-a1b2`), a title, a type (`bug`, `task`, `feature`, `epic`, `chore`, and friends — see [`bd types`](https://beads.gascity.com/cli-reference/types) ), a priority (`0` critical → `4` backlog), and a status moving `open` → `in_progress` → `closed`. “Bead” and “issue” name the same thing; the CLI says issue, the product says bead. **Dependencies** connect beads into a graph. Two edge types shape what agents may work on: | Type | Meaning | Affects ready work | | --- | --- | --- | | `blocks` | hard ordering — the blocker must close first | **yes** | | `parent-child` | epic/subtask structure | **indirectly** — a blocked parent blocks its children | | `discovered-from` | provenance — found while working on the parent | no | | `related` | soft association | no | Workflow steps add two more blocking types (`conditional-blocks`, `waits-for`) — see [Molecules](https://beads.gascity.com/workflows/molecules) . Richer knowledge-graph edges (`relates-to`, `duplicates`, `supersedes`, `replies-to`) are covered in [Graph Links](https://beads.gascity.com/core-concepts/graph-links) . [​](https://beads.gascity.com/core-concepts#ready-work-%E2%80%94-what-bd-ready-computes) Ready work — what `bd ready` computes --------------------------------------------------------------------------------------------------------------------------------- **Ready work** is the claimable frontier of the graph: open beads with no open blockers, excluding anything in progress, blocked, deferred, or held by a gate. Agents never scan the whole tracker; they ask for the frontier and claim atomically. Here `bd ready` returns `bd-a1b2` and `bd-77aa` — everything else is either closed or waiting on an open blocker. Closing `bd-a1b2` makes `bd-c3d4` ready; nothing needs re-planning. bd ready --json # the claimable frontier, machine-readable bd ready --claim --json # atomically claim the first match [​](https://beads.gascity.com/core-concepts#hash-ids-%E2%80%94-why-agents-never-collide) Hash IDs — why agents never collide ------------------------------------------------------------------------------------------------------------------------------- IDs like `bd-a1b2` are content-derived hashes (of title, description, creator, and creation time, plus a collision nonce), not sequence numbers. Two agents (or two branches) creating beads at the same time cannot mint the same ID, so merges never renumber work. The hash length extends automatically on collision and scales with database size — see [Hash IDs](https://beads.gascity.com/core-concepts/hash-ids) and [Adaptive ID Length](https://beads.gascity.com/core-concepts/adaptive-ids) . [​](https://beads.gascity.com/core-concepts#workflows-%E2%80%94-formula-%E2%86%92-proto-%E2%86%92-molecule) Workflows — formula → proto → molecule ----------------------------------------------------------------------------------------------------------------------------------------------------- Repeatable multi-step work is declared once and stamped out on demand: * A **formula** is the source: a TOML/JSON file defining a DAG of steps — see [Formulas](https://beads.gascity.com/workflows/formulas) . * Cooking compiles it into a **proto**: a template epic with `{{variables}}`, not yet live work. * Pouring instantiates a **molecule**: real beads whose steps flow through `bd ready` like any other work — see [Molecules](https://beads.gascity.com/workflows/molecules) . * A **wisp** is the same instantiation with an ephemeral lifecycle — gone at the next `bd purge` — see [Wisps](https://beads.gascity.com/workflows/wisps) . * A **gate** parks a step until something external happens: a human sign-off, a timer, or a GitHub run or PR — see [Gates](https://beads.gascity.com/workflows/gates) . [​](https://beads.gascity.com/core-concepts#sync-%E2%80%94-how-work-moves-between-machines) Sync — how work moves between machines ------------------------------------------------------------------------------------------------------------------------------------- Beads stores everything in [Dolt](https://github.com/dolthub/dolt) , a version-controlled SQL database. Every write auto-commits to Dolt history; sync is native push/pull, piggybacking on your existing git remote under a separate ref — no server to run. `.beads/issues.jsonl` is a passive export for viewers and interchange — it is not the database, not the sync protocol, and not a backup. The full model (and its anti-patterns) is in [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts) ; **federation** — peer-to-peer sharing across repos and organizations — is in [Federation](https://beads.gascity.com/multi-agent/federation) . [​](https://beads.gascity.com/core-concepts#storage-modes) Storage modes --------------------------------------------------------------------------- | Mode | Command | Data lives at | Writers | | --- | --- | --- | --- | | **Embedded** (default) | `bd init` | `.beads/embeddeddolt/` | one (file-locked) | | **Server** | `bd init --server` | `.beads/dolt/` | many concurrent | Embedded runs Dolt in-process and is right for almost everyone; server mode connects to an external `dolt sql-server` for multi-writer setups — see the [Dolt backend](https://beads.gascity.com/architecture/dolt) and the [architecture overview](https://beads.gascity.com/architecture/index) . [​](https://beads.gascity.com/core-concepts#where-to-go-next) Where to go next --------------------------------------------------------------------------------- * [Quick Start](https://beads.gascity.com/getting-started/quickstart) — install, create, claim, and close your first beads. * [Issues & Dependencies](https://beads.gascity.com/core-concepts/issues) — field-level detail on beads and their relationships. * [Workflows](https://beads.gascity.com/workflows/index) — molecules, formulas, gates, and wisps in depth. * [Multi-Agent](https://beads.gascity.com/multi-agent/index) — routing, coordination, and federation for fleets of agents. [Upgrading](https://beads.gascity.com/getting-started/upgrading) [Issues & Dependencies](https://beads.gascity.com/core-concepts/issues) ⌘I --- # Dependencies and Gates - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/core-concepts/dependencies#content-area) Beads includes a full dependency system for ordering work and a gate system for bridging external conditions (PR merges, CI runs, timers) into the dependency graph. [​](https://beads.gascity.com/core-concepts/dependencies#adding-dependencies) Adding Dependencies ---------------------------------------------------------------------------------------------------- # issue-2 depends on issue-1 (issue-1 blocks issue-2) bd dep add issue-2 issue-1 # Shorthand: issue-1 blocks issue-2 bd dep issue-1 --blocks issue-2 # Alternative flags (equivalent) bd dep add issue-2 --blocked-by issue-1 bd dep add issue-2 --depends-on issue-1 When issue-1 is open, issue-2 won’t appear in `bd ready`. Once issue-1 is closed, issue-2 unblocks automatically. [​](https://beads.gascity.com/core-concepts/dependencies#removing-dependencies) Removing Dependencies -------------------------------------------------------------------------------------------------------- bd dep remove issue-2 issue-1 bd dep rm issue-2 issue-1 # alias [​](https://beads.gascity.com/core-concepts/dependencies#dependency-types) Dependency Types ---------------------------------------------------------------------------------------------- Dependencies have a type that determines whether they block work. **Blocking types** (affect `bd ready`): | Type | Meaning | Example | | --- | --- | --- | | `blocks` (default) | B cannot start until A closes | Task ordering | | `parent-child` | Children blocked when parent blocked | Epic hierarchies | | `conditional-blocks` | B runs only if A fails | Error handling paths | | `waits-for` | B waits for all of A’s children | Fanout aggregation | **Non-blocking types** (graph annotations only): | Type | Meaning | | --- | --- | | `related` | Informational link | | `tracks` | Tracks progress of another issue | | `discovered-from` | Found during work on another issue | | `caused-by` | Root cause link | | `validates` | Test or verification link | | `supersedes` | Replaces another issue | Specify with `--type`: bd dep add issue-2 issue-1 --type tracks bd dep add issue-2 issue-1 --type caused-by [​](https://beads.gascity.com/core-concepts/dependencies#finding-ready-work) Finding Ready Work -------------------------------------------------------------------------------------------------- `bd ready` shows issues with no open blocking dependencies: bd ready Output: 📋 Ready work (1 issues with no blockers): 1. [P1] bd-a1b2: Set up database An issue is ready when ALL of its blocking dependencies are closed. # Filter ready work bd ready --priority 1 # By priority bd ready --label backend # By label bd ready --assignee alice # By assignee bd ready --unassigned # Unassigned only bd ready --type task # By issue type bd ready --sort oldest # Oldest first [​](https://beads.gascity.com/core-concepts/dependencies#viewing-blocked-issues) Viewing Blocked Issues ---------------------------------------------------------------------------------------------------------- bd blocked Shows every blocked issue and what blocks it. Use after closing an issue to see what just unblocked. [​](https://beads.gascity.com/core-concepts/dependencies#visualizing-dependencies) Visualizing Dependencies -------------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/dependencies#dependency-tree) Dependency Tree bd dep tree issue-id # What does this issue depend on? bd dep tree issue-id --direction=up # What depends on this issue? bd dep tree issue-id --direction=both # Both directions bd dep tree issue-id --status=open # Only open issues bd dep tree issue-id --max-depth=3 # Limit depth bd dep tree issue-id --format=mermaid # Mermaid.js output ### [​](https://beads.gascity.com/core-concepts/dependencies#dependency-graph) Dependency Graph bd graph issue-id # Single issue DAG bd graph --all # All open issues # Output formats bd graph --compact issue-id # One line per issue bd graph --box issue-id # ASCII boxes with layers bd graph --dot issue-id | dot -Tsvg > graph.svg # Graphviz bd graph --html issue-id > graph.html # Interactive D3.js The graph organizes issues into layers: * **Layer 0**: No dependencies (can start immediately) * **Layer 1**: Depends on layer 0 * **Higher layers**: Depend on lower layers * **Same layer**: Can run in parallel ### [​](https://beads.gascity.com/core-concepts/dependencies#dependency-list) Dependency List bd dep list issue-id # What does this depend on? bd dep list issue-id --direction=up # What depends on this? bd dep list issue-id --type=tracks # Filter by type ### [​](https://beads.gascity.com/core-concepts/dependencies#cycle-detection) Cycle Detection bd dep cycles Beads also rejects cycles at write time — `bd dep add` checks for cycles before committing. [​](https://beads.gascity.com/core-concepts/dependencies#cross-repo-dependencies) Cross-Repo Dependencies ------------------------------------------------------------------------------------------------------------ Dependencies can reference issues in other beads rigs: bd dep add local-issue external:other-project:remote-issue External dependencies always block. When the remote issue closes, `bd ready` reflects the change (checked at query time). [​](https://beads.gascity.com/core-concepts/dependencies#gates) Gates ------------------------------------------------------------------------ Gates are special issues that block dependent work until an external condition is met. They bridge the gap between beads (which tracks work) and external systems (which track code, CI, or time). ### [​](https://beads.gascity.com/core-concepts/dependencies#the-problem-gates-solve) The Problem Gates Solve When you use Dolt (server or embedded), issue state is decoupled from code state. Closing a beads issue means “work is done” but the code may still be on a feature branch, waiting for PR review: issue-1: closed in beads (work done) PR #42: open on GitHub (code not yet on main) issue-2: blocked by issue-1 (should it start?) With file-based storage (JSONL), issue updates land atomically with code in the same commit. With Dolt, they don’t. Gates solve this by making the dependency wait for the external condition — not just the beads issue status. ### [​](https://beads.gascity.com/core-concepts/dependencies#gate-types) Gate Types | Type | Condition | Auto-Resolution | | --- | --- | --- | | `gh:pr` | PR merged | `gh pr view` returns MERGED | | `gh:run` | CI passes | `gh run view` returns completed + success | | `timer` | Time elapsed | Current time exceeds timeout | | `bead` | Cross-rig issue closed | Remote bead status checked | | `human` | Manual approval | `bd gate resolve <id>` | ### [​](https://beads.gascity.com/core-concepts/dependencies#creating-gates) Creating Gates # Wait for PR #42 to merge bd create --type=gate --title="Wait for PR #42" \ --await-type=gh:pr --await-id=42 # Wait for CI run bd create --type=gate --title="Wait for CI" \ --await-type=gh:run --await-id=12345 # Wait 30 minutes bd create --type=gate --title="Cooldown" \ --await-type=timer --await-id=30m # Wait for a cross-rig bead to close bd create --type=gate --title="Wait for upstream fix" \ --await-type=bead --await-id=other-rig:issue-id # Manual approval gate bd create --type=gate --title="Deploy approval" ### [​](https://beads.gascity.com/core-concepts/dependencies#wiring-gates-into-dependencies) Wiring Gates into Dependencies A gate is an issue. Wire it into the dependency graph like any other: # issue-2 waits for the gate (which waits for PR #42) bd dep add issue-2 <gate-id> ### [​](https://beads.gascity.com/core-concepts/dependencies#checking-gates) Checking Gates `bd gate check` evaluates all open gates and closes resolved ones: bd gate check # Check all gates bd gate check --type=gh:pr # Only PR gates bd gate check --type=gh:run # Only CI gates bd gate check --type=timer # Only timers bd gate check --dry-run # Preview without changes bd gate check --escalate # Escalate failed gates Escalation marks gates whose conditions failed (e.g., PR closed without merge, CI run failed) so they surface for attention. ### [​](https://beads.gascity.com/core-concepts/dependencies#listing-and-inspecting-gates) Listing and Inspecting Gates bd gate list # Open gates bd gate list --all # Including closed bd gate show <gate-id> # Full details ### [​](https://beads.gascity.com/core-concepts/dependencies#manual-resolution) Manual Resolution For `human` gates or overrides: bd gate resolve <gate-id> --reason "Approved by team lead" ### [​](https://beads.gascity.com/core-concepts/dependencies#discovering-ci-run-ids) Discovering CI Run IDs When you create a `gh:run` gate before the run starts, `bd gate discover` matches gates to GitHub Actions runs using heuristics (commit SHA, branch, timing): bd gate discover # Auto-match gates to runs bd gate discover --dry-run # Preview matches bd gate discover --branch main # Filter by branch ### [​](https://beads.gascity.com/core-concepts/dependencies#automating-gate-checks) Automating Gate Checks Run `bd gate check` periodically to auto-close resolved gates: * **CI step**: Add to your GitHub Actions workflow * **Cron**: `*/5 * * * * cd /path/to/repo && bd gate check` * **Agent hook**: Run at session start or after PR operations [​](https://beads.gascity.com/core-concepts/dependencies#recipes) Recipes ---------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/dependencies#pr-merge-gate-common) PR Merge Gate (Common) Agent A finishes work, opens PR, creates a gate so Agent B waits for merge: # Agent A bd update issue-1 --status=in_progress # ... write code, open PR #42 ... bd create --type=gate --title="Wait for PR #42" \ --await-type=gh:pr --await-id=42 bd dep add issue-2 <gate-id> bd close issue-1 # Agent B bd ready # issue-2 not shown (gate open) # ... PR #42 merges ... bd gate check # gate closes bd ready # issue-2 appears ### [​](https://beads.gascity.com/core-concepts/dependencies#ci-gate-before-deploy) CI Gate Before Deploy bd create --type=gate --title="CI green on main" \ --await-type=gh:run --await-id=<run-id> bd dep add deploy-task <gate-id> ### [​](https://beads.gascity.com/core-concepts/dependencies#epic-with-ordered-phases) Epic with Ordered Phases bd create "Auth System" -t epic bd create "Design" --parent <epic> bd create "Implement" --parent <epic> bd create "Test" --parent <epic> bd dep add <implement> <design> bd dep add <test> <implement> bd dep tree <epic> bd ready # Only "Design" is ready [​](https://beads.gascity.com/core-concepts/dependencies#see-also) See Also ------------------------------------------------------------------------------ * [Quick Start](https://beads.gascity.com/getting-started/quickstart) — First steps with dependencies * [Molecules](https://beads.gascity.com/workflows/molecules) — Molecule workflows using gates and dependencies * [Agent Coordination](https://beads.gascity.com/multi-agent/coordination) — Cross-repo dependency patterns * [Dolt Backend for Beads](https://beads.gascity.com/architecture/dolt) — Dolt backend configuration * [CLI Reference](https://beads.gascity.com/cli-reference/index) — Full command reference [Issues & Dependencies](https://beads.gascity.com/core-concepts/issues) [Hash-based IDs](https://beads.gascity.com/core-concepts/hash-ids) ⌘I --- # How Beads Works - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/core-concepts/index#content-area) Coding agents lose their memory every time a session ends. Markdown plans rot, TODO comments scatter, and a crashed agent takes its context with it. Beads replaces that with a **persistent, structured work graph**: every unit of work is a **bead** (an issue) in a version-controlled database, connected by dependencies, and `bd ready` computes exactly what can be worked on right now. Work survives the agent; the next session picks up where the last one died. The loop above is the whole product in miniature: creating and closing beads reshapes the graph, and the graph — not a human dispatcher — decides what is workable next. [​](https://beads.gascity.com/core-concepts/index#beads-and-dependencies) Beads and dependencies --------------------------------------------------------------------------------------------------- A **bead** is one tracked unit of work: a hash ID (`bd-a1b2`), a title, a type (`bug`, `task`, `feature`, `epic`, `chore`, and friends — see [`bd types`](https://beads.gascity.com/cli-reference/types) ), a priority (`0` critical → `4` backlog), and a status moving `open` → `in_progress` → `closed`. “Bead” and “issue” name the same thing; the CLI says issue, the product says bead. **Dependencies** connect beads into a graph. Two edge types shape what agents may work on: | Type | Meaning | Affects ready work | | --- | --- | --- | | `blocks` | hard ordering — the blocker must close first | **yes** | | `parent-child` | epic/subtask structure | **indirectly** — a blocked parent blocks its children | | `discovered-from` | provenance — found while working on the parent | no | | `related` | soft association | no | Workflow steps add two more blocking types (`conditional-blocks`, `waits-for`) — see [Molecules](https://beads.gascity.com/workflows/molecules) . Richer knowledge-graph edges (`relates-to`, `duplicates`, `supersedes`, `replies-to`) are covered in [Graph Links](https://beads.gascity.com/core-concepts/graph-links) . [​](https://beads.gascity.com/core-concepts/index#ready-work-%E2%80%94-what-bd-ready-computes) Ready work — what `bd ready` computes --------------------------------------------------------------------------------------------------------------------------------------- **Ready work** is the claimable frontier of the graph: open beads with no open blockers, excluding anything in progress, blocked, deferred, or held by a gate. Agents never scan the whole tracker; they ask for the frontier and claim atomically. Here `bd ready` returns `bd-a1b2` and `bd-77aa` — everything else is either closed or waiting on an open blocker. Closing `bd-a1b2` makes `bd-c3d4` ready; nothing needs re-planning. bd ready --json # the claimable frontier, machine-readable bd ready --claim --json # atomically claim the first match [​](https://beads.gascity.com/core-concepts/index#hash-ids-%E2%80%94-why-agents-never-collide) Hash IDs — why agents never collide ------------------------------------------------------------------------------------------------------------------------------------- IDs like `bd-a1b2` are content-derived hashes (of title, description, creator, and creation time, plus a collision nonce), not sequence numbers. Two agents (or two branches) creating beads at the same time cannot mint the same ID, so merges never renumber work. The hash length extends automatically on collision and scales with database size — see [Hash IDs](https://beads.gascity.com/core-concepts/hash-ids) and [Adaptive ID Length](https://beads.gascity.com/core-concepts/adaptive-ids) . [​](https://beads.gascity.com/core-concepts/index#workflows-%E2%80%94-formula-%E2%86%92-proto-%E2%86%92-molecule) Workflows — formula → proto → molecule ----------------------------------------------------------------------------------------------------------------------------------------------------------- Repeatable multi-step work is declared once and stamped out on demand: * A **formula** is the source: a TOML/JSON file defining a DAG of steps — see [Formulas](https://beads.gascity.com/workflows/formulas) . * Cooking compiles it into a **proto**: a template epic with `{{variables}}`, not yet live work. * Pouring instantiates a **molecule**: real beads whose steps flow through `bd ready` like any other work — see [Molecules](https://beads.gascity.com/workflows/molecules) . * A **wisp** is the same instantiation with an ephemeral lifecycle — gone at the next `bd purge` — see [Wisps](https://beads.gascity.com/workflows/wisps) . * A **gate** parks a step until something external happens: a human sign-off, a timer, or a GitHub run or PR — see [Gates](https://beads.gascity.com/workflows/gates) . [​](https://beads.gascity.com/core-concepts/index#sync-%E2%80%94-how-work-moves-between-machines) Sync — how work moves between machines ------------------------------------------------------------------------------------------------------------------------------------------- Beads stores everything in [Dolt](https://github.com/dolthub/dolt) , a version-controlled SQL database. Every write auto-commits to Dolt history; sync is native push/pull, piggybacking on your existing git remote under a separate ref — no server to run. `.beads/issues.jsonl` is a passive export for viewers and interchange — it is not the database, not the sync protocol, and not a backup. The full model (and its anti-patterns) is in [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts) ; **federation** — peer-to-peer sharing across repos and organizations — is in [Federation](https://beads.gascity.com/multi-agent/federation) . [​](https://beads.gascity.com/core-concepts/index#storage-modes) Storage modes --------------------------------------------------------------------------------- | Mode | Command | Data lives at | Writers | | --- | --- | --- | --- | | **Embedded** (default) | `bd init` | `.beads/embeddeddolt/` | one (file-locked) | | **Server** | `bd init --server` | `.beads/dolt/` | many concurrent | Embedded runs Dolt in-process and is right for almost everyone; server mode connects to an external `dolt sql-server` for multi-writer setups — see the [Dolt backend](https://beads.gascity.com/architecture/dolt) and the [architecture overview](https://beads.gascity.com/architecture/index) . [​](https://beads.gascity.com/core-concepts/index#where-to-go-next) Where to go next --------------------------------------------------------------------------------------- * [Quick Start](https://beads.gascity.com/getting-started/quickstart) — install, create, claim, and close your first beads. * [Issues & Dependencies](https://beads.gascity.com/core-concepts/issues) — field-level detail on beads and their relationships. * [Workflows](https://beads.gascity.com/workflows/index) — molecules, formulas, gates, and wisps in depth. * [Multi-Agent](https://beads.gascity.com/multi-agent/index) — routing, coordination, and federation for fleets of agents. [Upgrading](https://beads.gascity.com/getting-started/upgrading) [Issues & Dependencies](https://beads.gascity.com/core-concepts/issues) ⌘I --- # Quick Start - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/getting-started/quickstart#content-area) Get up and running with Beads in a few minutes. [​](https://beads.gascity.com/getting-started/quickstart#why-beads) Why Beads? --------------------------------------------------------------------------------- Flat issue trackers (GitHub Issues, Jira, etc.) show you a list of open items. You pick one. But if that item depends on something else that isn’t done yet, you’ve wasted time. Multiply this across a team of AI agents and humans, and you get thrashing. Beads tracks **dependencies between issues** and computes a **ready queue** — only items with no active blockers appear. Here’s the difference: **Flat tracker (GitHub Issues):** Open issues: Set up database, Create API, Add authentication → An agent picks "Add authentication" and gets stuck immediately **Beads:** $ bd ready 1. [P1] [task] bd-1: Set up database $ bd ready --explain --json | jq '.blocked[0]' { "id": "bd-3", "title": "Add authentication", "blocked_by": [{"id": "bd-2", "title": "Create API", "status": "open"}] } The agent picks the right task every time. No wasted cycles. [​](https://beads.gascity.com/getting-started/quickstart#installation) Installation -------------------------------------------------------------------------------------- Install `bd` using [the full installation guide](https://beads.gascity.com/getting-started/installation) (Homebrew, install script, npm, or `go install`). **Developing in a clone of this repository:** use `make install` so the binary gets correct build metadata and a consistent install path. Avoid ad-hoc `go build` / `go install` without the Makefile unless you know what you are doing — see the repository `README` and `AGENTS.md`. bd --help [​](https://beads.gascity.com/getting-started/quickstart#initialize) Initialize ---------------------------------------------------------------------------------- First time in a repository: # Basic setup (prompts for contributor mode) bd init # For AI agents (non-interactive) bd init --quiet # OSS contributor (fork workflow with separate planning repo) bd init --contributor # Team member (branch workflow for collaboration) bd init --team # Protected main branch (GitHub/GitLab) # Note: Dolt stores data under refs/dolt/data, separate from # Git refs, so no --branch flag is needed. The wizard will: * Create `.beads/` directory and embedded Dolt database * **Prompt for your role** (maintainer or contributor) unless a flag is provided * Import existing issues from git (if any) * Install git hooks (skip with `--skip-hooks`) Notes: * Dolt is the default (and only) storage backend. Data is stored in `.beads/embeddeddolt/`. * By default, Dolt runs in **embedded mode** (in-process, no server needed). * For multi-writer setups, use `bd init --server` to connect to a `dolt sql-server` instead. * To import issues from an older installation, run `bd init --from-jsonl`. ### [​](https://beads.gascity.com/getting-started/quickstart#role-configuration) Role configuration During `bd init`, you’ll be asked: “Contributing to someone else’s repo? \[y/N\]” * Answer **Y** if you’re contributing to a fork (runs contributor wizard) * Answer **N** if you’re the maintainer or have push access This sets `git config beads.role` which determines how beads routes issues: | Role | Use case | Issue storage | | --- | --- | --- | | `maintainer` | Repo owner, team with push access | In-repo `.beads/` | | `contributor` | Fork contributor, OSS contributor | Separate planning repo | You can also configure manually: # Set as contributor git config beads.role contributor # Set as maintainer git config beads.role maintainer # Check current role git config --get beads.role **Note:** If `beads.role` is not configured, beads falls back to URL-based detection (deprecated). Run `bd doctor` to check configuration status. [​](https://beads.gascity.com/getting-started/quickstart#your-first-issues) Your first issues ------------------------------------------------------------------------------------------------ # Create a few issues bd create "Set up database" -p 1 -t task bd create "Create API" -p 2 -t feature bd create "Add authentication" -p 2 -t feature # List them bd list **Note:** Issue IDs are hash-based (e.g., `bd-a1b2`, `bd-f14c`) to prevent collisions when multiple agents/branches work concurrently. [​](https://beads.gascity.com/getting-started/quickstart#hierarchical-issues-epics) Hierarchical issues (epics) ------------------------------------------------------------------------------------------------------------------ For large features, use hierarchical IDs to organize work: # Create epic (generates parent hash ID) bd create "Auth System" -t epic -p 1 # Returns: bd-a3f8e9 # Create child tasks (use --parent to attach to the epic) bd create "Design login UI" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.1 bd create "Backend validation" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.2 bd create "Integration tests" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.3 # View hierarchy bd dep tree bd-a3f8e9 Output: Dependency tree for bd-a3f8e9: > bd-a3f8e9: Auth System [epic] [P1] (open) > bd-a3f8e9.1: Design login UI [P1] (open) > bd-a3f8e9.2: Backend validation [P1] (open) > bd-a3f8e9.3: Integration tests [P1] (open) [​](https://beads.gascity.com/getting-started/quickstart#add-dependencies) Add dependencies ---------------------------------------------------------------------------------------------- # API depends on database bd dep add bd-2 bd-1 # Auth depends on API bd dep add bd-3 bd-2 # View the tree bd dep tree bd-3 Output: Dependency tree for bd-3: > bd-3: Add authentication [P2] (open) > bd-2: Create API [P2] (open) > bd-1: Set up database [P1] (open) **Dependency visibility:** `bd list` shows blocking dependencies inline: ○ bd-a1b2 [P1] [task] - Set up database ○ bd-f14c [P2] [feature] - Create API (blocked by: bd-a1b2) ○ bd-g25d [P2] [feature] - Add authentication (blocked by: bd-f14c) [​](https://beads.gascity.com/getting-started/quickstart#find-ready-work) Find ready work -------------------------------------------------------------------------------------------- bd ready Output: Ready work (1 issues with no active blockers): 1. [P1] bd-1: Set up database Only bd-1 is ready because bd-2 and bd-3 are blocked. **Understanding why:** Use `--explain` to see the full graph reasoning: bd ready --explain Output: Ready Work Explanation ● Ready (1 issues): bd-1 [P1] Set up database Reason: no blocking dependencies Unblocks: 1 issue(s) ● Blocked (2 issues): bd-2 [P2] Create API ← blocked by bd-1: Set up database [open] bd-3 [P2] Add authentication ← blocked by bd-2: Create API [open] ─ Summary: 1 ready, 2 blocked **Note:** `bd ready` is not the same as `bd list --status open`. The `list` command shows all open issues regardless of blockers. The `ready` command computes the dependency graph and only shows truly unblocked work. [​](https://beads.gascity.com/getting-started/quickstart#work-the-queue) Work the queue ------------------------------------------------------------------------------------------ # Start working on bd-1 bd update bd-1 --claim # Complete it bd close bd-1 --reason "Database setup complete" # Check ready work again bd ready Now bd-2 is ready. [​](https://beads.gascity.com/getting-started/quickstart#track-progress) Track progress ------------------------------------------------------------------------------------------ # See blocked issues bd blocked # View statistics bd stats [​](https://beads.gascity.com/getting-started/quickstart#team-sync) Team sync -------------------------------------------------------------------------------- Share issues with your team using Dolt remotes. Dolt stores data under `refs/dolt/data` on the same Git remote, separate from standard Git refs. In repos with `origin`, `bd init` configures that Dolt remote automatically. # Verify the remote, or add one if the repo had no origin during init bd dolt remote list bd dolt remote add origin git+ssh://git@github.com/org/repo.git # if needed # Push your issues bd dolt push # Pull teammates' changes bd dolt pull When a teammate clones the repo, `bd bootstrap` auto-detects the existing database on `refs/dolt/data`, clones it, and wires `origin` for future `bd dolt push` / `bd dolt pull`. See [`bd dolt`](https://beads.gascity.com/cli-reference/dolt) for CLI details. For remote configuration, see [Dolt architecture](https://beads.gascity.com/architecture/dolt) ; for federation, see [federation](https://beads.gascity.com/multi-agent/federation) . [​](https://beads.gascity.com/getting-started/quickstart#optional-notion-sync) Optional: Notion sync ------------------------------------------------------------------------------------------------------- If you keep project issues in Notion, save an integration token first: bd config set notion.token <your-token> Then either create a new Beads database under a parent page or connect to an existing target: bd notion init --parent <page-id> # or bd notion connect --url <notion-database-or-data-source-url> The same auth value can also come from `NOTION_TOKEN`. Directly setting `notion.data_source_id` remains available as an escape hatch for advanced setups. Check which auth source is active and whether the target schema is ready: bd notion status bd notion status --json Preview or run sync: bd notion sync --dry-run bd notion sync bd notion sync --pull bd notion sync --push [​](https://beads.gascity.com/getting-started/quickstart#database-location) Database location ------------------------------------------------------------------------------------------------ By default (embedded mode), data is stored in `.beads/embeddeddolt/` within your repository. In server mode, data is managed by the external `dolt sql-server`. [​](https://beads.gascity.com/getting-started/quickstart#migrating-databases) Migrating databases ---------------------------------------------------------------------------------------------------- After upgrading bd, use `bd migrate` to check for and migrate old database files: # Inspect migration plan (AI agents) bd migrate --inspect --json # Check schema and config bd info --schema --json # Preview migration changes bd migrate --dry-run # Migrate old databases to beads.db bd migrate # Migrate and clean up old files bd migrate --yes **AI agents:** Use `--inspect` to analyze migration safety before running. The system verifies required config keys and data integrity invariants. [​](https://beads.gascity.com/getting-started/quickstart#database-maintenance) Database maintenance ------------------------------------------------------------------------------------------------------ As your project accumulates closed issues, the database grows. Manage size with these commands: # View compaction statistics bd admin compact --stats # Preview compaction candidates (30+ days closed) bd admin compact --analyze --json # Apply agent-generated summary bd admin compact --apply --id bd-42 --summary summary.txt # Immediately delete closed issues (CAUTION: permanent!) bd admin cleanup --force **When to compact:** * Database file > 10MB with many old closed issues * After major project milestones when old issues are no longer relevant * Before archiving a project phase **Note:** Compaction is permanent graceful decay. Original content is discarded but recoverable via `bd restore <id>` (from the pre-compaction snapshot, with Dolt history as fallback). [​](https://beads.gascity.com/getting-started/quickstart#next-steps) Next steps ---------------------------------------------------------------------------------- * Add labels: `bd create "Task" -l "backend,urgent"` * Filter ready work: `bd ready --priority 1` * Explain the graph: `bd ready --explain` * Check graph integrity: `bd graph check` * Search issues: `bd list --status open` * Detect cycles: `bd dep cycles` * Gates for PR/CI sync: [`bd gate`](https://beads.gascity.com/cli-reference/gate) * More sync scenarios: [`bd dolt`](https://beads.gascity.com/cli-reference/dolt) * Full command list: [CLI Reference](https://beads.gascity.com/cli-reference/index) See the [repository README](https://github.com/gastownhall/beads/blob/main/README.md) for an overview and links to deeper docs. [Installation](https://beads.gascity.com/getting-started/installation) [IDE Setup](https://beads.gascity.com/getting-started/ide-setup) ⌘I --- # Multi-Repo Migration Guide - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/multi-agent/multi-repo-migration#content-area) This guide helps you adopt beads’ multi-repo workflow for OSS contributions, team collaboration, and multi-phase development. [​](https://beads.gascity.com/multi-agent/multi-repo-migration#quick-start) Quick Start ------------------------------------------------------------------------------------------ **Already have beads installed?** Jump to your scenario: * [OSS Contributor](https://beads.gascity.com/multi-agent/multi-repo-migration#oss-contributor-workflow) - Keep planning out of upstream PRs * [Team Member](https://beads.gascity.com/multi-agent/multi-repo-migration#team-workflow) - Shared planning on branches * [Multi-Phase Development](https://beads.gascity.com/multi-agent/multi-repo-migration#multi-phase-development) - Separate repos per phase * [Multiple Personas](https://beads.gascity.com/multi-agent/multi-repo-migration#multiple-personas) - Architect vs. implementer separation **New to beads?** See [Quick Start](https://beads.gascity.com/getting-started/quickstart) first. [​](https://beads.gascity.com/multi-agent/multi-repo-migration#what-is-multi-repo-mode) What is Multi-Repo Mode? ------------------------------------------------------------------------------------------------------------------- By default, beads stores issues in its Dolt database under `.beads/` in your current repository (`.beads/embeddeddolt/` in the default embedded mode). Multi-repo mode lets you: * **Route issues to different repositories** based on your role (maintainer vs. contributor) * **Aggregate issues from multiple repos** into a unified view * **Keep contributor planning separate** from upstream projects * **Maintain data integrity everywhere** - Dolt version control in every repo [​](https://beads.gascity.com/multi-agent/multi-repo-migration#when-do-you-need-multi-repo) When Do You Need Multi-Repo? --------------------------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#you-don%E2%80%99t-need-multi-repo-if) You DON’T need multi-repo if: * ✅ Working solo on your own project * ✅ Team with shared repository and trust model * ✅ All issues belong in the project’s git history ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#you-do-need-multi-repo-if) You DO need multi-repo if: * 🔴 Contributing to OSS - don’t pollute upstream with planning * 🔴 Fork workflow - planning shouldn’t appear in PRs * 🔴 Multiple work phases - design vs. implementation repos * 🔴 Multiple personas - architect planning vs. implementer tasks [​](https://beads.gascity.com/multi-agent/multi-repo-migration#core-concepts) Core Concepts ---------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#1-source-repository-source_repo) 1\. Source Repository (`source_repo`) Every issue has a `source_repo` field indicating which repository owns it: {"id":"bd-abc","source_repo":".","title":"Core issue"} {"id":"bd-xyz","source_repo":"~/.beads-planning","title":"Planning issue"} * `.` = Current repository (default) * `~/.beads-planning` = Contributor planning repo * `/path/to/repo` = Absolute path to another repo ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#2-auto-routing) 2\. Auto-Routing Beads automatically routes new issues to the right repository based on your role: # Maintainer (has SSH push access) bd create "Fix bug" -p 1 # → Creates in current repo (source_repo = ".") # Contributor (HTTPS or no push access) bd create "Fix bug" -p 1 # → Creates in ~/.beads-planning (source_repo = "~/.beads-planning") ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#3-multi-repo-hydration) 3\. Multi-Repo Hydration Beads can aggregate issues from multiple repositories into a unified database: bd list --json # Shows issues from: # - Current repo (.) # - Planning repo (~/.beads-planning) # - Any configured additional repos [​](https://beads.gascity.com/multi-agent/multi-repo-migration#oss-contributor-workflow) OSS Contributor Workflow -------------------------------------------------------------------------------------------------------------------- **Problem:** You’re contributing to an OSS project but don’t want your experimental planning to appear in PRs. **Solution:** Use a separate planning repository that’s never committed to upstream. ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#setup-one-time) Setup (One-Time) # 1. Fork and clone the upstream project git clone https://github.com/you/project.git cd project # 2. Initialize beads (if not already done) bd init # 3. Run the contributor setup wizard bd init --contributor # The wizard will: # - Detect that you're in a fork (checks for 'upstream' remote) # - Prompt you to create a planning repo (~/.beads-planning by default) # - Configure auto-routing (contributor → planning repo) # - Set up multi-repo hydration ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#manual-configuration) Manual Configuration If you prefer manual setup: # 1. Create planning repository mkdir -p ~/.beads-planning cd ~/.beads-planning git init bd init --prefix plan # 2. Configure routing in your fork cd ~/projects/project bd config set routing.mode auto bd config set routing.contributor "~/.beads-planning" # 3. Add planning repo to hydration sources bd config set repos.additional "~/.beads-planning" ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#daily-workflow) Daily Workflow # Work in your fork cd ~/projects/project # Create planning issues (auto-routed to ~/.beads-planning) bd create "Investigate auth implementation" -p 1 bd create "Draft RFC for new feature" -p 2 # View all issues (current repo + planning repo) bd ready bd list --json # Work on an issue bd update plan-42 --claim # Complete work bd close plan-42 --reason "Completed" # Create PR - your planning issues never appear! git add . git commit -m "Fix authentication bug" git push origin my-feature-branch # ✅ PR only contains code changes, no .beads/ pollution ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#proposing-issues-upstream) Proposing Issues Upstream If you want to share a planning issue with upstream: # Option 1: Manually copy issue to upstream repo bd show plan-42 --json > /tmp/issue.json # (Send to maintainers or create GitHub issue) # Option 2: Migrate issue (future feature, see bd-mlcz) bd migrate plan-42 --to . --dry-run bd migrate plan-42 --to . [​](https://beads.gascity.com/multi-agent/multi-repo-migration#team-workflow) Team Workflow ---------------------------------------------------------------------------------------------- **Problem:** Team members working on shared repository with branches, but different levels of planning granularity. **Solution:** Use branch-based workflow with optional personal planning repos. ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#setup-team-lead) Setup (Team Lead) # 1. Initialize beads in main repo cd ~/projects/team-project bd init --prefix team # 2. Run team setup wizard bd init --team # The wizard will: # - Detect shared repository (SSH push access) # - Configure auto-routing (maintainer → current repo) # - Set up protected branch workflow (if using GitHub/GitLab) # - Create example workflows ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#setup-team-member) Setup (Team Member) # 1. Clone team repo git clone git@github.com:team/project.git cd project # 2. Beads auto-detects you're a maintainer (SSH access) bd create "Implement feature X" -p 1 # → Creates in current repo (team-123) # 3. Optional: Create personal planning repo for experiments mkdir -p ~/.beads-planning-personal cd ~/.beads-planning-personal git init bd init --prefix exp # 4. Configure multi-repo in team project cd ~/projects/project bd config set repos.additional "~/.beads-planning-personal" ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#daily-workflow-2) Daily Workflow # Shared team planning (committed to repo) bd create "Implement auth" -p 1 --repo . # → team-42 (visible to entire team) # Personal experiments (not committed to team repo) bd create "Try alternative approach" -p 2 --repo ~/.beads-planning-personal # → exp-99 (private planning) # View all work bd ready bd list --json # Complete team work and sync bd dolt push [​](https://beads.gascity.com/multi-agent/multi-repo-migration#multi-phase-development) Multi-Phase Development ------------------------------------------------------------------------------------------------------------------ **Problem:** Project has distinct phases (planning, implementation, maintenance) that need separate issue spaces. **Solution:** Use separate repositories for each phase. ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#setup) Setup # 1. Create phase repositories mkdir -p ~/projects/myapp-planning mkdir -p ~/projects/myapp-implementation mkdir -p ~/projects/myapp-maintenance # 2. Initialize each phase cd ~/projects/myapp-planning git init bd init --prefix plan cd ~/projects/myapp-implementation git init bd init --prefix impl cd ~/projects/myapp-maintenance git init bd init --prefix maint # 3. Configure aggregation in main workspace cd ~/projects/myapp-implementation bd config set repos.additional "~/projects/myapp-planning,~/projects/myapp-maintenance" ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#workflow) Workflow # Phase 1: Planning cd ~/projects/myapp-planning bd create "Design auth system" -p 1 -t epic bd create "Research OAuth providers" -p 1 # Phase 2: Implementation (view planning + implementation issues) cd ~/projects/myapp-implementation bd ready # Shows issues from both repos bd create "Implement auth backend" -p 1 bd dep add impl-42 plan-10 --type blocks # Link across repos # Phase 3: Maintenance cd ~/projects/myapp-maintenance bd create "Security patch for auth" -p 0 -t bug [​](https://beads.gascity.com/multi-agent/multi-repo-migration#multiple-personas) Multiple Personas ------------------------------------------------------------------------------------------------------ **Problem:** You work as both architect (high-level planning) and implementer (detailed tasks). **Solution:** Separate repositories for each persona’s work. ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#setup-2) Setup # 1. Create persona repos mkdir -p ~/architect-planning mkdir -p ~/implementer-tasks cd ~/architect-planning git init bd init --prefix arch cd ~/implementer-tasks git init bd init --prefix impl # 2. Configure aggregation cd ~/implementer-tasks bd config set repos.additional "~/architect-planning" ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#workflow-2) Workflow # Architect mode cd ~/architect-planning bd create "System architecture for feature X" -p 1 -t epic bd create "Database schema design" -p 1 # Implementer mode (sees both architect + implementation tasks) cd ~/implementer-tasks bd ready bd create "Implement user table" -p 1 bd dep add impl-10 arch-42 --type blocks # Complete implementation bd close impl-10 --reason "Completed" [​](https://beads.gascity.com/multi-agent/multi-repo-migration#configuration-reference) Configuration Reference ------------------------------------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#routing-settings) Routing Settings # Auto-detect role and route accordingly bd config set routing.mode auto # Always use default repo (ignore role detection) bd config set routing.mode explicit bd config set routing.default "." # Configure repos for each role bd config set routing.maintainer "." bd config set routing.contributor "~/.beads-planning" ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#multi-repo-hydration) Multi-Repo Hydration # Add additional repos to aggregate bd config set repos.additional "~/repo1,~/repo2,~/repo3" # Set primary repo (optional) bd config set repos.primary "." ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#override-auto-routing) Override Auto-Routing # Force issue to specific repo (ignores auto-routing) bd create "Issue" -p 1 --repo /path/to/repo [​](https://beads.gascity.com/multi-agent/multi-repo-migration#troubleshooting) Troubleshooting -------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#issues-appearing-in-wrong-repository) Issues appearing in wrong repository **Problem:** `bd create` routes issues to unexpected repository. **Solution:** # Check current routing configuration bd config get routing.mode bd config get routing.maintainer bd config get routing.contributor # Check detected role bd config get beads.role # Override with explicit flag bd create "Issue" -p 1 --repo . ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#can%E2%80%99t-see-issues-from-other-repos) Can’t see issues from other repos **Problem:** `bd list` only shows issues from current repo. **Solution:** # Check multi-repo configuration bd config get repos.additional # Add missing repos bd config set repos.additional "~/repo1,~/repo2" # Verify hydration bd dolt push bd list --json ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#merge-conflicts) Merge conflicts **Problem:** Multiple repos with conflicting changes. **Solution:** Dolt handles merge conflicts natively with cell-level merge. See [Troubleshooting](https://beads.gascity.com/reference/troubleshooting#merge-conflicts) for details. ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#discovered-issues-in-wrong-repository) Discovered issues in wrong repository **Problem:** Issues created with `discovered-from` dependency appear in wrong repo. **Solution:** Discovered issues automatically inherit parent’s `source_repo`. This is intentional. To override: bd create "Issue" -p 1 --deps discovered-from:bd-42 --repo /different/repo ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#planning-repo-polluting-prs) Planning repo polluting PRs **Problem:** Your `~/.beads-planning` changes appear in PRs to upstream. **Solution:** This shouldn’t happen if configured correctly. Verify: # Check that planning repo is separate from fork ls -la ~/.beads-planning/.git # Should exist ls -la ~/projects/fork/.beads/ # Should NOT contain planning issues # Verify routing bd config get routing.contributor # Should be ~/.beads-planning [​](https://beads.gascity.com/multi-agent/multi-repo-migration#backward-compatibility) Backward Compatibility ---------------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#migrating-from-single-repo) Migrating from Single-Repo No migration needed! Multi-repo mode is opt-in: # Before (single repo) bd create "Issue" -p 1 # → Creates in local Dolt database # After (multi-repo configured) bd create "Issue" -p 1 # → Auto-routed based on role # → Old issues in local database still work ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#disabling-multi-repo) Disabling Multi-Repo # Remove routing configuration bd config unset routing.mode bd config unset repos.additional # All issues go to current repo again bd create "Issue" -p 1 # → Back to single-repo mode [​](https://beads.gascity.com/multi-agent/multi-repo-migration#best-practices) Best Practices ------------------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#oss-contributors) OSS Contributors * ✅ Always use `~/.beads-planning` or similar for personal planning * ✅ Never commit `.beads/` changes to upstream PRs * ✅ Use descriptive prefixes (`plan-`, `exp-`) for clarity * ❌ Don’t mix planning and implementation in the same repo ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#teams) Teams * ✅ Use `bd dolt push` to sync the shared Dolt database * ✅ Use protected branch workflow for main/master * ✅ Review issue changes in PRs like code changes * ❌ Don’t delete `.beads/` - you lose all issue data ### [​](https://beads.gascity.com/multi-agent/multi-repo-migration#multi-phase-projects) Multi-Phase Projects * ✅ Use clear phase naming (`planning`, `impl`, `maint`) * ✅ Link issues across phases with dependencies * ✅ Archive completed phases periodically * ❌ Don’t duplicate issues across phases [​](https://beads.gascity.com/multi-agent/multi-repo-migration#next-steps) Next Steps ---------------------------------------------------------------------------------------- * **CLI Reference:** See [README.md](https://github.com/gastownhall/beads/blob/main/README.md) for command details * **Configuration Guide:** See [Configuration](https://beads.gascity.com/reference/configuration) for all config options * **Troubleshooting:** See [Troubleshooting](https://beads.gascity.com/reference/troubleshooting) * **Multi-Repo Internals:** See [ROUTING.md#multi-repo-hydration](https://beads.gascity.com/multi-agent/routing#multi-repo-hydration) [​](https://beads.gascity.com/multi-agent/multi-repo-migration#related-issues) Related Issues ------------------------------------------------------------------------------------------------ * `bd-8rd` - Migration and onboarding epic * `bd-mlcz` - `bd migrate` command (planned) * `bd-kla1` - `bd init --contributor` wizard - implemented * `bd-twlr` - `bd init --team` wizard - implemented [Federation Setup Guide](https://beads.gascity.com/multi-agent/federation) [Integrations](https://beads.gascity.com/integrations) ⌘I --- # Installation - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/getting-started/installation#content-area) Complete installation guide for all platforms. [​](https://beads.gascity.com/getting-started/installation#components-overview) Components Overview ------------------------------------------------------------------------------------------------------ Beads has several components - here’s what they are and when you need them: | Component | What It Is | When You Need It | | --- | --- | --- | | **bd CLI** | Core command-line tool | Always - this is the foundation | | **Claude Code Plugin** | Slash commands + enhanced UX | Optional - if you want `/beads:ready`, `/beads:create` commands | | **MCP Server (beads-mcp)** | Model Context Protocol interface | Only for MCP-only environments (Claude Desktop, Amp) | **How they relate:** * The **bd CLI** is the core - install it first via Homebrew, npm, or script * The **Plugin** enhances Claude Code with slash commands but _requires_ the CLI installed * The **MCP server** is an _alternative_ to the CLI for environments without shell access **Important:** Beads is installed system-wide, not cloned into your project. The `.beads/` directory in your project only contains the issue database. **Typical setups:** | Environment | What to Install | | --- | --- | | Claude Code, Cursor, Windsurf | bd CLI (+ optional Plugin for Claude Code) | | GitHub Copilot (VS Code) | bd CLI + MCP server | | Claude Desktop (no shell) | MCP server only | | Terminal / scripts | bd CLI only | | CI/CD pipelines | bd CLI only | **Are they mutually exclusive?** No - you can have CLI + Plugin + MCP all installed. They don’t conflict. But most users only need the CLI. [​](https://beads.gascity.com/getting-started/installation#quick-install-recommended) Quick Install (Recommended) -------------------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/getting-started/installation#homebrew-macos/linux) Homebrew (macOS/Linux) brew install beads Homebrew core’s `beads` formula is the supported Homebrew package. If you previously installed the old tap formula as `bd`, see [Migrating from the old Homebrew tap](https://beads.gascity.com/getting-started/upgrading#homebrew) to switch to the core formula. **Why Homebrew?** * Simple one-command install * Automatic updates via `brew upgrade` * No need to install Go * Handles PATH setup automatically ### [​](https://beads.gascity.com/getting-started/installation#mise-en-place-macos/linux/windows) Mise-en-place (macOS/Linux/Windows) You can install beads using [mise](https://mise.jdx.dev/) from the latest GitHub release: mise install github:gastownhall/beads mise use -g github:gastownhall/beads The `-g` enables beads globally. To enable project-specific versions, omit it. **Why Mise?** * Same as Homebrew: simple, updates via `mise up`, works without Go, handles PATH * Supports all platforms * Always the latest release * May optionally use a different release version for specific projects Mise’s Go backend follows the same caveats as `go install`; prefer the release backend above. ### [​](https://beads.gascity.com/getting-started/installation#quick-install-script-macos/linux/freebsd) Quick Install Script (macOS/Linux/FreeBSD) curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash The installer will: * Detect your platform (macOS/Linux/FreeBSD, amd64/arm64) * Verify downloaded release archives against release `checksums.txt` * Fall back to the supported `go install` modes if Go is available * Fall back to building from source if needed * Guide you through PATH setup if necessary On macOS, the script preserves the downloaded binary signature by default. If you explicitly want ad-hoc local re-signing, opt in: BEADS_INSTALL_RESIGN_MACOS=1 curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ### [​](https://beads.gascity.com/getting-started/installation#comparison-of-installation-methods) Comparison of Installation Methods | Method | Best For | Updates | Prerequisites | Notes | | --- | --- | --- | --- | --- | | **Homebrew** | macOS/Linux users | `brew upgrade beads` | Homebrew | Recommended. Handles everything automatically | | **Mise** | All platforms | `mise up` | mise | Installs the latest GitHub release | | **npm** | JS/Node.js projects | `npm update -g @beads/bd` | Node.js | Convenient if npm is your ecosystem | | **bun** | JS/Bun.js projects | `bun install -g --trust @beads/bd` | Bun.js | Convenient if bun is your ecosystem | | **Install script** | Quick setup, CI/CD | Re-run script | curl, bash | Good for automation and one-liners | | **go install (nocgo)** | Go developers, simplest install | Re-run command | Go 1.24+ | **Server-mode only** (no embedded Dolt) | | **go install (cgo)** | Go developers wanting embedded mode | Re-run command | Go 1.24+, C compiler | Full embedded-Dolt support | | **From source** | Contributors only | `git pull && go build` | Go, git | Full control, can modify code | | **AUR (Arch)** | Arch Linux users | `yay -Syu` | yay/paru | Community-maintained | **TL;DR:** Use Homebrew if available. Use npm if you’re in a Node.js environment. Use the script for quick one-off installs or CI. [​](https://beads.gascity.com/getting-started/installation#go-install-and-build-dependencies) Go Install and Build Dependencies ---------------------------------------------------------------------------------------------------------------------------------- Use Homebrew, npm, or the install script if you do not specifically need `go install`. `go install` has two supported modes that give different capabilities: * **Server-mode only (nocgo, simplest):** `CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest`. Works on any machine with a Go toolchain, no C compiler needed. Produces a server-mode-only binary — you must run an external `dolt sql-server` and use `bd init --server`. See [Dolt](https://beads.gascity.com/architecture/dolt) for server-mode setup. * **Embedded-capable (cgo):** `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest`. Requires a C compiler (gcc/clang on Unix, MinGW on Windows). Produces a binary with the default embedded-Dolt backend — `bd init` Just Works. ICU headers are not required. The embedded-capable command uses `gms_pure_go` so go-mysql-server uses Go’s stdlib regexp instead of ICU. Use the `github.com/steveyegge/beads` path for `go install`. The repository now lives under `gastownhall/beads`, but released Go modules still declare `github.com/steveyegge/beads` for compatibility. If you don’t have a preference, `brew install beads` or the install script give you the embedded-capable build with no fuss. ### [​](https://beads.gascity.com/getting-started/installation#build-dependencies-contributors-only) Build Dependencies (Contributors Only) These dependencies are only needed if you build from source. If you installed via Homebrew, npm, or the install script, skip this section entirely. Building from source requires a C compiler (for CGO / embedded Dolt). ICU is not required — all builds use the `gms_pure_go` tag which selects Go’s stdlib `regexp` instead of ICU regex. See [ICU-POLICY.md](https://github.com/gastownhall/beads/blob/main/engdocs/ICU-POLICY.md) for details. macOS (Homebrew): brew install zstd Linux (Debian/Ubuntu): sudo apt-get install -y libzstd-dev Linux (Fedora/RHEL): sudo dnf install -y libzstd-devel For maintainers only: if you intentionally need to run [scripts/test-icu-path.sh](https://github.com/gastownhall/beads/blob/main/scripts/test-icu-path.sh) (which exercises the leftover ICU code path), install ICU headers: `brew install icu4c` (macOS) or `sudo apt-get install -y libicu-dev` (Linux). This is not needed for normal development. [​](https://beads.gascity.com/getting-started/installation#platform-specific-installation) Platform-Specific Installation ---------------------------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/getting-started/installation#macos) macOS **Via Homebrew** (recommended): brew install beads **Via go install** (server-mode only): CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest **Via go install** (embedded-capable, needs Xcode CLI tools): CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest **From source**: git clone https://github.com/gastownhall/beads cd beads make build sudo mv bd /usr/local/bin/ ### [​](https://beads.gascity.com/getting-started/installation#linux) Linux **Via Homebrew** (works on Linux too): brew install beads **Arch Linux** (AUR): # Install from AUR yay -S beads-git # or paru -S beads-git Thanks to [@v4rgas](https://github.com/v4rgas) for maintaining the AUR package! **Via go install** (server-mode only): CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest **Via go install** (embedded-capable, needs gcc): CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ### [​](https://beads.gascity.com/getting-started/installation#freebsd) FreeBSD **Via quick install script**: curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash **Via go install** (server-mode only): CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest ### [​](https://beads.gascity.com/getting-started/installation#windows-11) Windows 11 Beads ships with native Windows support—no MSYS or MinGW required. **Prerequisites:** * [Go 1.24+](https://go.dev/dl/) installed (add `%USERPROFILE%\go\bin` to your `PATH`) * Git for Windows **Via PowerShell script**: irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex The script installs a prebuilt Windows release if available and verifies the downloaded ZIP checksum against release `checksums.txt`. Go is only required for `go install` or building from source. **Via go install** (server-mode only): $env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest This produces a server-mode-only binary with no C compiler requirement — the fastest path to a working `bd` on Windows. **Via go install** (embedded-capable, needs a Windows CGO toolchain): $env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest Requires a GCC-compatible Windows CGO compiler on your PATH, such as MinGW-w64/MSYS2 `gcc` or MSYS2 LLVM `clang` targeting `windows-gnu` (`clang64`/`clangarm64`). ICU is **not** required — `gms_pure_go` selects Go’s stdlib `regexp`. Visual Studio `cl.exe` by itself is not enough because Go passes GCC-style CGO flags; use a MinGW/MSYS2 toolchain, set `CC`, or set `WINDOWS_CGO_BINS` when building from source. **From source**: git clone https://github.com/gastownhall/beads cd beads make build Move-Item bd.exe $env:USERPROFILE\AppData\Local\Microsoft\WindowsApps\ **Windows notes:** * The Dolt server listens on a loopback TCP endpoint * Allow `bd.exe` loopback traffic through any host firewall [​](https://beads.gascity.com/getting-started/installation#ide-and-editor-integrations) IDE and Editor Integrations ---------------------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/getting-started/installation#cli-+-hooks-recommended) CLI + Hooks (Recommended) The recommended approach for Claude Code, Cursor, Windsurf, and other editors with shell access: # 1. Install bd CLI (see Quick Install above) brew install beads # 2. Initialize in your project cd your-project bd init --quiet # 3. Setup editor integration (choose one) bd setup claude # Claude Code - installs SessionStart hooks bd setup copilot # GitHub Copilot CLI - creates .copilot-plugin/plugin.json + .github/copilot-instructions.md bd setup cursor # Cursor IDE - creates .cursor/rules/beads.mdc bd setup aider # Aider - creates .aider.conf.yml bd setup codex # Codex CLI - installs Beads skill, AGENTS.md guidance, and native hooks bd setup factory # Factory.ai Droid - creates/updates AGENTS.md bd setup mux # Mux - creates/updates AGENTS.md **How it works:** * `bd init` creates or updates `AGENTS.md` and installs project Claude/Codex integrations by default unless you use `--skip-agents` or `--stealth` * Editor hooks/rules inject `bd prime` automatically on session start * Codex 0.129.0+ uses native `/hooks`: SessionStart injects `bd prime`, compact hooks mark context stale, and the next prompt after compaction refreshes Beads context once * `bd prime` provides ~1-2k tokens of workflow context * You use `bd` CLI commands directly * Git hooks (installed by `bd init`) refresh exports and legacy fallbacks; `bd dolt push/pull` syncs the database * `bd onboard` prints the small manual snippet for unsupported agents or custom instruction files **Why this is recommended:** * **Context efficient** - ~1-2k tokens vs 10-50k for MCP tool schemas * **Lower latency** - Direct CLI calls, no MCP protocol overhead * **Universal** - Works with any editor that has shell access **Verify installation:** every recipe supports a check flag, e.g. `bd setup claude --check` or `bd setup copilot --check`. ### [​](https://beads.gascity.com/getting-started/installation#claude-code-plugin-optional) Claude Code Plugin (Optional) For enhanced UX with slash commands: # In Claude Code /plugin marketplace add gastownhall/beads /plugin install beads # Restart Claude Code The plugin adds: * Slash commands: `/beads:ready`, `/beads:create`, `/beads:show`, `/beads:update`, `/beads:close`, etc. * Task agent for autonomous execution See [Claude Code Plugin](https://beads.gascity.com/integrations/claude-code-plugin) for complete plugin documentation. ### [​](https://beads.gascity.com/getting-started/installation#github-copilot) GitHub Copilot For **VS Code with GitHub Copilot**, install the MCP server (`uv tool install beads-mcp`) and create `.vscode/mcp.json` in your project — or add it to the VS Code user-level MCP config to enable it for all projects. See [GitHub Copilot](https://beads.gascity.com/integrations/github-copilot) for the complete setup guide, including the user-level config paths per platform. For the **GitHub Copilot CLI** terminal integration: bd setup copilot # Install project Copilot plugin + repository instructions bd setup copilot --check # Verify the project integration files exist This setup is currently project-scoped only. It writes `.copilot-plugin/plugin.json` and `.github/copilot-instructions.md`; there is no separate `--global` or `--project` mode for Copilot today, and it does not manage `~/.copilot/...` paths. See [Copilot CLI](https://beads.gascity.com/integrations/copilot-cli) for the full guide. ### [​](https://beads.gascity.com/getting-started/installation#mcp-server-alternative) MCP Server (Alternative) Use MCP only when CLI is unavailable (Claude Desktop, Sourcegraph Amp without shell): # Using uv (recommended) uv tool install beads-mcp # Or using pip pip install beads-mcp **Configuration for Claude Desktop** (macOS): Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: { "mcpServers": { "beads": { "command": "beads-mcp" } } } For Sourcegraph Amp configuration and detailed MCP server documentation, see [MCP Server](https://beads.gascity.com/integrations/mcp-server) . [​](https://beads.gascity.com/getting-started/installation#verifying-installation) Verifying Installation ------------------------------------------------------------------------------------------------------------ After installing, verify bd is working: bd version bd help [​](https://beads.gascity.com/getting-started/installation#troubleshooting) Troubleshooting ---------------------------------------------------------------------------------------------- For additional troubleshooting, see [Troubleshooting](https://beads.gascity.com/reference/troubleshooting) . ### [​](https://beads.gascity.com/getting-started/installation#bd-command-not-found) `bd: command not found` bd is not in your PATH: # Check if installed go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd # Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc) export PATH="$PATH:$(go env GOPATH)/bin" # Or reinstall with the recommended installer curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ### [​](https://beads.gascity.com/getting-started/installation#zsh-killed-bd-or-crashes-on-macos) `zsh: killed bd` or crashes on macOS This is typically caused by CGO/SQLite compatibility issues: # Install an embedded-capable build CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest If you installed via Homebrew, this shouldn’t be necessary as the formula already enables CGO. If you’re still seeing crashes with the Homebrew version, please [file an issue](https://github.com/gastownhall/beads/issues) . ### [​](https://beads.gascity.com/getting-started/installation#mcp-server-fails-to-start-standalone-beads-mcp) MCP server fails to start (standalone beads-mcp) The Claude Code plugin itself does not bundle an MCP server. If you configured the standalone `beads-mcp` server (see [MCP Server](https://beads.gascity.com/integrations/mcp-server) ) and it fails immediately, `uv` is likely not installed or not in your PATH. **Symptoms:** * Plugin slash commands work, but MCP tools are unavailable * Error logs show `command not found: uv` * Server fails silently on startup **Solution:** # Install uv curl -LsSf https://astral.sh/uv/install.sh | sh # Restart your shell or update PATH source ~/.local/bin/env # Verify uv is available which uv # Restart Claude Code See [Claude Code Plugin](https://beads.gascity.com/integrations/claude-code-plugin) for alternative installation methods. [​](https://beads.gascity.com/getting-started/installation#updating-bd) Updating bd -------------------------------------------------------------------------------------- Upgrade checklist: 1. With your current `bd`, sync remote-backed databases before installing the new binary: `bd dolt push` `bd dolt pull` 2. Back up before migration: `bd export --all -o .beads/backup/pre-migrate-$(date +%Y%m%d).jsonl` 3. Upgrade using the command for your install method below. 4. After upgrading: `bd info --whats-new` `bd hooks install` `bd version` 5. If crossing a schema migration on a remote-backed database, only the designated migrator runs: `bd migrate` `bd dolt push` Other clones should install the new binary and run `bd bootstrap`, not independently migrate. For the full procedure, see [Upgrading](https://beads.gascity.com/getting-started/upgrading) . ### [​](https://beads.gascity.com/getting-started/installation#quick-install-script-macos/linux/freebsd-2) Quick install script (macOS/Linux/FreeBSD) curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ### [​](https://beads.gascity.com/getting-started/installation#powershell-installer-windows) PowerShell installer (Windows) irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex ### [​](https://beads.gascity.com/getting-started/installation#homebrew) Homebrew brew upgrade beads ### [​](https://beads.gascity.com/getting-started/installation#npm) npm npm update -g @beads/bd ### [​](https://beads.gascity.com/getting-started/installation#bun) bun bun install -g --trust @beads/bd ### [​](https://beads.gascity.com/getting-started/installation#go-install) go install Use whichever mode you installed with originally: # Server-mode only CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest # Embedded-capable CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest ### [​](https://beads.gascity.com/getting-started/installation#from-source) From source cd beads git pull make build sudo mv bd /usr/local/bin/ Prereleases (e.g. release candidates) are published only as GitHub prereleases and are not pushed to the stable Homebrew/npm/PyPI channels, so `brew upgrade` and friends will not move you onto them — fetch the prerelease build explicitly. For post-upgrade steps (hooks, migrations), see [Upgrading](https://beads.gascity.com/getting-started/upgrading) . [​](https://beads.gascity.com/getting-started/installation#uninstalling) Uninstalling ---------------------------------------------------------------------------------------- To completely remove Beads from a repository, see [Uninstalling](https://beads.gascity.com/recovery/uninstalling) . [​](https://beads.gascity.com/getting-started/installation#next-steps) Next Steps ------------------------------------------------------------------------------------ After installation: 1. **Initialize a project**: `cd your-project && bd init` 2. **Learn the basics**: See [Quick Start](https://beads.gascity.com/getting-started/quickstart) 3. **Configure your agent**: See [IDE Setup](https://beads.gascity.com/getting-started/ide-setup) , or run `bd setup --list` 4. **Explore examples**: Check out the [examples/](https://github.com/gastownhall/beads/tree/main/examples) directory [Introduction](https://beads.gascity.com/) [Quick Start](https://beads.gascity.com/getting-started/quickstart) ⌘I --- # Multi-Repo Routing - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/multi-agent/routing#content-area) One agent often works across more than one repository: an OSS fork plus a private planning repo, a planning repo feeding an implementation repo, several project checkouts on one machine. **Routing** decides which repository’s database receives each new bead, so a contributor’s planning never pollutes upstream PRs while a maintainer’s beads land straight in the project. Routing is opt-in. With no routing configuration, every bead lands in the current repository — nothing on this page changes single-repo workflows. [​](https://beads.gascity.com/multi-agent/routing#the-contributor-problem) The contributor problem ----------------------------------------------------------------------------------------------------- You fork an OSS project that uses beads. Every planning bead you create writes to the fork’s `.beads/` data, and your fork’s issue database now diverges from upstream in every PR you open. What you want is to plan freely _about_ the project without planning _in_ the project. Routing solves this by detecting your role and redirecting `bd create` to a separate planning repository (`~/.beads-planning` by default) that is never pushed upstream. [​](https://beads.gascity.com/multi-agent/routing#how-routing-decides) How routing decides --------------------------------------------------------------------------------------------- When you run `bd create`, the target repository is chosen in strict precedence order: 1. `--repo <path>` — explicit override, always wins 2. `routing.mode: auto` — route by detected role (maintainer or contributor) 3. `routing.default` — everything else (defaults to `.`, the current repo) Reads follow the same routing: with routing active, `bd list` and `bd ready` read from the routed repository, and ID lookups like `bd show` fall back to the routed repository when a bead isn’t found locally. [​](https://beads.gascity.com/multi-agent/routing#role-detection) Role detection ----------------------------------------------------------------------------------- The role that drives auto mode comes from git config — `beads.role` is the source of truth: bd config set beads.role contributor # stored in git config, not the database bd config get beads.role When `beads.role` is unset, `bd` prints a warning and falls back to a deprecated remote-URL heuristic: | Git remote situation | Detected role | | --- | --- | | `origin` and `upstream` point at different repos (fork workflow) | contributor | | SSH `origin` (`git@...`, `ssh://`) or credentialed HTTPS | maintainer | | Plain HTTPS `origin` without credentials | contributor | | No remote configured (local project) | maintainer | SSH does not reliably indicate push access — fork contributors often clone over SSH. Set `beads.role` explicitly and the heuristic (and its warning) never runs. [​](https://beads.gascity.com/multi-agent/routing#setup) Setup ----------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/routing#contributors) Contributors cd ~/projects/my-fork bd init --contributor The interactive wizard: 1. Creates the planning repository (`~/.beads-planning` by default) as its own git repo with a `.beads/` directory 2. Sets `routing.mode: auto` and `routing.contributor` to the planning repo 3. Adds the planning repo to `repos.additional` so routed beads stay visible (see [hydration](https://beads.gascity.com/multi-agent/routing#multi-repo-hydration) ) 4. On forks, points sync at the `upstream` remote so `bd dolt pull` fetches issue data from the source repo rather than your fork Plain `bd init` also detects the fork pattern (an `upstream` remote that differs from `origin`) and applies the same contributor configuration automatically; pass `--role maintainer` to opt out. ### [​](https://beads.gascity.com/multi-agent/routing#teams) Teams bd init --team Teams sharing one repository usually need no routing: with routing unset, every bead lands in the shared repo. The team wizard configures the rest of the shared workflow — team mode and, for protected-main setups, a separate sync branch for issue commits. Team members who want a private scratch space route experiments explicitly: bd create "Try alternative approach" --repo ~/.beads-planning-personal Full step-by-step walkthroughs for both scenarios (plus multi-phase and multi-persona setups) live in [Multi-Repo Migration](https://beads.gascity.com/multi-agent/multi-repo-migration) . [​](https://beads.gascity.com/multi-agent/routing#configuration-reference) Configuration reference ----------------------------------------------------------------------------------------------------- Set these with `bd config set <key> <value>`; see the [configuration reference](https://beads.gascity.com/reference/configuration) for storage locations. | Key | Default | Meaning | | --- | --- | --- | | `routing.mode` | (unset) | `auto` routes by role; `explicit` (or unset) sends everything to `routing.default` | | `routing.default` | `.` | Target when auto mode is off | | `routing.maintainer` | `.` | Target for maintainers in auto mode | | `routing.contributor` | `~/.beads-planning` | Target for contributors in auto mode | | `repos.primary` | (unset) | Primary repo for multi-repo hydration | | `repos.additional` | (unset) | Repos to hydrate beads from | | `beads.role` | (unset) | Explicit role: `maintainer` or `contributor` (stored in git config) | Verify the effective configuration and where each value comes from: bd config show # all sources: config.yaml, database, git, env bd config validate # checks routing.mode value and related settings bd where # which database this directory actually uses [​](https://beads.gascity.com/multi-agent/routing#overriding-per-bead) Overriding per bead --------------------------------------------------------------------------------------------- `--repo` bypasses routing entirely for one bead: bd create "Fix upstream bug" --repo . # force current repo bd create "Private experiment" --repo ~/scratch # force another repo [​](https://beads.gascity.com/multi-agent/routing#discovered-work-stays-with-its-parent) Discovered work stays with its parent --------------------------------------------------------------------------------------------------------------------------------- A bead created with a `discovered-from` dependency inherits its parent’s `source_repo`, so work discovered while executing a task stays attributed to the same repository as that task — regardless of your role: bd create "Found race in auth" --deps discovered-from:bd-abc # inherits bd-abc's source_repo Add `--repo` to override the inheritance. [​](https://beads.gascity.com/multi-agent/routing#multi-repo-hydration) Multi-repo hydration ----------------------------------------------------------------------------------------------- Routing writes beads to another repository — which means your current database doesn’t contain them. **Hydration** imports beads from other repos into your database, each tagged with its `source_repo`, so `bd list` and `bd ready` show one unified view. Configure it by listing the other repos in `repos.additional`: bd repo add ~/.beads-planning # add a repo to hydrate from bd repo list # show primary + additional repos bd repo sync # import beads from all additional repos bd repo remove ~/.beads-planning # remove, deleting its hydrated beads `bd repo sync` reads each additional repo’s `.beads/issues.jsonl` export and imports the beads with their original prefixes and `source_repo` set, skipping repos whose export hasn’t changed. `bd init --contributor` wires hydration up automatically; `bd doctor` warns when routing targets are missing from `repos.additional`. Once hydrated, beads from other repos are ordinary rows in your database — filter by provenance or link them with normal dependencies: bd list --json | jq '.[] | select(.source_repo == "~/.beads-planning")' bd dep add impl-42 plan-10 --type blocks For dependencies on _capabilities_ of another project rather than specific beads, `bd dep add` also accepts `external:<project>:<capability>` targets — see [`bd dep`](https://beads.gascity.com/cli-reference/dep) . [​](https://beads.gascity.com/multi-agent/routing#one-agent-many-projects) One agent, many projects ------------------------------------------------------------------------------------------------------ An AI agent working across several repositories should run a _single_ beads MCP server instance: { "beads": { "command": "beads-mcp", "args": [] } } The server resolves the beads workspace from each request’s working directory, so one configuration serves every project while each project keeps its own isolated database (embedded Dolt at `.beads/embeddeddolt/` by default; server mode uses `.beads/dolt/`). Running one MCP instance per project invites operations landing in the wrong database. To share one Dolt server across all projects instead of embedded per-project storage, initialize with `bd init --shared-server` (or set `BEADS_DOLT_SHARED_SERVER=1`): projects share a server at `~/.beads/shared-server/` while staying isolated in per-project databases named after their issue prefixes. See [MCP Server](https://beads.gascity.com/integrations/mcp-server) for installation and client configuration. [​](https://beads.gascity.com/multi-agent/routing#troubleshooting) Troubleshooting ------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/multi-agent/routing#beads-land-in-the-wrong-repository) Beads land in the wrong repository bd config get routing.mode # auto? bd config get beads.role # explicit role set? bd config show --source git # what git config contributes Fix by setting the role explicitly (`bd config set beads.role maintainer`), forcing the target for one bead (`--repo .`), or disabling role detection entirely (`bd config set routing.mode explicit`). ### [​](https://beads.gascity.com/multi-agent/routing#routed-beads-don%E2%80%99t-appear-in-bd-list) Routed beads don’t appear in bd list The routing target isn’t being hydrated. Add it and sync: bd repo add ~/.beads-planning bd repo sync `bd doctor` catches this misconfiguration. ### [​](https://beads.gascity.com/multi-agent/routing#discovered-beads-appear-in-the-%E2%80%9Cwrong%E2%80%9D-repo) Discovered beads appear in the “wrong” repo Intentional — beads with a `discovered-from` dependency inherit the parent’s `source_repo`. Override with `--repo` at creation time. ### [​](https://beads.gascity.com/multi-agent/routing#planning-beads-show-up-in-upstream-prs) Planning beads show up in upstream PRs The planning repo must be a separate git repository, never committed to the fork: ls ~/.beads-planning/.git # should exist bd config get routing.contributor # should point at the planning repo ### [​](https://beads.gascity.com/multi-agent/routing#role-warning-on-every-bd-create) Role warning on every bd create `bd` warns when it falls back to the URL heuristic. Silence it permanently: bd config set beads.role maintainer # or contributor [​](https://beads.gascity.com/multi-agent/routing#related-pages) Related pages --------------------------------------------------------------------------------- * [Multi-Repo Migration](https://beads.gascity.com/multi-agent/multi-repo-migration) — full setup walkthroughs for contributor, team, and multi-phase workflows * [Agent Coordination](https://beads.gascity.com/multi-agent/coordination) — assigning and claiming work between agents * [Federation](https://beads.gascity.com/multi-agent/federation) — peer-to-peer sharing of beads across repos and organizations * [`bd init`](https://beads.gascity.com/cli-reference/init) , [`bd config`](https://beads.gascity.com/cli-reference/config) , [`bd repo`](https://beads.gascity.com/cli-reference/repo) , [`bd create`](https://beads.gascity.com/cli-reference/create) — command reference [Multi-Agent](https://beads.gascity.com/multi-agent) [Agent Coordination](https://beads.gascity.com/multi-agent/coordination) ⌘I --- # Configuration - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference/configuration#content-area) Complete configuration reference for beads. Last reviewed: 2026-07-10 Freshness source: `cmd/bd/main.go`, `cmd/bd/config.go`, and `internal/configfile/`. beads has two complementary configuration systems: 1. **Tool-level configuration** (YAML, managed by [Viper](https://github.com/spf13/viper) ) — startup flags and tool behavior, stored in `config.yaml` files. These are user preferences: output format, auto-commit behavior, CLI ergonomics. 2. **Project-level configuration** (managed by `bd config`) — integration credentials, status maps, and project-specific settings, stored in the Dolt database. Some keys are routed to `config.yaml` instead (see [YAML-only keys](https://beads.gascity.com/reference/configuration#yaml-only-keys-startup-settings) below). The split is deliberate: tool settings are user-specific; project config is team-shared and travels with the database when you run `bd dolt push`. That is also why secrets are refused in the database — see [Security](https://beads.gascity.com/reference/configuration#security-where-secrets-live) . Dolt is the only storage backend. Embedded mode (the default) stores data at `.beads/embeddeddolt/`; server mode (`bd init --server` or `BEADS_DOLT_SERVER_MODE=1`) uses `.beads/dolt/`. See [Dolt architecture](https://beads.gascity.com/architecture/dolt) . [​](https://beads.gascity.com/reference/configuration#configuration-locations) Configuration Locations --------------------------------------------------------------------------------------------------------- `config.yaml` is searched in this order, with later files overriding earlier ones: 1. `~/.beads/config.yaml` (legacy user-level, lowest priority) 2. `~/.config/bd/config.yaml` (user-level; this exact path is checked even on platforms whose native user-config directory differs) 3. `<repo>/.beads/config.yaml` (project-level, walked up from the current directory) 4. `$BEADS_DIR/config.yaml` (highest priority, when `BEADS_DIR` points at a different workspace) A `config.local.yaml` next to the project `config.yaml` is also merged in last for machine-specific overrides that should not be committed. [​](https://beads.gascity.com/reference/configuration#precedence) Precedence ------------------------------------------------------------------------------- For Viper-managed (YAML) keys, highest to lowest: 1. **Command-line flags** (e.g. `--json`, `--db`, `--actor`) 2. **Environment variables** (`BD_*`, plus a small set of legacy `BEADS_*` names — see below) 3. **`config.yaml`** files (in the order listed above) 4. **Built-in defaults** Project-level keys written via `bd config set` (Jira, Linear, GitHub, status maps, etc.) live in the Dolt database. They are read at command time and have no env var override. When a config.yaml value or environment variable shadows a database key, `bd config list` prints an override warning, and `bd config show` reports the source of every effective key. [​](https://beads.gascity.com/reference/configuration#managing-configuration) Managing Configuration ------------------------------------------------------------------------------------------------------- # Set a value (auto-routes to config.yaml or the database) bd config set jira.url "https://company.atlassian.net" bd config set validation.on-create warn # YAML-only key # Set many values in one go (single auto-commit; validates before writing) bd config set-many jira.url=https://example.atlassian.net jira.project=PROJ # Get a value bd config get jira.url bd config get --json jira.url # → {"key":"jira.url","value":"https://company.atlassian.net"} # List all database-stored config (with override warnings) bd config list # Show all effective config with provenance (env / config.yaml / default / database) bd config show bd config show --source config.yaml bd config show --json # Validate sync-related configuration bd config validate # Remove a value bd config unset jira.url `bd config set` automatically routes the write to the right location: keys in the YAML namespace (see below) are written to the project `config.yaml`; everything else is written to the Dolt database. `beads.role` is stored in git config. Unrecognized keys produce a warning with a did-you-mean suggestion; use the `custom.*` namespace for user-defined keys. [​](https://beads.gascity.com/reference/configuration#yaml-only-keys-startup-settings) YAML-only Keys (Startup Settings) --------------------------------------------------------------------------------------------------------------------------- These keys must live in `config.yaml`, not the database, because they are read before the database is opened. Writing them with `bd config set` automatically updates `config.yaml`. The full namespaces routed to YAML are: `routing.*`, `sync.*`, `git.*`, `directory.*`, `repos.*`, `external_projects.*`, `validation.*`, `hierarchy.*`, `ai.*`, `backup.*`, `export.*`, `dolt.*`, `federation.*`, `metrics.*`, `list.*` Plus these individual keys: `no-db`, `json`, `db`, `actor`, `identity`, `no-push`, `no-git-ops`, `agent.profile`, `create.require-description`, `import.auto`, `import.path`, `prime.max-memories`, `prime.max-memory-chars`, and the secret keys `github.token`, `gitlab.token`, `jira.api_token`, `ado.pat`, `linear.api_key`, `linear.oauth_client_id`, `linear.oauth_client_secret`. Any key whose name contains `api_key`, `api-key`, `secret`, `token`, or `password` is treated as a secret: it is refused on git-tracked `config.yaml` files unless you pass `--force-git-tracked`. Prefer exporting the value as an environment variable instead (e.g. `LINEAR_API_KEY`). [​](https://beads.gascity.com/reference/configuration#tool-level-settings-config-yaml) Tool-Level Settings (config.yaml) --------------------------------------------------------------------------------------------------------------------------- | Setting | Flag | Env Var | Default | Description | | --- | --- | --- | --- | --- | | `json` | `--json` | `BD_JSON` | `false` | JSON output for scripting | | `db` | `--db` | `BD_DB` | (auto-discover) | Database path | | `actor` | `--actor` | `BEADS_ACTOR` | `git config user.name` | Actor name for audit trail (see [Actor identity](https://beads.gascity.com/reference/configuration#actor-identity-resolution)<br>) | | `identity` | `--identity` | `BEADS_IDENTITY` | (git user / hostname) | Sender identity for `bd mail` | | `no-db` | `--no-db` | `BD_NO_DAEMON` (related) | `false` | Run without opening the database | | `no-push` | `--no-push` | `BD_NO_PUSH` | `false` | Skip pushing to the remote in `bd dolt push` | | `no-git-ops` | — | — | `false` | Disable git ops in `bd prime` close protocol | | `agent.profile` | — | `BD_AGENT_PROFILE` | `conservative` | Policy profile `bd prime` uses for git/commit authority: `conservative`, `minimal`, `team-maintainer`; invalid values fall back to `conservative` | | `prime.max-memories` | `--max-memories` | `BD_PRIME_MAX_MEMORIES` | `0` | Max persistent memories injected by `bd prime` (0 = unlimited) | | `prime.max-memory-chars` | `--max-memory-chars` | `BD_PRIME_MAX_MEMORY_CHARS` | `0` | Max total bytes of memory entries injected by `bd prime`, at whole-memory boundaries (0 = unlimited) | | `dolt.auto-commit` | `--dolt-auto-commit` | `BD_DOLT_AUTO_COMMIT` | `on` | Create a Dolt history commit after each successful write (see [below](https://beads.gascity.com/reference/configuration#auto-commit-sql-commits-vs-dolt-commits)<br>) | | `dolt.auto-push` | — | `BD_DOLT_AUTO_PUSH` | `false` | Auto-push to Dolt remote after writes (opt-in; see [below](https://beads.gascity.com/reference/configuration#auto-push)<br>) | | `dolt.auto-push-interval` | — | `BD_DOLT_AUTO_PUSH_INTERVAL` | `5m` | Minimum time between auto-pushes | | `dolt.auto-push-timeout` | — | `BD_DOLT_AUTO_PUSH_TIMEOUT` | `30s` | Timeout for a single auto-push attempt | | `dolt.shared-server` | `--shared-server` | `BEADS_DOLT_SHARED_SERVER` | `false` | Share one Dolt server at `~/.beads/shared-server/` | | `dolt.max-conns` | — | `BEADS_DOLT_MAX_CONNS` | `10` | Connection pool size | | `git.author` | — | `BD_GIT_AUTHOR` | (none) | Override commit author for beads commits | | `git.no-gpg-sign` | — | `BD_GIT_NO_GPG_SIGN` | `false` | Disable GPG signing for beads commits | | `create.require-description` | — | `BD_CREATE_REQUIRE_DESCRIPTION` | `false` | Require description on `bd create` | | `validation.on-create` | — | `BD_VALIDATION_ON_CREATE` | `none` | Template validation: `none`, `warn`, `error` | | `validation.on-close` | — | `BD_VALIDATION_ON_CLOSE` | `none` | Template validation on close | | `validation.on-sync` | — | `BD_VALIDATION_ON_SYNC` | `none` | Template validation before sync | | `validation.metadata.mode` | — | — | `none` | Metadata schema validation | | `hierarchy.max-depth` | — | — | `3` | Max hierarchical ID nesting depth | | `backup.enabled` | — | `BD_BACKUP_ENABLED` | `false` | Enable periodic Dolt-native backup to `.beads/backup/` (see [below](https://beads.gascity.com/reference/configuration#auto-backup)<br>) | | `backup.interval` | — | `BD_BACKUP_INTERVAL` | `15m` | Minimum time between auto-backups | | `backup.git-push` | — | — | `false` | Auto-push backup repo | | `backup.git-repo` | — | `BD_BACKUP_GIT_REPO` | (none) | Backup git repo URL; when set, backups go to a `backup/` directory inside that repo | | `export.auto` | — | — | `false` | Refresh `.beads/issues.jsonl` export after every write; not cross-machine sync | | `export.path` | — | — | `issues.jsonl` | Output filename relative to `.beads/` | | `export.interval` | — | — | `60s` | Minimum time between auto-exports | | `export.git-add` | — | — | `false` | Run `git add` on the export file | | `import.auto` | — | `BD_IMPORT_AUTO` | `true` | Master switch for automatic JSONL imports: the git-hook fallback used when no Dolt remote is configured, and the empty-database recovery import when `.beads/issues.jsonl` exists but the database is empty. `false` disables all auto-imports; explicit `bd import` always works | | `import.path` | — | — | `issues.jsonl` | Input filename relative to `.beads/` for implied JSONL imports (including `bd init --from-jsonl` and empty-DB auto-import); use relative paths for portability | | `routing.mode` | — | — | (none) | Multi-repo routing: `auto`, `maintainer`, `contributor`, `explicit` | | `routing.default` | — | — | `.` | Default routing target | | `routing.maintainer` | — | — | `.` | Maintainer-routed path | | `routing.contributor` | — | — | `~/.beads-planning` | Contributor-routed path | | `list.limit` | `--limit` / `-n` | `BD_LIST_LIMIT` | `50` | Default limit for `bd list` results | | `directory.labels` | — | — | `{}` | Map directory patterns → labels for monorepos | | `external_projects` | — | — | `{}` | Map project names → paths for cross-project deps | | `federation.remote` | — | `BD_FEDERATION_REMOTE` | (none) | Dolt remote URL (`dolthub://`, `gs://`, `s3://`, `az://`, `file://`) | | `federation.sovereignty` | — | `BD_FEDERATION_SOVEREIGNTY` | (none) | Sovereignty tier: `T1`, `T2`, `T3`, `T4` (see [below](https://beads.gascity.com/reference/configuration#sync-and-federation)<br>) | | `federation.allowed-remote-patterns` | — | — | `[]` | Glob patterns restricting allowed remote URLs | | `federation.exclude_types` | — | — | `[wisp]` | Issue types excluded from federation push | | `sync.require_confirmation_on_mass_delete` | — | — | `false` | Prompt before pushing when a merge deletes most issues | | `output.title-length` | — | — | `255` | Title display in feedback (`0` hides); see routing note below | | `ai.model` | — | `BD_AI_MODEL` | `claude-haiku-4-5-20251001` | Default AI model | | `agents.file` | — | — | `AGENTS.md` | Agents instruction filename; see routing note below | **JSONL export is opt-in**`export.auto` and `export.git-add` are disabled unless configured explicitly. `.beads/issues.jsonl` is an optional export for viewers, interchange, and issue-level migration. It is not the canonical source of truth, not cross-machine sync, and not a full database backup.Workflows that depend on a fresh, git-staged JSONL file should opt in: bd config set export.auto true bd config set export.git-add true Use `bd dolt push` / `bd dolt pull` for sync and `bd backup` for restorable database backups. Routing note: `output.title-length` and `agents.file` are functionally tool-level settings, but `bd config set` writes them to the Dolt database. They are typically read from `config.yaml` when set there directly. `bd config show` is the source of truth for what’s currently effective on your machine, including provenance. [​](https://beads.gascity.com/reference/configuration#dolt-history-backup-and-push) Dolt History, Backup, and Push --------------------------------------------------------------------------------------------------------------------- Three post-write behaviors run after each successful write command, in this order: auto-commit, auto-backup, auto-push. ### [​](https://beads.gascity.com/reference/configuration#auto-commit-sql-commits-vs-dolt-commits) Auto-commit: SQL Commits vs Dolt Commits There are two different kinds of “commit”: * **SQL transaction commit** — what happens when a `bd` command updates tables successfully (durable in the Dolt _working set_). * **Dolt version-control commit** — what records those changes into Dolt _history_ (visible in `bd history`, and what push/pull/merge workflows operate on). By default (`dolt.auto-commit: on`), `bd` creates a Dolt history commit after each successful write command, so changes are never left only in the working set. The cost is more Dolt commits over time — one per write command — which is intentional; use `bd compact` to squash old history. Disable for a single command: bd --dolt-auto-commit off create "No history commit for this one" Or in `config.yaml`: dolt: auto-commit: off ### [​](https://beads.gascity.com/reference/configuration#auto-backup) Auto-backup Periodic Dolt-native backup to `.beads/backup/` provides a recovery path independent of the live database. Local Dolt commits (via `dolt.auto-commit`) remain the primary safety net; backup is a secondary layer. Unlike `bd export` or `.beads/issues.jsonl`, this is a full database backup: it preserves tables, branches, commit history, and working-set data. backup: enabled: true # Enable auto-backup after write commands interval: 15m # Minimum time between auto-backups How it works: * After each write command, `bd` compares the Dolt HEAD commit hash against the last backup state. * If data changed and the throttle interval has passed, a Dolt-native backup is synced to `.beads/backup/` (or to a `backup/` directory inside `backup.git-repo` when configured). * State is tracked in `backup_state.json` inside the backup directory. Manual commands (see [bd backup](https://beads.gascity.com/cli-reference/backup) ): bd backup init <path> # Register a destination (filesystem or DoltHub URL) bd backup sync # Push to the configured destination bd backup restore [path] # Restore from a backup (--force to overwrite) bd backup remove # Unregister the destination bd backup status # Show configuration and last sync time ### [​](https://beads.gascity.com/reference/configuration#auto-push) Auto-push By default, `bd` does not push automatically after write commands. Auto-push is explicit opt-in because concurrent pushes to git-protocol Dolt remotes can corrupt or strand remote history when multiple writers race. dolt: auto-push: true # Explicit opt-in; safe for single-writer setups auto-push-interval: 5m # Minimum time between auto-pushes auto-push-timeout: 30s # Bound one push attempt when the remote is unreachable How it works: * After each write command (after auto-commit and auto-backup), `bd` checks whether a push is due. * Pushes are debounced: skipped if the last push was less than `dolt.auto-push-interval` ago. * Change detection: skipped if the Dolt HEAD commit hasn’t changed since the last push. * Push failures are warnings only (non-fatal), and failed attempts are throttled too. * Last push time and commit are tracked in `.beads/push-state.json`, a per-machine file (not in the database, to avoid merge conflicts across machines). Before pushing, `bd` verifies the local chunk store with `dolt fsck --quiet`, bounded by a 30-second timeout. For large stores, raise it with the runtime-only `BEADS_FSCK_TIMEOUT` environment variable (accepts durations like `2m` or bare seconds like `90`). [​](https://beads.gascity.com/reference/configuration#actor-identity-resolution) Actor Identity Resolution ------------------------------------------------------------------------------------------------------------- The actor name (used for `created_by` and audit trails) is resolved in this order: 1. `--actor` flag (explicit override) 2. `BEADS_ACTOR` environment variable 3. `BD_ACTOR` environment variable (deprecated alias) 4. `git config user.name` 5. `$USER` environment variable 6. `"unknown"` (final fallback) For most developers no configuration is needed — issue authorship matches commit authorship automatically. To override, set `BEADS_ACTOR` in your shell profile: export BEADS_ACTOR="my-github-handle" [​](https://beads.gascity.com/reference/configuration#project-level-settings-database) Project-Level Settings (Database) --------------------------------------------------------------------------------------------------------------------------- These are written to the Dolt database by `bd config set` and have no env var override. Common namespaces: | Namespace | Purpose | | --- | --- | | `jira.*` | Jira integration (URL, project(s), status\_map, type\_map, custom\_fields) | | `linear.*` | Linear integration (team\_id(s), priority\_map, state\_map, label\_type\_map, relation\_map) | | `github.*` | GitHub integration (org, repo, label\_map) | | `gitlab.*` | GitLab integration | | `ado.*` | Azure DevOps integration (org, project(s), state\_map, type\_map) | | `notion.*` | Notion integration | | `custom.*` | User-defined / custom integrations | | `<tracker>.last_sync` | Updated automatically after each tracker sync; enables incremental sync | | `status.custom` | Custom statuses with optional behavior categories (see [below](https://beads.gascity.com/reference/configuration#custom-statuses-and-types)<br>) | | `types.custom` | Comma-separated list of custom issue types | | `types.infra` | Infra types routed to the wisps table instead of the versioned issues table | | `compact_tier1_days`, `compact_tier2_days` | Age thresholds in days for `bd admin compact` tier eligibility (defaults `30` and `90`) | | `issue_id_mode` | `hash` (default) \| `counter` (see [below](https://beads.gascity.com/reference/configuration#sequential-counter-ids)<br>) | | `min_hash_length`, `max_hash_length` | Adaptive ID bounds (defaults `3` and `8`) | | `max_collision_prob` | Hash ID collision tolerance (default `0.25`) | | `doctor.suppress.*` | Suppress specific `bd doctor` warnings by check slug (warnings only; errors always show) | Issue prefix (`issue_prefix`) is **not** settable via `bd config set` — use `bd init --prefix`, `bd bootstrap`, or `bd rename-prefix`. ### [​](https://beads.gascity.com/reference/configuration#custom-statuses-and-types) Custom Statuses and Types Custom statuses supplement the built-ins (`open`, `in_progress`, `blocked`, `deferred`, `closed`). Each entry is `name` or `name:category`: bd config set status.custom "in_review:active,qa_testing:wip,on_hold:frozen,archived:done" The category controls how the status behaves: | Category | In `bd ready` | In default `bd list` | | --- | --- | --- | | `active` | yes | yes | | `wip` | no | yes | | `done` | no | no (terminal) | | `frozen` | no | no (on hold) | | (none) | no | yes (backward compatible) | Custom types extend the built-in issue types: bd config set types.custom "agent,molecule,event" Use `bd statuses` and `bd types` to list everything configured. ### [​](https://beads.gascity.com/reference/configuration#sequential-counter-ids) Sequential Counter IDs By default, beads generates hash-based IDs (e.g. `bd-a3f2`). For projects that prefer short sequential IDs (`bd-1`, `bd-2`, …), enable counter mode: bd config set issue_id_mode counter bd create "First issue" -p 1 # → bd-1 bd create "Second issue" -p 2 # → bd-2 | Value | Behavior | | --- | --- | | `hash` | (default) Hash-based IDs, adaptive length, collision-safe | | `counter` | Sequential integers per prefix: `bd-1`, `bd-2`, `bd-3`, … | Counter mode behavior: * Each prefix (`bd`, `plug`, …) has its own independent counter, so multi-repo or routed setups don’t interleave. * The counter is stored atomically in the database; concurrent creates within a single Dolt session are safe. * On first use (including switching an existing repository to counter mode), the counter seeds itself from the highest existing numeric ID for that prefix, so new IDs don’t collide with old ones. * An explicit `--id` flag on `bd create` bypasses ID generation entirely; the counter is not incremented. * Counter mode applies only to regular issues, not wisps. Tradeoff — hash vs. counter: | | Hash IDs | Counter IDs | | --- | --- | --- | | Human readability | Lower (`bd-a3f2`) | Higher (`bd-1`) | | Distributed/concurrent safety | Excellent (collision-free across branches) | Needs care (counters can diverge on parallel branches) | | Predictability | Unpredictable | Sequential | | Best for | Multi-agent, multi-branch workflows | Single-writer or project-management UIs | ### [​](https://beads.gascity.com/reference/configuration#adaptive-hash-ids) Adaptive Hash IDs Hash IDs size themselves to the database: lengths start at `min_hash_length` and grow toward `max_hash_length` to keep the collision probability under `max_collision_prob`. bd config set max_collision_prob "0.01" # Stricter collision tolerance (default 0.25) bd config set min_hash_length "5" # Force minimum 5-char IDs (default 3) bd config set max_hash_length "8" # Upper bound (default 8) [​](https://beads.gascity.com/reference/configuration#sync-and-federation) Sync and Federation ------------------------------------------------------------------------------------------------- Beads syncs exclusively through Dolt remotes (`bd dolt push` / `bd dolt pull`) with cell-level merge. Use `bd export` for issue portability and `bd backup` for restorable database backups. Federation settings live in `config.yaml`: federation: remote: dolthub://myorg/beads sovereignty: T2 * `federation.remote`: Dolt remote URL (`dolthub://org/beads`, `gs://bucket/beads`, `s3://bucket/beads`, `az://account.blob.core.windows.net/container/beads`, `file://...`) * `federation.sovereignty`: data sovereignty tier: * `T1`: Full sovereignty — data never leaves controlled infrastructure * `T2`: Regional sovereignty — data stays within region/jurisdiction * `T3`: Provider sovereignty — data with trusted cloud provider * `T4`: No restrictions — data can be anywhere `bd config validate` checks the remote URL format, the sovereignty tier, `federation.allowed-remote-patterns`, and `routing.mode`. [​](https://beads.gascity.com/reference/configuration#integration-configuration) Integration Configuration ------------------------------------------------------------------------------------------------------------- Tracker settings are project-level config under the tracker’s namespace; secrets (`jira.api_token`, `linear.api_key`, `github.token`, `gitlab.token`, `ado.pat`) are YAML-routed and better supplied as environment variables. Every tracker records `<tracker>.last_sync` automatically after a sync, enabling incremental syncs. ### [​](https://beads.gascity.com/reference/configuration#jira) Jira bd config set jira.url "https://company.atlassian.net" bd config set jira.project "PROJ" bd config set jira.projects "PROJ1,PROJ2" # Multiple projects (comma-separated) export JIRA_API_TOKEN="YOUR_TOKEN" # or: bd config set jira.api_token ... # Map bd statuses to Jira statuses bd config set jira.status_map.open "To Do" bd config set jira.status_map.in_progress "In Progress" bd config set jira.status_map.closed "Done" # Map bd issue types to Jira issue types bd config set jira.type_map.bug "Bug" bd config set jira.type_map.feature "Story" bd config set jira.type_map.task "Task" # Set Jira custom fields on pushed issues bd config set jira.custom_fields.customfield_10042 '{"value":"AI Platform"}' bd config set jira.custom_fields.Story.customfield_10042 '{"value":"AI Platform"}' `jira.custom_fields.<field>` applies to every issue pushed to Jira. `jira.custom_fields.<JiraType>.<field>` applies only when the mapped Jira issue type matches `<JiraType>`; per-type fields override global fields with the same field key. Values beginning with `{` or `[` are sent as JSON (useful for select-like fields); other values are sent as strings. `jira.url`, `jira.project`/`jira.projects`, and `jira.api_token` fall back to the `JIRA_URL`, `JIRA_PROJECT`/`JIRA_PROJECTS`, and `JIRA_API_TOKEN` environment variables. See [bd jira](https://beads.gascity.com/cli-reference/jira)\ .\ \ ### \ \ [​](https://beads.gascity.com/reference/configuration#linear)\ \ Linear\ \ export LINEAR_API_KEY="lin_api_YOUR_API_KEY" # Settings → API → Personal API keys\ \ bd config set linear.team_id "team-uuid-here"\ bd config set linear.team_ids "uuid-1,uuid-2" # Multiple teams (or LINEAR_TEAM_IDS)\ \ \ When `linear.team_ids` is set, `bd linear sync` fetches issues from all listed teams; push with multiple teams configured requires an explicit `--team`. The singular `linear.team_id` remains supported. Mapping namespaces — `linear.priority_map.*` (Linear 0–4 → beads 0–4), `linear.state_map.*` (Linear state types and custom state names → beads statuses, e.g. `bd config set linear.state_map.in_review in_progress`), `linear.label_type_map.*` (Linear labels → bd issue types), and `linear.relation_map.*` (Linear relations → bd dependencies; imported only when pulling with `--relations`) — are documented with defaults in [bd linear](https://beads.gascity.com/cli-reference/linear)\ . Staleness detection: after each successful pull, `bd` writes a timestamp to `.beads/last_pull` (a local-only, per-machine file covered by the `.beads/.gitignore` template). `bd linear sync --pull-if-stale` pulls only when data is older than the threshold (`--threshold`, default 20m), and a 5-minute debounce prevents agent loops. `bd prime` and other core commands never contact Linear — run `bd linear sync --pull-if-stale` from a session-start hook to keep data fresh in agent sessions.\ \ ### \ \ [​](https://beads.gascity.com/reference/configuration#github)\ \ GitHub\ \ bd config set github.org "myorg"\ bd config set github.repo "myrepo"\ export GITHUB_TOKEN="YOUR_TOKEN" # or: bd config set github.token ...\ \ # Map bd labels to GitHub labels\ bd config set github.label_map.bug "bug"\ bd config set github.label_map.feature "enhancement"\ \ \ See [bd github](https://beads.gascity.com/cli-reference/github)\ .\ \ ### \ \ [​](https://beads.gascity.com/reference/configuration#azure-devops)\ \ Azure DevOps\ \ Connection keys (`ado.pat`, `ado.org`, `ado.project`, `ado.projects`, `ado.url`) each have an `AZURE_DEVOPS_*` environment variable equivalent; config keys take priority over env vars. When `ado.projects` is set, `bd ado sync` fetches work items from all listed projects in a single query. State maps default to the Agile process template (override with `ado.state_map.*` / `ado.type_map.*` for Scrum or CMMI), and priority mapping (ADO 1–4 ↔ beads 0–4, with backlog collapsing to low) is automatic and not configurable. Full setup, mapping tables, and sync commands: [Azure DevOps integration](https://beads.gascity.com/integrations/azure-devops)\ and [bd ado](https://beads.gascity.com/cli-reference/ado)\ .\ \ [​](https://beads.gascity.com/reference/configuration#environment-variables)\ \ Environment Variables\ -----------------------------------------------------------------------------------------------------\ \ The Viper env prefix is `BD_`. Config keys map to env vars by upper-casing and replacing `.` and `-` with `_` (e.g. `dolt.auto-commit` → `BD_DOLT_AUTO_COMMIT`, `validation.on-create` → `BD_VALIDATION_ON_CREATE`). Selected commonly-used variables:\ \ | Variable | Description |\ | --- | --- |\ | `BD_DB`, `BEADS_DB` | Database path (legacy `BEADS_DB` still honored) |\ | `BD_JSON` | Force JSON output |\ | `BD_DOLT_AUTO_COMMIT` | Override `dolt.auto-commit` (`on`/`off`) |\ | `BD_DOLT_AUTO_PUSH`, `BD_DOLT_AUTO_PUSH_INTERVAL`, `BD_DOLT_AUTO_PUSH_TIMEOUT` | Override auto-push settings |\ | `BD_BACKUP_ENABLED`, `BD_BACKUP_INTERVAL`, `BD_BACKUP_GIT_REPO` | Override backup settings |\ | `BD_AGENT_PROFILE` | Override `agent.profile` |\ | `BD_AI_MODEL` | Override AI model |\ | `BD_FEDERATION_REMOTE`, `BD_FEDERATION_SOVEREIGNTY` | Override federation settings |\ | `BD_VALIDATION_ON_CREATE` / `_ON_CLOSE` / `_ON_SYNC` | Override validation modes |\ | `BD_NO_PAGER`, `BD_PAGER` | Pager behavior |\ | `BD_NON_INTERACTIVE` | Disable prompts |\ | `BD_DEBUG` | Enable debug logging |\ | `BEADS_DIR` | Force the active beads workspace directory |\ | `BEADS_ACTOR` | Actor identity (preferred over `BD_ACTOR`, which is a deprecated alias) |\ | `BEADS_IDENTITY` | Sender identity for `bd mail` |\ | `BEADS_FSCK_TIMEOUT` | Runtime-only timeout for the pre-push `dolt fsck --quiet` integrity check (default `30s`) |\ | `BEADS_DOLT_SERVER_MODE`, `BEADS_DOLT_SHARED_SERVER`, `BEADS_DOLT_DATA_DIR`, `BEADS_DOLT_PORT`, … | Embedded/server Dolt overrides |\ \ Integration secrets follow tracker-specific conventions: `LINEAR_API_KEY`, `GITHUB_TOKEN`, `GITLAB_TOKEN`, `JIRA_API_TOKEN`, `AZURE_DEVOPS_PAT`, `ANTHROPIC_API_KEY`. These are preferred over storing the value in `config.yaml` for git-tracked projects. `bd config show` will display the source of every effective key, making overrides explicit.\ \ [​](https://beads.gascity.com/reference/configuration#security-where-secrets-live)\ \ Security: Where Secrets Live\ ------------------------------------------------------------------------------------------------------------------\ \ * Tokens and API keys are never stored in the Dolt database — database config is pushed to remotes, which would expose secrets and trip GitHub secret scanning. `bd config set` routes secret keys to the local `config.yaml` instead.\ * Writing a secret to a git-tracked `config.yaml` is refused unless you pass `--force-git-tracked`; environment variables are the safer default.\ * `bd init` writes a `.beads/.gitignore` that keeps the database directories (`embeddeddolt/`, `dolt/`), runtime files, push state, and the federation credential key out of git.\ \ [​](https://beads.gascity.com/reference/configuration#example-beads/config-yaml)\ \ Example `.beads/config.yaml`\ ----------------------------------------------------------------------------------------------------------------\ \ # Default JSON output for scripting\ json: true\ \ # Dolt history & sync\ dolt:\ auto-commit: on # Create a Dolt commit after each successful write\ auto-push: false # Opt-in for single-writer setups\ \ # Issue creation policies\ create:\ require-description: true\ \ validation:\ on-create: warn # Warn when creating issues missing required sections\ on-close: none\ on-sync: none\ \ # Git commit signing for beads commits (GH#600)\ git:\ author: "beads-bot <beads@example.com>"\ no-gpg-sign: true\ \ # Periodic Dolt-native backup to .beads/backup/\ backup:\ enabled: true\ interval: 15m\ \ # Optional auto-export of issues.jsonl after writes for viewers/interchange\ export:\ auto: false\ path: issues.jsonl\ interval: 60s\ git-add: false\ \ # Optional Dolt federation\ federation:\ remote: dolthub://myorg/beads\ sovereignty: T2\ \ # Directory-aware label scoping for monorepos (GH#541)\ directory:\ labels:\ packages/maverick: maverick\ packages/agency: agency\ \ # Cross-project dependency resolution (bd-h807)\ external_projects:\ beads: ../beads\ other-project: /absolute/path/to/other-project\ \ output:\ title-length: 255\ \ \ For machine-specific overrides that should not be committed, drop them in `.beads/config.local.yaml`; it is merged in last.\ \ [​](https://beads.gascity.com/reference/configuration#per-command-override)\ \ Per-Command Override\ ---------------------------------------------------------------------------------------------------\ \ bd --db /tmp/test.db list # Override database for one command\ bd --json --actor "ci-bot" create "Fix things" # Multiple flags\ \ \ [​](https://beads.gascity.com/reference/configuration#use-in-scripts)\ \ Use in Scripts\ ---------------------------------------------------------------------------------------\ \ Configuration is designed for scripting; every `bd config` subcommand takes `--json`:\ \ # Get one value ({"key":"jira.url","value":"..."})\ JIRA_URL=$(bd config get --json jira.url | jq -r '.value')\ \ # Get all database config as a flat object\ bd config list --json | jq -r '.["jira.project"]'\ \ \ [​](https://beads.gascity.com/reference/configuration#viewing-active-configuration)\ \ Viewing Active Configuration\ -------------------------------------------------------------------------------------------------------------------\ \ bd config show # Effective config with provenance\ bd config show --json # Machine-readable\ bd config list # Database-stored config\ bd info --json | jq '.config' # Quick snapshot\ \ \ [Reference](https://beads.gascity.com/reference)\ [Git Integration](https://beads.gascity.com/reference/git-integration)\ \ ⌘I --- # Troubleshooting - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference/troubleshooting#content-area) Common issues and solutions. For step-by-step runbooks, see the [Recovery section](https://beads.gascity.com/recovery/index) . [​](https://beads.gascity.com/reference/troubleshooting#installation-issues) Installation Issues --------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/troubleshooting#bd-command-not-found) `bd: command not found` # Check if installed which bd go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd # Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc) export PATH="$PATH:$(go env GOPATH)/bin" # Or reinstall with the recommended installer curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash ### [​](https://beads.gascity.com/reference/troubleshooting#wrong-version-of-bd-running) Wrong version of bd running If `bd version` shows an unexpected version (e.g., older than what you just installed), you likely have multiple `bd` binaries in your PATH: # Check all bd binaries in PATH which -a bd # Example output showing conflict: # /Users/you/go/bin/bd <- From go install (older) # /opt/homebrew/bin/bd <- From Homebrew (newer) # Remove the old go install version rm ~/go/bin/bd # Or remove mise-managed Go installs rm ~/.local/share/mise/installs/go/*/bin/bd # Verify which bd bd version This happens when a binary from an earlier `go install` sits in `~/go/bin/` ahead of a newer package-manager install. Choose one installation method (Homebrew recommended) and stick with it. ### [​](https://beads.gascity.com/reference/troubleshooting#zsh-killed-bd-on-macos) `zsh: killed bd` on macOS CGO/SQLite compatibility issue: CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest # Or if building from source git clone https://github.com/gastownhall/beads cd beads CGO_ENABLED=1 go build -tags gms_pure_go -o bd ./cmd/bd sudo mv bd /usr/local/bin/ Homebrew builds already enable CGO, so this shouldn’t be necessary there. If you still see crashes with the Homebrew version, please [file an issue](https://github.com/gastownhall/beads/issues) . ### [​](https://beads.gascity.com/reference/troubleshooting#permission-denied) Permission denied chmod +x $(which bd) # Or install to a user directory instead mkdir -p ~/.local/bin mv bd ~/.local/bin/ export PATH="$HOME/.local/bin:$PATH" ### [​](https://beads.gascity.com/reference/troubleshooting#antivirus-flags-bd-as-malware) Antivirus flags bd as malware Kaspersky, Windows Defender, and others sometimes flag `bd` as a generic trojan. This is a **false positive** — Go binaries commonly trigger antivirus heuristics. Verify the binary’s SHA256 checksum against the [GitHub release page](https://github.com/gastownhall/beads/releases) before adding an exclusion. See [Antivirus False Positives](https://beads.gascity.com/reference/antivirus) for per-vendor instructions. [​](https://beads.gascity.com/reference/troubleshooting#database-issues) Database Issues ------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/troubleshooting#database-not-found) Database not found # Initialize beads bd init --quiet # Or point bd at an existing .beads directory BEADS_DIR=/path/to/.beads bd list ### [​](https://beads.gascity.com/reference/troubleshooting#database-locked) Database locked # Stop the Dolt server if running (server mode) bd dolt stop # Find and kill hanging bd processes ps aux | grep bd kill <pid> # Try again bd list Do NOT remove files inside `.dolt/` directories (including `noms/LOCK`). These are Dolt-internal files — removing them WILL cause unrecoverable data corruption. Dolt manages these files itself. For high-concurrency scenarios (multiple agents), server mode (`bd init --server`) handles concurrent access natively via `dolt sql-server`. ### [​](https://beads.gascity.com/reference/troubleshooting#bd-init-refuses-to-run) `bd init` refuses to run `bd init` and `bd dolt` refuse operations that could destroy local or remote history, printing a pattern code such as `init-local-exists` or `pk-fork-refused`. Each code has a runbook — see [Recovery Playbooks](https://beads.gascity.com/recovery/init-safety) . Export first (`bd export -o backup.jsonl`) if you intend to re-initialize over existing data. ### [​](https://beads.gascity.com/reference/troubleshooting#corrupted-database) Corrupted database Distinguish **logical consistency issues** (ID collisions, wrong prefixes) from **physical database corruption** (disk failures, power loss, filesystem errors). For logical consistency issues — this is not corruption: bd doctor --fix For physical corruption, rebuild from a Dolt remote or a backup: # Move the damaged data directory aside: mv .beads/embeddeddolt .beads/embeddeddolt.backup # embedded mode (default) mv .beads/dolt .beads/dolt.backup # server mode bd init bd dolt pull # Pull from Dolt remote if configured # Or restore from a backup: # bd backup restore [path] --force See [Database Corruption](https://beads.gascity.com/recovery/database-corruption) for the full runbook. ### [​](https://beads.gascity.com/reference/troubleshooting#dolt-journal-corruption-after-restart) Dolt journal corruption after restart **Symptom (server mode):** After a system restart, `bd` reports that the Dolt server started but is not accepting connections, and `.beads/dolt-server.log` contains: possible data loss detected in journal file at offset ...: corrupted journal **Cause:** Dolt detected damaged journal blocks after an unclean shutdown. This is not the same as a stale PID, stale port, or stale lock file. `bd` will not run Dolt’s data-loss repair mode automatically. **Safe recovery when your remote is current:** # Server mode data lives at .beads/dolt; embedded mode at .beads/embeddeddolt mv .beads/dolt .beads/dolt.corrupt.$(date +%Y%m%dT%H%M%S) bd bootstrap --dry-run bd bootstrap --yes bd stats If the remote may be stale, keep the corrupt directory for forensics and inspect it with `dolt fsck` before considering `dolt fsck --revive-journal-with-data-loss`. Only use the revive path after reviewing Dolt’s data-loss warning. ### [​](https://beads.gascity.com/reference/troubleshooting#failed-to-import-issue-already-exists) `failed to import: issue already exists` You’re trying to bootstrap a database with issues that conflict with existing ones. Clear the local database and re-initialize from an export: # DESTROYS the local database — export first if unsure rm -rf .beads/embeddeddolt # embedded mode (default) rm -rf .beads/dolt # server mode bd init --from-jsonl ### [​](https://beads.gascity.com/reference/troubleshooting#import-fails-with-missing-parent-errors) Import fails with missing parent errors Errors like `parent issue bd-abc does not exist` when bootstrapping from JSONL or pulling hierarchical issues (e.g., `bd-abc.1`) mean the parent issue was deleted but children still reference it — typically after `bd delete` on a parent, a branch merge where one side deleted it, or an incomplete import. Imports accept orphans without validation by default, so the children still arrive; the error indicates the parent itself is gone. Recreate the parent (or close out the orphaned children) after the import. **Prevention:** use `bd delete --cascade` to also delete children, and review children first with `bd children <parent-id>`. ### [​](https://beads.gascity.com/reference/troubleshooting#old-data-returns-after-reset) Old data returns after reset `bd admin reset --force` only removes **local** beads data. Old issues can return from configured Dolt remotes or from other machines that push after you reset. For a complete clean slate, reset every clone (or clear the remote’s beads data) before re-running `bd init`. If you previously used the removed legacy sync-branch feature, also delete its branch and worktrees — see [Worktrees: Legacy Cleanup](https://beads.gascity.com/reference/worktrees#legacy-cleanup) . ### [​](https://beads.gascity.com/reference/troubleshooting#bd-shows-0-issues-but-the-database-has-data) `bd` shows 0 issues but the database has data **Symptom (server mode):** All `bd` commands return empty results even though your data exists. **Cause:** `bd` is connecting to a different Dolt server or database than expected — an empty “shadow” database on the wrong server. **Diagnosis:** # Check what mode and server bd is using cat .beads/metadata.json | grep -E "dolt_mode|dolt_server_port" # Run server-mode health checks bd doctor --server # Confirm what the connected database contains bd sql 'SELECT COUNT(*) FROM issues' **Fix:** ensure your Dolt server is running from the correct data directory and that `metadata.json` points at the right server and port. If a stale `.beads/dolt/` directory exists alongside an external-server configuration, it can shadow the real database — confirm your real data lives on the server before removing the stale directory. ### [​](https://beads.gascity.com/reference/troubleshooting#configured-server-unreachable-auto-start-disabled) Configured server unreachable (auto-start disabled) **Symptom (server mode):** `bd` returns “database not found on Dolt server” when the configured server is down. **Cause:** When `metadata.json` has an explicit `dolt_server_port`, bd treats the server as externally managed and intentionally disables auto-start — spawning a different server would create a shadow database. **Fix:** # Start your configured Dolt server bd dolt start # Or start manually with the correct data directory dolt sql-server --host 127.0.0.1 --port 3307 --data-dir /path/to/your/dolt/data If you want auto-start behavior, remove `dolt_server_port` from `.beads/metadata.json`. ### [​](https://beads.gascity.com/reference/troubleshooting#port-conflicts-with-multiple-projects) Port conflicts with multiple projects **Symptom (server mode):** Commands in a second project fail or connect to the wrong database, and multiple `dolt sql-server` processes are running. **Cause:** Each server-mode project starts its own Dolt server by default, which can conflict on machines with many projects. **Fix:** Enable shared server mode so all projects use a single Dolt server: # Option 1: Machine-wide (add to ~/.bashrc or ~/.zshrc) export BEADS_DOLT_SHARED_SERVER=1 # Option 2: Per-project bd config set dolt.shared-server true After enabling, existing projects may need `bd init --reinit-local -q` to create their database on the shared server. **Verify:** `bd dolt status` from any project should show the same server, port 3308, and `~/.beads/shared-server/` as the data directory. ### [​](https://beads.gascity.com/reference/troubleshooting#multiple-databases-detected-warning) Multiple databases detected warning bd warns when it finds more than one `.beads` directory in your directory hierarchy, marking the one in use with `▶` (usually the closest to your current directory). Multiple databases risk working in the wrong one or tracking the same work twice. * **Nested projects (intentional):** this is supported — just note which database is active, or pin it explicitly. * **Accidental duplicates:** export from the unwanted database (`bd export -o issue-export.jsonl`), then remove its `.beads` directory. * **Override selection:** # Point bd at a specific .beads directory (recommended) export BEADS_DIR=/path/to/.beads # Legacy method (deprecated, points at the database file directly) export BEADS_DB=/path/to/db ### [​](https://beads.gascity.com/reference/troubleshooting#circuit-breaker-%E2%80%9Cserver-appears-down-failing-fast%E2%80%9D) Circuit breaker: “server appears down, failing fast” **Symptom (server mode):** Every `bd` command fails with `dolt circuit breaker is open: server appears down, failing fast (cooldown 30s)`, persisting across repeated invocations. **Cause:** The circuit breaker tripped after repeated connection failures. Its state lives in a file under `/tmp/beads-circuit/` (named `beads-dolt-circuit-<host>-<port>[-<db>].json`, keyed on host:port) and is shared across all `bd` processes. Once tripped, all commands to that host:port are rejected until a successful probe resets it. For beads-managed local servers, `bd dolt status` reports from the server’s PID file — a “running” status does not guarantee the server is actually accepting connections on the expected port. **Diagnosis:** # Check circuit breaker state cat /tmp/beads-circuit/beads-dolt-circuit-*.json # Check if the Dolt server is actually listening lsof -i :<port> # Compare the configured port with what's running cat .beads/metadata.json | grep port **Fix:** rm /tmp/beads-circuit/beads-dolt-circuit-*.json bd dolt stop bd dolt start bd list On macOS, `/tmp` is a symlink to `/private/tmp`, which is not always cleared on restart — the state file can persist across reboots. [​](https://beads.gascity.com/reference/troubleshooting#dolt-server-issues) Dolt Server Issues ------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/troubleshooting#server-not-starting) Server not starting # Check server health bd doctor # Check server logs (server mode; embedded mode runs in-process, no server log) cat .beads/dolt-server.log # Restart the server bd dolt stop bd dolt start ### [​](https://beads.gascity.com/reference/troubleshooting#version-mismatch) Version mismatch After upgrading bd: bd dolt stop bd dolt start [​](https://beads.gascity.com/reference/troubleshooting#sync-issues) Sync Issues ----------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/troubleshooting#changes-not-syncing) Changes not syncing # Force push to Dolt remote bd dolt push # Check hooks bd hooks list ### [​](https://beads.gascity.com/reference/troubleshooting#recovery-from-backup) Recovery from backup # Restore from a Dolt backup bd backup restore [path] --force # Or pull from Dolt remote bd dolt pull ### [​](https://beads.gascity.com/reference/troubleshooting#merge-conflicts) Merge conflicts Dolt merges at the cell level, so concurrent changes conflict only when they touch the same field of the same issue. Hash-based IDs mean different issues never collide on ID. # Check for and fix Dolt conflicts bd doctor --fix # Re-push bd dolt push See [Merge Conflicts](https://beads.gascity.com/recovery/merge-conflicts) for the full runbook. [​](https://beads.gascity.com/reference/troubleshooting#git-hook-issues) Git Hook Issues ------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/troubleshooting#hooks-not-running) Hooks not running # Check if installed ls -la .git/hooks/ # Reinstall bd hooks install ### [​](https://beads.gascity.com/reference/troubleshooting#hook-errors) Hook errors # Check hook script cat .git/hooks/pre-commit # Run manually .git/hooks/pre-commit ### [​](https://beads.gascity.com/reference/troubleshooting#hook-timeout-kills-chained-pre-commit-hooks) Hook timeout kills chained pre-commit hooks **Symptom:** After `bd hooks install`, chained pre-commit hooks (eslint, prettier, ruff, etc.) stop running, with: `beads: hook 'pre-commit' timed out after 300s -- continuing without beads`. **Cause:** The beads hook shim wraps `bd hooks run` with an OS-level timeout. Since `bd hooks run` chains to your original hook internally, the timeout covers both beads’ own work and your entire hook pipeline. **Fix:** Increase the timeout (default 300 seconds): # Add to ~/.bashrc or ~/.zshrc export BEADS_HOOK_TIMEOUT=600 # 10 minutes (in seconds) ### [​](https://beads.gascity.com/reference/troubleshooting#permission-denied-on-git-hooks) Permission denied on git hooks Git hooks need execute permissions: chmod +x .git/hooks/pre-commit chmod +x .git/hooks/post-merge chmod +x .git/hooks/post-checkout ### [​](https://beads.gascity.com/reference/troubleshooting#corrupted-symlinked-claude-md) Corrupted symlinked `CLAUDE.md` **Symptom:** Git reports `CLAUDE.md` as a symlink entry (mode `120000`), but the indexed blob contains multi-line Markdown instead of a one-line symlink target. On macOS this can make clones or checkouts fail. This affects repositories corrupted by older setup behavior (fixed in [#4192](https://github.com/gastownhall/beads/pull/4192) ). To repair an existing bad index entry: # Confirm the bad entry: mode 120000 but Markdown content git ls-files -s CLAUDE.md git cat-file -p :CLAUDE.md | sed -n '1,5p' # Convert the blob to a regular tracked file without changing content sha=$(git rev-parse :CLAUDE.md) git update-index --cacheinfo 100644,$sha,CLAUDE.md git checkout-index -f -- CLAUDE.md # Verify: first column should now be 100644 git ls-files -s CLAUDE.md git diff -- CLAUDE.md Commit the mode repair after review. ### [​](https://beads.gascity.com/reference/troubleshooting#%E2%80%9Dbranch-already-checked-out%E2%80%9D-or-unexpected-git/beads-worktrees/) ”Branch already checked out” or unexpected `.git/beads-worktrees/` Older beads versions created hidden git worktrees for a removed sync-branch feature; leftovers can lock branches (`fatal: 'main' is already checked out at .../beads-worktrees/...`). Remove them: rm -rf .git/beads-worktrees rm -rf .git/worktrees/beads-* git worktree prune See [Worktrees: Legacy Cleanup](https://beads.gascity.com/reference/worktrees#legacy-cleanup) . [​](https://beads.gascity.com/reference/troubleshooting#dependency-issues) Dependency Issues ----------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/troubleshooting#bd-ready-shows-nothing-but-i-have-open-issues) `bd ready` shows nothing but I have open issues Those issues probably have open blockers: # See blocked issues bd blocked # Show the dependency tree (default max depth: 50) bd dep tree <issue-id> bd dep tree <issue-id> --max-depth 10 # Remove a blocking dependency if needed bd dep remove <from-id> <to-id> Remember: only `blocks` dependencies affect ready work. ### [​](https://beads.gascity.com/reference/troubleshooting#circular-dependencies) Circular dependencies bd prevents dependency cycles, which break ready work detection: # Detect cycles bd dep cycles # Remove one dependency bd dep remove bd-A bd-B See [Circular Dependencies](https://beads.gascity.com/recovery/circular-dependencies) for the full runbook. ### [​](https://beads.gascity.com/reference/troubleshooting#dependencies-not-showing-up) Dependencies not showing up # Show full issue details including dependencies bd show <issue-id> # Visualize the dependency tree bd dep tree <issue-id> Different dependency types have different meanings — only `blocks` gates ready work. See [Dependencies](https://beads.gascity.com/core-concepts/dependencies) . [​](https://beads.gascity.com/reference/troubleshooting#performance-issues) Performance Issues ------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/troubleshooting#slow-queries) Slow queries # Check database stats bd stats # Check on-disk size du -sh .beads/embeddeddolt # embedded mode (default) du -sh .beads/dolt # server mode # Preview compaction candidates bd admin compact --dry-run --all # Compact if large bd admin compact --analyze Consider splitting very large projects into multiple databases: cd ~/project/component1 && bd init --prefix comp1 cd ~/project/component2 && bd init --prefix comp2 ### [​](https://beads.gascity.com/reference/troubleshooting#high-memory-usage) High memory usage # Run Dolt garbage collection to compact storage bd admin compact --dolt [​](https://beads.gascity.com/reference/troubleshooting#agent-issues) Agent Issues ------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/troubleshooting#agent-creates-duplicate-issues) Agent creates duplicate issues Agents may not realize an issue already exists. Prevention strategies: * Have agents search first: `bd list --json | grep "title"` * Label auto-created issues: `bd create "..." -l auto-generated` * Consolidate duplicates: `bd duplicate <dup-id> --of <canonical-id>` closes the duplicate with a reference to the canonical issue ### [​](https://beads.gascity.com/reference/troubleshooting#agent-gets-confused-by-complex-dependencies) Agent gets confused by complex dependencies Simplify the dependency structure: # Check for overly complex trees bd dep tree <issue-id> # Remove unnecessary dependencies bd dep remove <from-id> <to-id> # Use labels instead of dependencies for loose relationships bd label add <issue-id> related-to-feature-X ### [​](https://beads.gascity.com/reference/troubleshooting#mcp-server-not-working) MCP server not working # Verify the MCP server is installed pip list | grep beads-mcp # Check MCP configuration (Claude Desktop on macOS) cat ~/Library/Application\ Support/Claude/claude_desktop_config.json # Test that the CLI itself works bd version bd ready bd doctor See [MCP Server](https://beads.gascity.com/integrations/mcp-server) for setup and configuration. ### [​](https://beads.gascity.com/reference/troubleshooting#sandboxed-environments-codex-claude-code-etc) Sandboxed environments (Codex, Claude Code, etc.) Sandboxes that restrict process and network permissions can prevent bd from controlling a Dolt server, causing persistent “database out of sync” errors or `bd dolt stop` failing with “operation not permitted”. bd auto-detects sandboxed environments and prints `Sandbox detected, using direct mode`. If auto-detection fails, pass the global `--sandbox` flag explicitly: bd --sandbox ready bd --sandbox create "Fix bug" -p 1 Sandbox mode disables Dolt auto-push so bd works without server control or network access. Sync manually once outside the sandbox: bd dolt push If staleness errors persist, `bd doctor --fix` forces a metadata refresh (low risk — it updates tracking metadata, not issues). Background: [GH#353](https://github.com/gastownhall/beads/issues/353) . [​](https://beads.gascity.com/reference/troubleshooting#platform-specific-issues) Platform-Specific Issues ------------------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/troubleshooting#windows-path-issues) Windows: Path issues # Check if bd.exe is in PATH where.exe bd # Add Go bin to PATH (permanently) [Environment]::SetEnvironmentVariable( "Path", $env:Path + ";$env:USERPROFILE\go\bin", [EnvironmentVariableTarget]::User ) # Reload PATH in current session $env:Path = [Environment]::GetEnvironmentVariable("Path", "User") ### [​](https://beads.gascity.com/reference/troubleshooting#windows-firewall-blocking-the-dolt-server) Windows: Firewall blocking the Dolt server In server mode, the Dolt server listens on loopback TCP. Allow `bd.exe` through Windows Firewall: Windows Security → Firewall & network protection → “Allow an app through firewall” → add `bd.exe` for Private networks. ### [​](https://beads.gascity.com/reference/troubleshooting#windows-controlled-folder-access-blocks-bd-init) Windows: Controlled Folder Access blocks `bd init` **Symptom:** `bd init` hangs indefinitely with high CPU usage, and CTRL+C doesn’t work. Controlled Folder Access may block bd without showing a notification, making this hard to diagnose without the `-v` flag: bd init -v # Error: failed to create .beads directory: mkdir .beads: The system cannot find the file specified **Solution:** Whitelist `bd.exe`: Windows Security → Virus & threat protection → Ransomware protection → Controlled folder access → “Allow an app through Controlled folder access” → browse to `bd.exe` (typically `%USERPROFILE%\go\bin\bd.exe`). Then retry `bd init`. ### [​](https://beads.gascity.com/reference/troubleshooting#macos-gatekeeper-blocking-execution) macOS: Gatekeeper blocking execution 1. Verify the downloaded binary checksum matches the release `checksums.txt`. 2. If you used `scripts/install.sh`, note that macOS ad-hoc re-signing is opt-in (`BEADS_INSTALL_RESIGN_MACOS=1`). 3. Approve the binary: # Remove quarantine attribute xattr -d com.apple.quarantine /usr/local/bin/bd # Or: System Preferences → Security & Privacy → General → "Allow anyway" [​](https://beads.gascity.com/reference/troubleshooting#debug-environment-variables) Debug Environment Variables ------------------------------------------------------------------------------------------------------------------- bd supports environment variables for debugging specific subsystems. Enable them when troubleshooting or when requested by maintainers. | Variable | Purpose | Output | | --- | --- | --- | | `BD_DEBUG` | General debug logging | stderr | | `BD_DEBUG_RPC` | RPC communication between CLI and Dolt server | stderr | | `BD_DEBUG_SYNC` | Sync and import timestamp protection | stderr | | `BD_DEBUG_ROUTING` | Issue routing and multi-repo resolution | stderr | | `BD_DEBUG_FRESHNESS` | Database file replacement detection | server log | Set any of them to `1` to enable; `unset` to disable. # General debugging BD_DEBUG=1 bd ready # Capture debug output to a file BD_DEBUG=1 bd dolt push 2> debug.log # Sync timestamp protection, e.g.: # [debug] Protected bd-123: local=2024-01-20T10:00:00Z >= incoming=2024-01-20T09:55:00Z BD_DEBUG_SYNC=1 bd dolt push # Freshness output goes to the server log (server mode), not stderr BD_DEBUG_FRESHNESS=1 bd dolt start tail -f .beads/dolt-server.log | grep freshness For multi-repo routing configuration, see [Routing](https://beads.gascity.com/multi-agent/routing) . [​](https://beads.gascity.com/reference/troubleshooting#getting-help) Getting Help ------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/troubleshooting#debug-output) Debug output bd --verbose list ### [​](https://beads.gascity.com/reference/troubleshooting#logs) Logs # Server mode (embedded mode runs in-process, no server log) cat .beads/dolt-server.log ### [​](https://beads.gascity.com/reference/troubleshooting#system-info) System info bd info --json ### [​](https://beads.gascity.com/reference/troubleshooting#file-an-issue) File an issue # Include this info bd version bd info --json uname -a Report at: [https://github.com/gastownhall/beads/issues](https://github.com/gastownhall/beads/issues) — or ask in [GitHub Discussions](https://github.com/gastownhall/beads/discussions) . [Observability (OpenTelemetry)](https://beads.gascity.com/reference/observability) [Antivirus False Positives](https://beads.gascity.com/reference/antivirus) ⌘I --- # Labels - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/core-concepts/labels#content-area) Labels provide flexible, multi-dimensional categorization for issues beyond the structured fields (status, priority, type). Use labels for cross-cutting concerns, technical metadata, and contextual tagging without schema changes. [​](https://beads.gascity.com/core-concepts/labels#design-philosophy) Design Philosophy ------------------------------------------------------------------------------------------ **When to use labels vs. structured fields:** * **Structured fields** (status, priority, type) → Core workflow state * Status: Where the issue is in the workflow (`open`, `in_progress`, `blocked`, `closed`) * Priority: How urgent (0-4) * Type: What kind of work (`bug`, `feature`, `task`, `epic`, `chore`) * **Labels** → Everything else * Technical metadata (`backend`, `frontend`, `api`, `database`) * Domain/scope (`auth`, `payments`, `search`, `analytics`) * Effort estimates (`small`, `medium`, `large`) * Quality gates (`needs-review`, `needs-tests`, `breaking-change`) * Team/ownership (`team-infra`, `team-product`) * Release tracking (`v1.0`, `v2.0`, `backport-candidate`) [​](https://beads.gascity.com/core-concepts/labels#quick-start) Quick Start ------------------------------------------------------------------------------ # Add labels when creating issues bd create "Fix auth bug" -t bug -p 1 -l auth,backend,urgent # Add labels to existing issues bd label add bd-42 security bd label add bd-42 breaking-change # Add multiple labels at once (comma-separated, no spaces around commas) bd label add bd-42 security,breaking-change # List issue labels bd label list bd-42 # Remove a label bd label remove bd-42 urgent # Remove multiple labels at once bd label remove bd-42 urgent,needs-review # List all labels in use bd label list-all # Filter by labels (AND - must have ALL) bd list --label backend,auth # Filter by labels (OR - must have AT LEAST ONE) bd list --label-any frontend,backend # Combine filters bd list --status open --priority 1 --label security [​](https://beads.gascity.com/core-concepts/labels#common-label-patterns) Common Label Patterns -------------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/labels#1-technical-component-labels) 1\. Technical Component Labels Identify which part of the system: backend frontend api database infrastructure cli ui mobile **Example:** bd create "Add GraphQL endpoint" -t feature -p 2 -l backend,api bd create "Update login form" -t task -p 2 -l frontend,auth,ui ### [​](https://beads.gascity.com/core-concepts/labels#2-domain/feature-area) 2\. Domain/Feature Area Group by business domain: auth payments search analytics billing notifications reporting admin **Example:** bd list --label payments --status open # All open payment issues bd list --label-any auth,security # Security-related work ### [​](https://beads.gascity.com/core-concepts/labels#3-size/effort-estimates) 3\. Size/Effort Estimates Quick effort indicators: small # < 1 day medium # 1-3 days large # > 3 days **Example:** # Find small quick wins bd ready --json | jq '.[] | select(.labels[] == "small")' ### [​](https://beads.gascity.com/core-concepts/labels#4-quality-gates) 4\. Quality Gates Track what’s needed before closing: needs-review needs-tests needs-docs breaking-change **Example:** bd label add bd-42 needs-review bd list --label needs-review --status in_progress ### [​](https://beads.gascity.com/core-concepts/labels#5-release-management) 5\. Release Management Track release targeting: v1.0 v2.0 backport-candidate release-blocker **Example:** bd list --label v1.0 --status open # What's left for v1.0? bd label add bd-42 release-blocker ### [​](https://beads.gascity.com/core-concepts/labels#6-team/ownership) 6\. Team/Ownership Indicate ownership or interest: team-infra team-product team-mobile needs-triage help-wanted **Example:** bd list --assignee alice --label team-infra bd create "Memory leak in cache" -t bug -p 1 -l team-infra,help-wanted ### [​](https://beads.gascity.com/core-concepts/labels#7-special-markers) 7\. Special Markers Process or workflow flags: auto-generated # Created by automation discovered-from # Found during other work (also a dep type) technical-debt good-first-issue duplicate wontfix **Example:** bd create "TODO: Refactor parser" -t chore -p 3 -l technical-debt,auto-generated [​](https://beads.gascity.com/core-concepts/labels#filtering-by-labels) Filtering by Labels ---------------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/labels#and-filtering-%E2%80%94label) AND Filtering (—label) All specified labels must be present: # Issues that are BOTH backend AND urgent bd list --label backend,urgent # Open bugs that need review AND tests bd list --status open --type bug --label needs-review,needs-tests ### [​](https://beads.gascity.com/core-concepts/labels#or-filtering-%E2%80%94label-any) OR Filtering (—label-any) At least one specified label must be present: # Issues in frontend OR backend bd list --label-any frontend,backend # Security or auth related bd list --label-any security,auth ### [​](https://beads.gascity.com/core-concepts/labels#combining-and/or) Combining AND/OR Mix both filters for complex queries: # Backend issues that are EITHER urgent OR a blocker bd list --label backend --label-any urgent,release-blocker # Frontend work that needs BOTH review and tests, but in any component bd list --label needs-review,needs-tests --label-any frontend,ui,mobile [​](https://beads.gascity.com/core-concepts/labels#workflow-examples) Workflow Examples ------------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/core-concepts/labels#triage-workflow) Triage Workflow # Create untriaged issue bd create "Crash on login" -t bug -p 1 -l needs-triage # During triage, add context bd label add bd-42 auth bd label add bd-42 backend bd label add bd-42 urgent bd label remove bd-42 needs-triage # Find untriaged issues bd list --label needs-triage ### [​](https://beads.gascity.com/core-concepts/labels#quality-gate-workflow) Quality Gate Workflow # Start work bd update bd-42 --claim # Mark quality requirements bd label add bd-42 needs-tests bd label add bd-42 needs-docs # Before closing, verify bd label list bd-42 # ... write tests and docs ... bd label remove bd-42 needs-tests bd label remove bd-42 needs-docs # Close when gates satisfied bd close bd-42 ### [​](https://beads.gascity.com/core-concepts/labels#release-planning) Release Planning # Tag issues for v1.0 bd label add bd-42 v1.0 bd label add bd-43 v1.0 bd label add bd-44 v1.0 # Track v1.0 progress bd list --label v1.0 --status closed # Done bd list --label v1.0 --status open # Remaining bd stats # Overall progress # Mark critical items bd label add bd-45 v1.0 bd label add bd-45 release-blocker ### [​](https://beads.gascity.com/core-concepts/labels#component-based-work-distribution) Component-Based Work Distribution # Backend team picks up work bd ready --json | jq '.[] | select(.labels[]? == "backend")' # Frontend team finds small tasks bd list --status open --label frontend,small # Find help-wanted items for new contributors bd list --label help-wanted,good-first-issue [​](https://beads.gascity.com/core-concepts/labels#label-management) Label Management ---------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/labels#listing-labels) Listing Labels # Labels on a specific issue bd label list bd-42 # All labels in database with usage counts bd label list-all # JSON output for scripting bd label list-all --json Output: [\ {"label": "auth", "count": 5},\ {"label": "backend", "count": 12},\ {"label": "frontend", "count": 8}\ ] ### [​](https://beads.gascity.com/core-concepts/labels#bulk-operations) Bulk Operations Add labels in batch during creation: bd create "Issue" -l label1,label2,label3 Script to add label to multiple issues: # Add "needs-review" to all in_progress issues bd list --status in_progress --json | jq -r '.[].id' | while read id; do bd label add "$id" needs-review done Remove label from multiple issues: # Remove "urgent" from closed issues bd list --status closed --label urgent --json | jq -r '.[].id' | while read id; do bd label remove "$id" urgent done [​](https://beads.gascity.com/core-concepts/labels#integration-with-git-workflow) Integration with Git Workflow ------------------------------------------------------------------------------------------------------------------ Labels are stored in the Dolt database and synced automatically with all issue data: # Make changes bd create "Fix bug" -l backend,urgent bd label add bd-42 needs-review # Changes are committed to Dolt history automatically # Sync with remotes when ready: bd dolt push # After pulling changes: bd dolt pull bd list --label backend # Fresh data including labels [​](https://beads.gascity.com/core-concepts/labels#markdown-import/export) Markdown Import/Export ---------------------------------------------------------------------------------------------------- Labels are preserved when importing from markdown: # Fix Authentication Bug ### Type bug ### Priority 1 ### Labels auth, backend, urgent, needs-review ### Description Users can't log in after recent deployment. bd create -f issue.md # Creates issue with all four labels [​](https://beads.gascity.com/core-concepts/labels#best-practices) Best Practices ------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/core-concepts/labels#1-establish-conventions-early) 1\. Establish Conventions Early Document your team’s label taxonomy: # Add to project README or CONTRIBUTING.md - Use lowercase, hyphen-separated (e.g., `good-first-issue`) - Prefix team labels (e.g., `team-infra`, `team-product`) - Use consistent size labels (`small`, `medium`, `large`) ### [​](https://beads.gascity.com/core-concepts/labels#2-don%E2%80%99t-overuse-labels) 2\. Don’t Overuse Labels Labels are flexible, but too many can cause confusion. Prefer: * 5-10 core technical labels (`backend`, `frontend`, `api`, etc.) * 3-5 domain labels per project * Standard process labels (`needs-review`, `needs-tests`) * Release labels as needed ### [​](https://beads.gascity.com/core-concepts/labels#3-clean-up-unused-labels) 3\. Clean Up Unused Labels Periodically review: bd label list-all # Remove obsolete labels from issues ### [​](https://beads.gascity.com/core-concepts/labels#4-use-labels-for-filtering-not-search) 4\. Use Labels for Filtering, Not Search Labels are for categorization, not free-text search: * ✅ Good: `backend`, `auth`, `urgent` * ❌ Bad: `fix-the-login-bug`, `john-asked-for-this` ### [​](https://beads.gascity.com/core-concepts/labels#5-combine-with-dependencies) 5\. Combine with Dependencies Labels + dependencies = powerful organization: # Epic with labeled subtasks bd create "Auth system rewrite" -t epic -p 1 -l auth,v2.0 bd create "Implement JWT" -t task -p 1 -l auth,backend --deps parent-child:bd-42 bd create "Update login UI" -t task -p 1 -l auth,frontend --deps parent-child:bd-42 # Find all v2.0 auth work bd list --label auth,v2.0 [​](https://beads.gascity.com/core-concepts/labels#ai-agent-usage) AI Agent Usage ------------------------------------------------------------------------------------ Labels are especially useful for AI agents managing complex workflows: # Auto-label discovered work bd create "Found TODO in auth.go" -t task -p 2 -l auto-generated,technical-debt # Filter for agent review bd list --label needs-review --status in_progress --json # Track automation metadata bd label add bd-42 ai-generated bd label add bd-42 needs-human-review Example agent workflow: # Agent discovers issues during refactor bd create "Extract validateToken function" -t chore -p 2 \ -l technical-debt,backend,auth,small \ --deps discovered-from:bd-10 # Agent marks work for review bd update bd-42 --claim # ... agent does work ... bd label add bd-42 needs-review bd label add bd-42 ai-generated # Human reviews and approves bd label remove bd-42 needs-review bd label add bd-42 approved bd close bd-42 [​](https://beads.gascity.com/core-concepts/labels#labels-as-state-cache) Labels as State Cache -------------------------------------------------------------------------------------------------- Labels can cache operational state for fast queries, enabling patterns where beads track both immutable history (events) and current state (labels). ### [​](https://beads.gascity.com/core-concepts/labels#the-pattern) The Pattern **Convention:** `<dimension>:<value>` Examples: * `patrol:muted` / `patrol:active` - patrol suppression state * `mode:degraded` / `mode:normal` - operational mode * `status:idle` / `status:working` - worker status * `health:healthy` / `health:failing` - component health **Implementation:** 1. Create an event bead (full context, immutable history) 2. Update the role bead’s labels (current state cache) # Event: Full record of what happened and why bd create "Muted patrol: user requested during debugging" -t event \ -l event-type:patrol-muted,actor:observer,reason:user-request # State: Update the role bead's label to reflect current state bd label remove beads/observer patrol:active bd label add beads/observer patrol:muted **Key principle:** Events are the source of truth. Labels are a cache for fast queries. ### [​](https://beads.gascity.com/core-concepts/labels#why-this-pattern) Why This Pattern? **Fast queries without event scanning:** # Without labels-as-state: scan all events to find current patrol state bd list --type event | grep "patrol" | tail -1 # Slow, fragile # With labels-as-state: direct query bd show beads/observer | grep "patrol:" # Instant **History preserved:** # When was patrol muted? Why? Who did it? bd list --label event-type:patrol-muted --type event **State recovery:** # If labels get corrupted, rebuild from events bd list --type event --label event-type:patrol-muted | tail -1 # Then re-apply the label ### [​](https://beads.gascity.com/core-concepts/labels#common-state-dimensions) Common State Dimensions | Dimension | Values | Use Case | | --- | --- | --- | | `patrol:` | `active`, `muted` | Patrol cycle suppression | | `mode:` | `normal`, `degraded`, `maintenance` | Operational mode | | `status:` | `idle`, `working`, `blocked` | Worker activity | | `health:` | `healthy`, `warning`, `failing` | Component health | | `lock:` | `unlocked`, `locked` | Exclusive access control | ### [​](https://beads.gascity.com/core-concepts/labels#state-transitions) State Transitions Always create an event before changing state labels: # Function to transition state with audit trail transition_state() { local role="$1" local dimension="$2" local old_value="$3" local new_value="$4" local reason="$5" # Record the transition bd create "State change: $dimension $old_value → $new_value" -t event \ -l "event-type:state-change,dimension:$dimension,from:$old_value,to:$new_value" # Update the cache bd label remove "$role" "$dimension:$old_value" bd label add "$role" "$dimension:$new_value" } # Usage transition_state beads/observer patrol active muted "User debugging session" ### [​](https://beads.gascity.com/core-concepts/labels#querying-state) Querying State # Current state of a role bd label list beads/observer | grep ":" # All roles in a specific state bd list --label patrol:muted # Roles NOT in expected state bd list --label-any mode:degraded,health:failing # History of state changes bd list --type event --label event-type:state-change ### [​](https://beads.gascity.com/core-concepts/labels#best-practices-2) Best Practices 1. **Use namespaced dimensions** - Prefix with role type if ambiguous 2. **Keep value sets small** - 2-4 values per dimension 3. **Document valid values** - List allowed values in role docs 4. **Always create events first** - Never update labels without history 5. **Treat labels as ephemeral** - Rebuild from events if corrupted ### [​](https://beads.gascity.com/core-concepts/labels#future-helpers) Future Helpers The pattern suggests helper commands (see bd-7l67): # Query current state bd state beads/observer patrol # → "muted" # Transition with automatic event creation bd set-state beads/observer patrol=active --reason "Debugging complete" Until helpers exist, use the manual pattern above. [​](https://beads.gascity.com/core-concepts/labels#advanced-patterns) Advanced Patterns ------------------------------------------------------------------------------------------ ### [​](https://beads.gascity.com/core-concepts/labels#component-matrix) Component Matrix Track issues across multiple dimensions: # Backend + auth + high priority bd list --label backend,auth --priority 1 # Any frontend work that's small bd list --label-any frontend,ui --label small # Critical issues across all components bd list --priority 0 --label-any backend,frontend,infrastructure ### [​](https://beads.gascity.com/core-concepts/labels#sprint-planning) Sprint Planning # Label issues for sprint for id in bd-42 bd-43 bd-44 bd-45; do bd label add "$id" sprint-12 done # Track sprint progress bd list --label sprint-12 --status closed # Velocity bd list --label sprint-12 --status open # Remaining bd stats | grep "In Progress" # Current WIP ### [​](https://beads.gascity.com/core-concepts/labels#technical-debt-tracking) Technical Debt Tracking # Mark debt bd create "Refactor legacy parser" -t chore -p 3 -l technical-debt,large # Find debt to tackle bd list --label technical-debt --label small bd list --label technical-debt --priority 1 # High-priority debt ### [​](https://beads.gascity.com/core-concepts/labels#breaking-change-coordination) Breaking Change Coordination # Identify breaking changes bd label add bd-42 breaking-change bd label add bd-42 v2.0 # Find all breaking changes for next major release bd list --label breaking-change,v2.0 # Ensure they're documented bd list --label breaking-change --label needs-docs [​](https://beads.gascity.com/core-concepts/labels#operational-state-pattern-labels-as-cache) Operational State Pattern (Labels as Cache) -------------------------------------------------------------------------------------------------------------------------------------------- For orchestration systems, labels can cache the current operational state of “role beads” (issues representing agents or system components). This enables fast state queries without scanning event history. ### [​](https://beads.gascity.com/core-concepts/labels#convention-%3Cdimension%3E%3Cvalue%3E) Convention: `<dimension>:<value>` Use colon-separated labels with a dimension prefix and value suffix: patrol:muted patrol:active mode:degraded mode:normal status:idle status:working health:healthy health:failing ### [​](https://beads.gascity.com/core-concepts/labels#the-pattern-2) The Pattern 1. **Create an event bead** with full context (immutable, audit trail) 2. **Update the role bead’s labels** to reflect current state (fast lookup) # 1. Record the event (source of truth) bd create "Muted patrol for agent-abc" -t event \ --parent agent-abc \ -d "Reason: investigating stuck worker. Expected duration: 30m" # 2. Update the cached state label bd label remove agent-abc patrol:active bd label add agent-abc patrol:muted ### [​](https://beads.gascity.com/core-concepts/labels#why-this-pattern-2) Why This Pattern? **Events are source of truth. Labels are cache.** | Approach | Events Only | Labels as Cache | | --- | --- | --- | | Query current state | Scan all events, find latest | `bd list --label patrol:muted` | | Query state history | Natural (all events exist) | Query events | | Audit trail | Complete | Complete (events still exist) | | Performance | O(n) events | O(1) label lookup | The pattern gives you both: complete history via events, fast queries via labels. ### [​](https://beads.gascity.com/core-concepts/labels#example-agent-role-states) Example: Agent Role States # Create a role bead for an agent bd create "witness-alpha" -t role -l patrol:active,mode:normal,health:healthy # Agent enters degraded mode bd create "Degraded: high error rate" -t event --parent witness-alpha \ -d "Error rate exceeded 5%. Reducing poll frequency." bd label remove witness-alpha mode:normal bd label add witness-alpha mode:degraded # Query current state bd list --label mode:degraded --type role # All degraded roles # Agent recovers bd create "Recovered: error rate normal" -t event --parent witness-alpha bd label remove witness-alpha mode:degraded bd label add witness-alpha mode:normal ### [​](https://beads.gascity.com/core-concepts/labels#common-dimensions) Common Dimensions | Dimension | Values | Use Case | | --- | --- | --- | | `patrol` | `active`, `muted`, `suspended` | Agent patrol cycles | | `mode` | `normal`, `degraded`, `maintenance` | Operational modes | | `status` | `idle`, `working`, `blocked` | Work state | | `health` | `healthy`, `warning`, `failing` | Health checks | | `sync` | `current`, `stale`, `syncing` | Sync state | ### [​](https://beads.gascity.com/core-concepts/labels#best-practices-3) Best Practices 1. **Always create the event first** - Labels are cache; events are truth 2. **Remove old value before adding new** - Prevents dimension:value1 + dimension:value2 conflicts 3. **Use consistent dimension names** - Establish team conventions early 4. **Keep dimensions orthogonal** - patrol and mode are independent concerns ### [​](https://beads.gascity.com/core-concepts/labels#querying-state-2) Querying State # Find all muted patrols bd list --label patrol:muted # Find healthy agents in normal mode bd list --label health:healthy,mode:normal # Find any non-healthy agents bd list --label-any health:warning,health:failing # Get state for a specific role bd label list witness-alpha # Output: patrol:active, mode:normal, health:healthy ### [​](https://beads.gascity.com/core-concepts/labels#helper-commands) Helper Commands For convenience, use these helpers: # Query a specific dimension bd state witness-alpha patrol # Output: active # List all state dimensions bd state list witness-alpha # Output: # patrol: active # mode: normal # health: healthy # Set state (creates event + updates label atomically) bd set-state witness-alpha patrol=muted --reason "Investigating issue" The `set-state` command atomically: 1. Creates an event bead with the reason (source of truth) 2. Removes the old dimension label if present 3. Adds the new dimension:value label (cache) See [bd set-state](https://beads.gascity.com/cli-reference/set-state) for full command reference. [​](https://beads.gascity.com/core-concepts/labels#troubleshooting) Troubleshooting -------------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/core-concepts/labels#labels-not-showing-in-list) Labels Not Showing in List Labels require explicit fetching. The `bd list` command shows issues but not labels in human output (only in JSON). # See labels in JSON bd list --json | jq '.[] | {id, labels}' # See labels for specific issue bd show bd-42 --json | jq '.labels' bd label list bd-42 ### [​](https://beads.gascity.com/core-concepts/labels#label-filtering-not-working) Label Filtering Not Working Check label names for exact matches (case-sensitive): # These are different labels: bd label add bd-42 Backend # Capital B bd list --label backend # Won't match # List all labels to see exact names bd label list-all ### [​](https://beads.gascity.com/core-concepts/labels#syncing-labels) Syncing Labels Labels are stored in the Dolt database. If labels seem out of sync: # Pull from Dolt remote bd dolt pull # Or run doctor to diagnose bd doctor [​](https://beads.gascity.com/core-concepts/labels#see-also) See Also ------------------------------------------------------------------------ * [README.md](https://github.com/gastownhall/beads/blob/main/README.md) - Main documentation * [AGENTS.md](https://github.com/gastownhall/beads/blob/main/AGENTS.md) - AI agent integration guide * [Advanced Features](https://beads.gascity.com/reference/advanced) - Advanced features and configuration [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts) [Issue Metadata](https://beads.gascity.com/core-concepts/metadata) ⌘I --- # FAQ - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/reference/faq#content-area) [​](https://beads.gascity.com/reference/faq#general) General --------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#what-is-beads) What is beads? Beads (`bd`) is a lightweight, Dolt-backed issue tracker designed for AI coding agents. It provides dependency-aware task management with built-in sync across machines, so agents and humans can collaborate from the same task graph. See [Core Concepts](https://beads.gascity.com/core-concepts/index) for the full model. ### [​](https://beads.gascity.com/reference/faq#why-beads-instead-of-github-issues-or-jira) Why beads instead of GitHub Issues or Jira? GitHub Issues plus the `gh` CLI can approximate some features, but hosted trackers fundamentally cannot replicate what AI agents need: | Capability | beads | GitHub Issues | | --- | --- | --- | | Typed dependencies | Core types (`blocks`, `related`, `parent-child`, `discovered-from`) plus workflow and knowledge-graph edges | Only “blocks/blocked by” links; no semantic enforcement, no `discovered-from` for agent work discovery | | Ready-work detection | `bd ready` computes transitive blocking offline in milliseconds | No built-in “ready” concept; requires custom GraphQL plus a sync service | | Offline-first task memory | Works offline; issues live in a local, version-controlled database; hash IDs prevent collisions on merge | Cloud-first; requires network and auth; no branch-scoped task state | | Conflicts and duplicates | Automatic collision resolution; duplicate merge with dependency consolidation and reference rewriting | Manual close-as-duplicate; no safe bulk merge, no cross-reference updates | | Local SQL database | Full SQL queries against a local Dolt database with native version control | No local database; data must be mirrored externally | | Agent-native APIs | Consistent `--json` on all commands; dedicated MCP server with workspace detection | Mixed JSON/text output; no agent-focused MCP layer | When to use each: GitHub Issues and Jira excel for human teams working in a web UI with cross-repo dashboards and integrations. Beads excels for AI agents that need offline, version-controlled task memory with graph semantics and deterministic queries. The two can also coexist — beads syncs bidirectionally with GitHub, Jira, and Linear (see [Migration](https://beads.gascity.com/reference/faq#migration) ). ### [​](https://beads.gascity.com/reference/faq#how-is-beads-different-from-taskwarrior) How is beads different from Taskwarrior? Taskwarrior is excellent for personal task management, but beads is built for AI agents: * **Agent semantics**: the `discovered-from` dependency type, `bd ready` for queue management * **JSON-first design**: every command has `--json` output * **Built-in sync**: version-controlled storage with native push/pull, no separate sync server to run * **Cell-level merge**: concurrent changes merge automatically at the field level * **SQL database**: full SQL queries against the Dolt database ### [​](https://beads.gascity.com/reference/faq#can-i-use-beads-without-ai-agents) Can I use beads without AI agents? Absolutely. Beads is a good CLI issue tracker for humans too — `bd ready` is useful for anyone managing dependencies. Think of it as “Taskwarrior meets git.” ### [​](https://beads.gascity.com/reference/faq#what-does-%E2%80%9Cbeads%E2%80%9D-stand-for) What does “beads” stand for? Nothing specific — it’s a metaphor for linked work items, like beads on a string. ### [​](https://beads.gascity.com/reference/faq#is-beads-production-ready) Is beads production-ready? Beads is a 1.x product used in production for AI-assisted development. The core functionality — create, update, dependencies, ready work, Dolt-backed sync — is stable, and releases follow semantic versioning. Data stays portable: `bd export` produces human-readable JSONL, and `bd backup` pushes Dolt-native backups. As with any tracker holding work you care about, keep normal backup hygiene (a Dolt remote or a `bd backup` destination). [​](https://beads.gascity.com/reference/faq#architecture) Architecture ------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#why-dolt-instead-of-plain-sqlite-or-flat-files) Why Dolt instead of plain SQLite or flat files? Dolt is a version-controlled SQL database — git semantics at the database level: * **Version-controlled SQL**: full SQL queries with branch, diff, and merge built in * **Cell-level merge**: concurrent changes merge automatically at the field level * **No separate sync format**: `bd dolt push` / `bd dolt pull` move history natively * **Multi-writer**: server mode supports concurrent agents * **Portable**: `bd export` produces JSONL for migration and interoperability See [Dolt architecture](https://beads.gascity.com/architecture/dolt) for the detailed analysis. ### [​](https://beads.gascity.com/reference/faq#why-hash-based-ids-instead-of-sequential) Why hash-based IDs instead of sequential? Sequential IDs (`#1`, `#2`) collide the moment two agents or two branches create issues concurrently — both mint the same next number, and the merge produces two different issues with one ID. Hash IDs like `bd-a1b2` are globally unique without coordination: # Branch A bd create "Add OAuth" # bd-a1b2 # Branch B bd create "Add Stripe" # bd-f14c — no collision git merge feature-auth # clean merge, distinct IDs IDs start at 3 characters and grow automatically (up to 8) as the database grows, keeping the collision probability under a fixed threshold. See [Hash IDs](https://beads.gascity.com/core-concepts/hash-ids) and [Adaptive IDs](https://beads.gascity.com/core-concepts/adaptive-ids) , or the [collision math](https://github.com/gastownhall/beads/blob/main/engdocs/COLLISION_MATH.md) if you want the numbers. ### [​](https://beads.gascity.com/reference/faq#what-are-hierarchical-child-ids) What are hierarchical child IDs? Hierarchical IDs (`bd-a3f8e9.1`, `bd-a3f8e9.2`) give epics and their subtasks human-readable structure: bd create "Auth System" -t epic # bd-a3f8e9 bd create "Login UI" --parent bd-a3f8e9 # bd-a3f8e9.1 bd create "Validation" --parent bd-a3f8e9 # bd-a3f8e9.2 The parent hash keeps the namespace unique across epics, the child numbers stay human-friendly, and up to 3 levels of nesting are supported. Use them for work breakdown structures; for cross-cutting relationships, use `bd dep add` instead. See [Hash IDs](https://beads.gascity.com/core-concepts/hash-ids) . ### [​](https://beads.gascity.com/reference/faq#embedded-mode-or-server-mode-%E2%80%94-which-am-i-running) Embedded mode or server mode — which am I running? The default `bd init` uses **embedded mode**: Dolt runs in-process inside `bd`, data lives at `.beads/embeddeddolt/`, and there is no server, port, or PID file to manage. This is the right mode for solo work, CI/CD, and single-agent setups. **Server mode** (`bd init --server`) connects to a running `dolt sql-server` and stores data at `.beads/dolt/`. Switch to it when multiple processes need concurrent write access to the same database — for example several agents on one machine. See [Dolt architecture](https://beads.gascity.com/architecture/dolt) for setup and migration between modes. [​](https://beads.gascity.com/reference/faq#usage) Usage ----------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#should-i-run-bd-init-myself-or-have-my-agent-do-it) Should I run bd init myself or have my agent do it? Either works — use the right flag: bd init # Humans: interactive, prompts for git hooks bd init --quiet # Agents: non-interactive, auto-installs hooks For an existing project, clone and run `bd init`; it creates the Dolt database and pulls from the configured remote. For a new project, run `bd init`, then commit the `.beads/` directory. ### [​](https://beads.gascity.com/reference/faq#how-do-i-sync-issues-across-machines) How do I sync issues across machines? bd dolt push # Push changes to the Dolt remote bd dolt pull # Pull changes from the Dolt remote `bd init` auto-configures your git origin as the Dolt remote when present; use `bd init --remote <url>` for an explicit remote. See [Sync Setup](https://beads.gascity.com/getting-started/sync-setup) . ### [​](https://beads.gascity.com/reference/faq#do-i-need-to-run-export/import-manually) Do I need to run export/import manually? No. All writes go directly to the Dolt database and are committed to Dolt history automatically; `bd dolt push` / `bd dolt pull` handle sync. `bd export` exists for portability and interchange — `.beads/issues.jsonl` is a passive export, never the database. For backups, use `bd backup init <path>` / `bd backup sync` / `bd backup restore`. See [Sync Concepts](https://beads.gascity.com/core-concepts/sync-concepts) for the full model and the sync patterns to avoid. ### [​](https://beads.gascity.com/reference/faq#what-if-my-database-feels-stale-after-a-colleague-pushes-changes) What if my database feels stale after a colleague pushes changes? bd dolt pull # Fetch and merge updates from the Dolt remote bd ready # Shows fresh data For federation setups, `bd federation sync` syncs with all configured peers. See [Federation](https://beads.gascity.com/multi-agent/federation) . ### [​](https://beads.gascity.com/reference/faq#how-do-i-handle-merge-conflicts) How do I handle merge conflicts? Dolt merges at the cell level, so most concurrent changes resolve automatically. Importing an issue with the same ID but different fields is an update, not a collision — hash IDs are stable, so same ID means same issue. If `bd dolt pull` does report conflicts: bd doctor --fix bd dolt push See the [merge conflicts runbook](https://beads.gascity.com/recovery/merge-conflicts) . ### [​](https://beads.gascity.com/reference/faq#can-i-track-issues-for-multiple-projects) Can I track issues for multiple projects? Yes — each project is completely isolated: cd ~/project1 && bd init --prefix proj1 cd ~/project2 && bd init --prefix proj2 Each project gets its own `.beads/` directory and database, and `bd` auto-discovers the right one by walking up from your current directory (like git). To link work across projects, hydrate the other repo into your database (`bd repo add`, then `bd repo sync`) and add normal dependencies, or depend on another project’s capability with an `external:<project>:<capability>` target — see [cross-repo routing](https://beads.gascity.com/multi-agent/routing) . In server mode, each project runs its own Dolt server by default. On machines with many projects you can opt into a single shared server (`bd init --shared-server`, or `export BEADS_DOLT_SHARED_SERVER=1`) that serves every project from `~/.beads/shared-server/`. See [Dolt architecture](https://beads.gascity.com/architecture/dolt) . ### [​](https://beads.gascity.com/reference/faq#can-multiple-agents-work-on-the-same-repo) Can multiple agents work on the same repo? Yes — that’s what beads was designed for. Hash IDs prevent collisions, and assignment tracks who’s working on what: bd ready --assignee agent-name # Query ready work for an agent bd update bd-a1b2 --claim # Atomically claim an issue (assignee + in_progress) bd create "Found issue" --deps discovered-from:bd-a1b2 # Track discovered work In orchestrated workflows an orchestrator usually assigns work (`bd assign`); agents picking work directly should use the atomic `--claim`. For multiple concurrent processes on one machine, use server mode; for distributed setups, Dolt’s cell-level merge and [federation](https://beads.gascity.com/multi-agent/federation) let agents work independently and merge like developers do. See [Agent Coordination](https://beads.gascity.com/multi-agent/coordination) . ### [​](https://beads.gascity.com/reference/faq#does-beads-work-offline) Does beads work offline? Yes — beads is offline-first. All queries run against the local Dolt database, no command needs the network, and sync happens via `bd dolt push` / `bd dolt pull` when you’re online. That makes it suitable for planes, unstable connections, air-gapped environments, and privacy-sensitive projects. ### [​](https://beads.gascity.com/reference/faq#how-do-i-use-beads-in-ci/cd) How do I use beads in CI/CD? Just run commands — embedded mode is the default, so no server is required: bd list --json bd ready --json [​](https://beads.gascity.com/reference/faq#workflows) Workflows ------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#what-are-formulas) What are formulas? Declarative workflow templates in TOML or JSON. `bd cook` compiles a formula into a proto (a template epic), and `bd mol pour` instantiates the proto as a molecule of real, tracked beads. See [Formulas](https://beads.gascity.com/workflows/formulas) . ### [​](https://beads.gascity.com/reference/faq#what-are-gates) What are gates? Async coordination primitives that block a workflow step until a condition clears: * **Human gates** wait for approval * **Timer gates** wait for a duration * **GitHub gates** wait for CI runs or PR events See [Gates](https://beads.gascity.com/workflows/gates) . ### [​](https://beads.gascity.com/reference/faq#what%E2%80%99s-the-difference-between-molecules-and-wisps) What’s the difference between molecules and wisps? Both are instantiated workflows made of real beads. **Molecules** (`bd mol pour`) are persistent — part of history, synced like any bead. **Wisps** (`bd mol wisp`) are ephemeral — flagged so they stay out of federation push and can be deleted wholesale (`bd purge`, `bd mol wisp gc`) once closed. Use molecules for work worth referencing later, wisps for operational loops like release checklists and health patrols. See [Molecules](https://beads.gascity.com/workflows/molecules) and [Wisps](https://beads.gascity.com/workflows/wisps) . [​](https://beads.gascity.com/reference/faq#integrations) Integrations ------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#should-i-use-the-cli-or-mcp) Should I use the CLI or MCP? **Use CLI + hooks** when a shell is available (Claude Code, Cursor, and similar): * Lower context overhead (on the order of a couple thousand tokens, versus tens of thousands for a full set of MCP tool schemas) * Faster execution * Universal across editors **Use MCP** when the CLI is unavailable (for example Claude Desktop). See [MCP Server](https://beads.gascity.com/integrations/mcp-server) . ### [​](https://beads.gascity.com/reference/faq#how-do-i-integrate-with-my-editor) How do I integrate with my editor? bd setup claude # Claude Code bd setup cursor # Cursor bd setup aider # Aider `bd setup` also supports copilot, gemini, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode. See [IDE Setup](https://beads.gascity.com/getting-started/ide-setup) and the [integrations index](https://beads.gascity.com/integrations/index) . ### [​](https://beads.gascity.com/reference/faq#can-beads-import-from-github-issues) Can beads import from GitHub Issues? Yes — `bd github sync --pull-only` imports issues in bulk (`bd github pull <refs>` cherry-picks specific ones), and `bd github sync` keeps beads and GitHub in sync bidirectionally. See the [bd github reference](https://beads.gascity.com/cli-reference/github) . [​](https://beads.gascity.com/reference/faq#migration) Migration ------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#how-do-i-migrate-from-github-issues-jira-or-linear) How do I migrate from GitHub Issues, Jira, or Linear? Beads has built-in bidirectional sync for all three — `bd github`, `bd jira`, and `bd linear` each provide `sync` for bulk moves, plus `pull`/`push` for specific issues by ID (GitLab, Azure DevOps, and Notion are covered by `bd gitlab`, `bd ado`, and `bd notion`). Configure credentials with `bd config set` per the [CLI reference](https://beads.gascity.com/cli-reference/index) , then run the sync in the pull direction: `bd github sync --pull-only`, `bd jira sync --pull`, or `bd linear sync --pull`. For any other tracker: export from it (usually CSV or JSON), convert to beads’ JSONL format, and run `bd import <file>`. See [examples](https://github.com/gastownhall/beads/tree/main/examples) for scripting patterns. ### [​](https://beads.gascity.com/reference/faq#can-i-export-back-out-of-beads) Can I export back out of beads? For GitHub, Jira, and Linear, use the same integrations in the push direction — `bd github sync --push-only`, `bd jira sync --push`, or `bd linear sync --push` for everything, or `bd <tracker> push <ids>` for specific beads. For anything else, `bd export -o issues.jsonl` produces JSONL you can convert with a script and feed to the target system’s API. [​](https://beads.gascity.com/reference/faq#performance) Performance ----------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#how-does-beads-handle-scale) How does beads handle scale? Dolt is a SQL database and comfortably handles far more issues than a typical project accumulates. Commands stay fast at the thousands-of-issues scale; for extremely large projects (100k+ issues), consider splitting into multiple databases per component. ### [​](https://beads.gascity.com/reference/faq#what-if-my-database-gets-too-large) What if my database gets too large? `bd gc` runs the full lifecycle: deletes old closed issues, squashes old Dolt commits, and runs Dolt garbage collection to reclaim disk space. bd gc --dry-run # Preview all phases bd gc # Delete issues closed 90+ days ago, compact, GC bd gc --older-than 30 # More aggressive decay window For semantic summarization of old closed issues instead of deletion, see `bd admin compact`. Or split the project: cd ~/project/frontend && bd init --prefix fe cd ~/project/backend && bd init --prefix be [​](https://beads.gascity.com/reference/faq#use-cases) Use Cases ------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#can-i-use-beads-for-non-code-projects) Can I use beads for non-code projects? Sure — beads is just an issue tracker. Writing projects (chapters as issues, outlines as dependencies), research (papers, experiments), home projects (renovations with blocking tasks) — any workflow with dependencies works, and the agent-friendly design fits any AI-assisted workflow. [​](https://beads.gascity.com/reference/faq#technical) Technical ------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#what-dependencies-does-beads-have) What dependencies does beads have? Beads is a single static binary with no runtime dependencies — the Dolt engine is embedded in-process. No PostgreSQL, no Redis, no Docker, no node\_modules. The standalone `dolt` CLI is only needed if you run server mode, and git is only needed to version your project code. See [Installation](https://beads.gascity.com/getting-started/installation) . ### [​](https://beads.gascity.com/reference/faq#can-i-query-or-extend-the-database-directly) Can I query or extend the database directly? Yes, three ways: `bd query` for the built-in query language (compound filters, boolean operators, date expressions), `bd sql` for raw SQL against the underlying database, and `--json` output on every command for building integrations. ### [​](https://beads.gascity.com/reference/faq#does-beads-support-windows) Does beads support Windows? Yes — native Windows support, no MSYS or MinGW required. A PowerShell script installs prebuilt releases, and everything works with Windows paths. See [Installation](https://beads.gascity.com/getting-started/installation#windows-11) . ### [​](https://beads.gascity.com/reference/faq#can-i-use-beads-with-git-worktrees) Can I use beads with git worktrees? Yes — beads works from normal git worktrees with no special setup. All worktrees in a repository share the same `.beads` workspace; `bd` discovers it from linked worktrees automatically. If an old beads version left hidden worktrees under `.git/` (from a since-removed sync-branch feature), clean them up: rm -rf .git/beads-worktrees rm -rf .git/worktrees/beads-* git worktree prune See [Worktrees](https://beads.gascity.com/reference/worktrees) for details and legacy cleanup. [​](https://beads.gascity.com/reference/faq#troubleshooting) Troubleshooting ------------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#why-is-the-dolt-server-not-starting) Why is the Dolt server not starting? This applies to server mode only (embedded mode has no server): bd doctor # Check health cat .beads/dolt-server.log # Check server logs (server mode) bd dolt stop && bd dolt start # Restart the server See [Troubleshooting](https://beads.gascity.com/reference/troubleshooting) . ### [​](https://beads.gascity.com/reference/faq#why-aren%E2%80%99t-my-changes-syncing) Why aren’t my changes syncing? bd dolt push # Push to the Dolt remote bd hooks list # Verify git hooks are installed bd doctor # Check for deeper issues See the [sync failures runbook](https://beads.gascity.com/recovery/sync-failures) . ### [​](https://beads.gascity.com/reference/faq#what%E2%80%99s-the-difference-between-database-corruption-and-id-collisions) What’s the difference between database corruption and ID collisions? These are two distinct integrity issues: **Logical consistency** — same ID assigned to different issues, wrong-prefix bugs, branch divergence. Hash-based IDs eliminate collisions by design, and `bd doctor --fix` repairs logical inconsistencies. **Physical corruption** — disk failures, power loss, or multiple processes writing to an embedded database simultaneously. Start with the [database corruption runbook](https://beads.gascity.com/recovery/database-corruption) (`bd doctor --fix` after backing up `.beads/`). If the database is unrecoverable and you have a Dolt remote, back up `.beads/`, delete the data directory for your mode — `.beads/embeddeddolt/` in embedded mode, `.beads/dolt/` in server mode — then re-init and pull: cp -r .beads .beads.backup rm -rf .beads/embeddeddolt # or .beads/dolt in server mode bd init bd dolt pull For multi-writer scenarios, use server mode so concurrent access goes through the server instead of racing on files. ### [​](https://beads.gascity.com/reference/faq#how-do-i-report-a-bug) How do I report a bug? 1. Check existing issues: [https://github.com/gastownhall/beads/issues](https://github.com/gastownhall/beads/issues) 2. Include `bd version`, `bd info --json`, and reproduction steps 3. File at: [https://github.com/gastownhall/beads/issues/new](https://github.com/gastownhall/beads/issues/new) [​](https://beads.gascity.com/reference/faq#getting-help) Getting Help ------------------------------------------------------------------------- ### [​](https://beads.gascity.com/reference/faq#where-can-i-get-more-help) Where can I get more help? * **Documentation**: [Quickstart](https://beads.gascity.com/getting-started/quickstart) , [Advanced Features](https://beads.gascity.com/reference/advanced) , [README](https://github.com/gastownhall/beads/blob/main/README.md) * **Troubleshooting**: [Troubleshooting guide](https://beads.gascity.com/reference/troubleshooting) and the [recovery runbooks](https://beads.gascity.com/recovery/index) * **Examples**: [examples/](https://github.com/gastownhall/beads/tree/main/examples) * **GitHub Issues**: [Report bugs or request features](https://github.com/gastownhall/beads/issues) * **GitHub Discussions**: [Ask questions](https://github.com/gastownhall/beads/discussions) ### [​](https://beads.gascity.com/reference/faq#how-can-i-contribute) How can I contribute? Contributions are welcome. See [CONTRIBUTING.md](https://github.com/gastownhall/beads/blob/main/CONTRIBUTING.md) for guidelines, test instructions, and the development workflow. ### [​](https://beads.gascity.com/reference/faq#where%E2%80%99s-the-roadmap) Where’s the roadmap? The roadmap lives in beads itself: bd list --priority-max 1 --json # All P0 and P1 issues Or check GitHub Issues for feature requests and planned improvements. [Antivirus False Positives](https://beads.gascity.com/reference/antivirus) [CLI Reference](https://beads.gascity.com/cli-reference) ⌘I --- # bd admin - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/admin#content-area) Generated from `bd help --doc admin`. Administrative commands for beads database maintenance. These commands are for advanced users and should be used carefully: cleanup Delete closed issues (issue lifecycle) compact Compact old closed issues to save space (storage optimization) reset Remove all beads data and configuration (full reset) For routine maintenance, prefer ‘bd doctor —fix’ which handles common repairs automatically. Use these admin commands for targeted database operations. bd admin [flags] [​](https://beads.gascity.com/cli-reference/admin#bd-admin-cleanup) bd admin cleanup --------------------------------------------------------------------------------------- Delete closed issues to reduce database size. This command permanently removes closed issues from the database. NOTE: This command only manages issue lifecycle (closed -> deleted). For general health checks and automatic repairs, use ‘bd doctor —fix’ instead. By default, deletes ALL closed issues. Use —older-than to only delete issues closed before a certain date. EXAMPLES: bd admin cleanup —force # Delete all closed issues bd admin cleanup —older-than 30 —force # Only issues closed 30+ days ago bd admin cleanup —ephemeral —force # Only closed wisps (transient molecules) bd admin cleanup —dry-run # Preview what would be deleted SAFETY: * Requires —force flag to actually delete (unless —dry-run) * Supports —cascade to delete dependents * Shows preview of what will be deleted * Use —json for programmatic output SEE ALSO: bd doctor —fix Automatic health checks and repairs (recommended for routine maintenance) bd admin compact Compact old closed issues to save space bd admin cleanup [flags] **Flags:** --cascade Recursively delete all dependent issues --dry-run Preview what would be deleted without making changes --ephemeral Only delete closed wisps (transient molecules) -f, --force Actually delete (without this flag, shows error) --older-than int Only delete issues closed more than N days ago (0 = all closed issues) [​](https://beads.gascity.com/cli-reference/admin#bd-admin-compact) bd admin compact --------------------------------------------------------------------------------------- Compact old closed issues using semantic summarization. Compaction reduces database size by summarizing closed issues that are no longer actively referenced. This is permanent graceful decay - original content is discarded. Modes: * Analyze: Export candidates for agent review (no API key needed) * Apply: Accept agent-provided summary (no API key needed) * Auto: AI-powered compaction (requires ANTHROPIC\_API\_KEY or ai.api\_key, legacy) * Dolt: Run Dolt garbage collection (for Dolt-backend repositories) Tiers: * Tier 1: Semantic compression (30 days closed, 70% reduction) * Tier 2: Ultra compression (90 days closed) - planned, not yet implemented Dolt Garbage Collection: With auto-commit per mutation, Dolt commit history grows over time. Use —dolt to run Dolt garbage collection and reclaim disk space. —dolt: Run Dolt GC on .beads/dolt directory to free disk space. This removes unreachable commits and compacts storage. Examples: [​](https://beads.gascity.com/cli-reference/admin#dolt-garbage-collection) Dolt garbage collection ===================================================================================================== bd compact —dolt # Run Dolt GC bd compact —dolt —dry-run # Preview without running GC [​](https://beads.gascity.com/cli-reference/admin#agent-driven-workflow-recommended) Agent-driven workflow (recommended) =========================================================================================================================== bd compact —analyze —json # Get candidates with full content bd compact —apply —id bd-42 —summary summary.txt bd compact —apply —id bd-42 —summary - < summary.txt [​](https://beads.gascity.com/cli-reference/admin#legacy-ai-powered-workflow) Legacy AI-powered workflow =========================================================================================================== bd compact —auto —dry-run # Preview candidates bd compact —auto —all # Compact all eligible issues bd compact —auto —id bd-42 # Compact specific issue [​](https://beads.gascity.com/cli-reference/admin#statistics) Statistics =========================================================================== bd compact —stats # Show statistics bd admin compact [flags] **Flags:** --actor string Actor name for audit trail (default "agent") --all Process all candidates --analyze Analyze mode: export candidates for agent review --apply Apply mode: accept agent-provided summary --auto Auto mode: AI-powered compaction (legacy) --batch-size int Issues per batch (default 10) --dolt Dolt mode: run Dolt garbage collection on .beads/dolt --dry-run Preview without compacting --force Force compact (bypass checks, requires --id) --id string Compact specific issue --json Output JSON format --limit int Limit number of candidates (0 = no limit) --stats Show compaction statistics --summary string Path to summary file (use '-' for stdin) --tier int Compaction tier (only tier 1 is implemented) (default 1) --workers int Parallel workers (default 5) [​](https://beads.gascity.com/cli-reference/admin#bd-admin-reset) bd admin reset ----------------------------------------------------------------------------------- Reset beads to an uninitialized state, removing all local data. This command removes: * The .beads directory (database, JSONL, config) * Git hooks installed by bd * Sync branch worktrees By default, shows what would be deleted (dry-run mode). Use —force to actually perform the reset. Examples: bd reset # Show what would be deleted bd reset —force # Actually delete everything bd admin reset [flags] **Flags:** --force Actually perform the reset (required) [CLI Reference](https://beads.gascity.com/cli-reference) [bd ado](https://beads.gascity.com/cli-reference/ado) ⌘I --- # bd ado - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/ado#content-area) Generated from `bd help --doc ado`. Commands for syncing issues between beads and Azure DevOps. Configuration can be set via ‘bd config’ or environment variables: ado.org / AZURE\_DEVOPS\_ORG - Organization name ado.project / AZURE\_DEVOPS\_PROJECT - Project name (single) ado.projects / AZURE\_DEVOPS\_PROJECTS - Project names (comma-separated) ado.pat / AZURE\_DEVOPS\_PAT - Personal access token ado.url / AZURE\_DEVOPS\_URL - Custom base URL (on-prem) bd ado [flags] [​](https://beads.gascity.com/cli-reference/ado#bd-ado-projects) bd ado projects ----------------------------------------------------------------------------------- List Azure DevOps projects that the configured token has access to. bd ado projects [flags] [​](https://beads.gascity.com/cli-reference/ado#bd-ado-pull) bd ado pull --------------------------------------------------------------------------- Pull one or more items from Azure DevOps. Accepts bead IDs or external references as positional arguments. Equivalent to: bd ado sync —pull-only —issues <refs> bd ado pull [refs...] [flags] **Flags:** --dry-run Preview pull without making changes [​](https://beads.gascity.com/cli-reference/ado#bd-ado-push) bd ado push --------------------------------------------------------------------------- Push one or more beads issues to Azure DevOps. Accepts bead IDs as positional arguments. Equivalent to: bd ado sync —push-only —issues <ids> bd ado push [bead-ids...] [flags] **Flags:** --dry-run Preview push without making changes [​](https://beads.gascity.com/cli-reference/ado#bd-ado-status) bd ado status ------------------------------------------------------------------------------- Display current Azure DevOps configuration and sync status. bd ado status [flags] [​](https://beads.gascity.com/cli-reference/ado#bd-ado-sync) bd ado sync --------------------------------------------------------------------------- Synchronize issues between beads and Azure DevOps. By default, performs bidirectional sync: * Pulls new/updated work items from Azure DevOps to beads * Pushes local beads issues to Azure DevOps Use —pull-only or —push-only to limit direction. Filters (—area-path, —iteration-path, —types, —states) restrict which work items are synced. On pull, they limit the WIQL query. On push, —types and —states filter local beads before pushing to ADO. Use —no-create with push to skip creating new ADO work items (only update existing linked items). Filters can also be persisted via config: ado.filter.area\_path, ado.filter.iteration\_path, ado.filter.types, ado.filter.states CLI flags override config values when both are set. bd ado sync [flags] **Flags:** --area-path string Filter to ADO area path (e.g., "Project\Team") --bootstrap-match Enable heuristic matching for first sync --dry-run Show what would be synced without making changes --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --iteration-path string Filter to ADO iteration path (e.g., "Project\Sprint 1") --no-create Never create new items in either direction (pull or push) --parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues. --prefer-ado On conflict, use Azure DevOps version --prefer-local On conflict, keep local beads version --prefer-newer On conflict, use most recent version (default) --project strings Project name(s) to sync (overrides configured project/projects) --pull-only Only pull issues from Azure DevOps --push-only Only push issues to Azure DevOps --reconcile Force reconciliation scan for deleted items --states string Filter to ADO states, comma-separated (e.g., "New,Active,Resolved") --types string Filter to work item types, comma-separated (e.g., "Bug,Task,User Story") [bd admin](https://beads.gascity.com/cli-reference/admin) [bd assign](https://beads.gascity.com/cli-reference/assign) ⌘I --- # bd assign - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/assign#content-area) Generated from `bd help --doc assign`. Assign an issue to someone. Shorthand for ‘bd update <id> —assignee <name>’. Examples: bd assign bd-123 alice bd assign bd-123 "" # unassign bd assign <id> <name> [flags] [bd ado](https://beads.gascity.com/cli-reference/ado) [bd audit](https://beads.gascity.com/cli-reference/audit) ⌘I --- # bd audit - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/audit#content-area) Generated from `bd help --doc audit`. Audit log entries are appended to .beads/interactions.jsonl. Each line is one event. This file is intended to be versioned in git and used for: * auditing (“why did the agent do that?”) * dataset generation (SFT/RL fine-tuning) Entries are append-only. Labeling creates a new “label” entry that references a parent entry. bd audit [flags] [​](https://beads.gascity.com/cli-reference/audit#bd-audit-label) bd audit label ----------------------------------------------------------------------------------- Append a label entry referencing an existing interaction bd audit label <entry-id> [flags] **Flags:** --label string Label value (e.g. "good" or "bad") --reason string Reason for label [​](https://beads.gascity.com/cli-reference/audit#bd-audit-record) bd audit record ------------------------------------------------------------------------------------- Append an audit interaction entry bd audit record [flags] **Flags:** --error string Error string (llm_call/tool_call) --exit-code int Exit code (tool_call) (default -1) --issue-id string Related issue id (bd-...) --kind string Entry kind (e.g. llm_call, tool_call, label) --model string Model name (llm_call) --prompt string Prompt text (llm_call) --response string Response text (llm_call) --stdin Read a JSON object from stdin (must match audit.Entry schema) --tool-name string Tool name (tool_call) [bd assign](https://beads.gascity.com/cli-reference/assign) [bd backup](https://beads.gascity.com/cli-reference/backup) ⌘I --- # bd blocked - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/blocked#content-area) Generated from `bd help --doc blocked`. Show blocked issues bd blocked [flags] **Flags:** --parent string Filter to descendants of this bead/epic [bd batch](https://beads.gascity.com/cli-reference/batch) [bd bootstrap](https://beads.gascity.com/cli-reference/bootstrap) ⌘I --- # bd children - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/children#content-area) Generated from `bd help --doc children`. List all beads that are children of the specified parent bead. This is a convenience alias for ‘bd list —parent <id> —status all’. Unlike plain ‘bd list’, children includes closed issues by default, since the primary use case is inspecting all work under a parent. Examples: bd children hq-abc123 # List all children of hq-abc123 bd children hq-abc123 —json # List children in JSON format bd children hq-abc123 —pretty # Show children in tree format bd children <parent-id> [flags] **Flags:** --pretty Show children in tree format [bd branch](https://beads.gascity.com/cli-reference/branch) [bd close](https://beads.gascity.com/cli-reference/close) ⌘I --- # bd bootstrap - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/bootstrap#content-area) Generated from `bd help --doc bootstrap`. Bootstrap sets up the beads database without destroying existing data. Unlike ‘bd init —force’, bootstrap will never delete existing issues. Bootstrap auto-detects the right action: • If sync.remote is configured: clones from the remote • If git origin has Dolt data (refs/dolt/data): clones from git and wires origin for future push/pull • If .beads/backup/\*.jsonl exists: restores from backup • If .beads/issues.jsonl exists: imports from git-tracked JSONL • If no database exists: creates a fresh one • If database already exists: validates and reports status This is the recommended command for: • Setting up beads on a fresh clone • Recovering after moving to a new machine • Repairing a broken database configuration Non-interactive mode (—non-interactive, —yes/-y, or BD\_NON\_INTERACTIVE=1): Skips the confirmation prompt before executing the bootstrap plan. Also auto-detected when stdin is not a terminal or CI=true is set. Examples: bd bootstrap # Auto-detect and set up bd bootstrap —dry-run # Show what would be done bd bootstrap —json # Output plan as JSON bd bootstrap —yes # Skip confirmation prompt bd bootstrap [flags] **Flags:** --dry-run Show what would be done without doing it --non-interactive Alias for --yes -y, --yes Skip confirmation prompts (for CI/automation) [bd blocked](https://beads.gascity.com/cli-reference/blocked) [bd branch](https://beads.gascity.com/cli-reference/branch) ⌘I --- # bd branch - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/branch#content-area) Generated from `bd help --doc branch`. List all branches or create a new branch. This command requires the Dolt storage backend. Without arguments, it lists all branches. With an argument, it creates a new branch. Examples: bd branch # List all branches bd branch feature-xyz # Create a new branch named feature-xyz bd branch [name] [flags] [bd bootstrap](https://beads.gascity.com/cli-reference/bootstrap) [bd children](https://beads.gascity.com/cli-reference/children) ⌘I --- # bd batch - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/batch#content-area) Generated from `bd help --doc batch`. Run multiple write operations in a single database transaction. Commands are read from stdin (one per line) or from a file via -f/—file. All operations execute inside a single dolt transaction: on any error the whole batch is rolled back, otherwise it is committed with one DOLT\_COMMIT. This is intended for shell scripts that currently invoke ‘bd’ many times in a loop, which causes severe write amplification on a dolt sql-server backed by btrfs+compression. Batching collapses N invocations into one transaction and one dolt commit. Grammar (one command per line): close <id> \[reason…\] update <id> <key>=<value> \[<key>=<value> …\] create <type> <priority> <title…> dep add <from-id> <to-id> \[type\] dep remove <from-id> <to-id> #comment (blank lines and ’# …’ comments are ignored) Supported ‘update’ keys: status, priority, title, assignee Supported dependency types: see ‘bd dep add —help’ (default: blocks) Tokens are whitespace-separated. Double-quoted strings (“like this”) may contain spaces; use ” to embed a quote and \\ for a backslash. Examples: [​](https://beads.gascity.com/cli-reference/batch#from-a-pipe) From a pipe ============================================================================= bd list —status stale -q | awk ‘{print “close”,$1,” stale”}’ | bd batch [​](https://beads.gascity.com/cli-reference/batch#from-a-file) From a file ============================================================================= bd batch -f operations.txt [​](https://beads.gascity.com/cli-reference/batch#inline) Inline =================================================================== printf ‘close bd-1 done\\nupdate bd-2 status=in\_progress\\n’ | bd batch On success, exits 0 and prints a summary (or JSON with —json). On any error, rolls back the entire transaction and exits non-zero with the failing line. NOTE: This is a narrow subset. Commands like ‘show’, ‘list’, ‘ready’, ‘sync’, complex create flows, or any flag not listed above are NOT accepted. Use normal ‘bd’ subcommands for interactive/read operations. bd batch [flags] **Flags:** --dry-run Parse input and echo commands without executing -f, --file string Read commands from file instead of stdin -m, --message string DOLT_COMMIT message (default: 'bd: batch N ops by <actor>') [bd backup](https://beads.gascity.com/cli-reference/backup) [bd blocked](https://beads.gascity.com/cli-reference/blocked) ⌘I --- # bd backup - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/backup#content-area) Generated from `bd help --doc backup`. Back up your beads database for off-machine recovery. This is a Dolt-native database backup. It preserves the database state, including tables, branches, commit history, and working-set data. This is different from ‘bd export’, which writes issue records to JSONL for migration and interoperability. Commands: bd backup init <path> Set up a backup destination (filesystem or DoltHub) bd backup sync Push to configured backup destination bd backup restore \[path\] Restore from a backup directory bd backup remove Remove backup destination bd backup status Show backup status DoltHub is recommended for cloud backup: bd backup init [https://doltremoteapi.dolthub.com/<user>/<repo](https://doltremoteapi.dolthub.com/<user>/<repo) \> Set DOLT\_REMOTE\_USER and DOLT\_REMOTE\_PASSWORD for authentication. bd backup [flags] [​](https://beads.gascity.com/cli-reference/backup#bd-backup-init) bd backup init ------------------------------------------------------------------------------------ Configure a filesystem path or URL as a backup destination. The path can be a local directory (external drive, NAS, Dropbox folder) or a DoltHub remote URL. If the destination was previously configured, it is updated to the new path. Filesystem examples: bd backup add /mnt/usb/beads-backup bd backup add ~/Dropbox/beads-backup DoltHub (recommended for cloud backup): bd backup add [https://doltremoteapi.dolthub.com/myuser/beads-backup](https://doltremoteapi.dolthub.com/myuser/beads-backup) After adding, run ‘bd backup sync’ to push your data. bd backup init <path> [flags] **Aliases:** add [​](https://beads.gascity.com/cli-reference/backup#bd-backup-remove) bd backup remove ---------------------------------------------------------------------------------------- Remove the configured backup destination. This unregisters the backup remote from Dolt and removes the local backup configuration. The backup data at the destination is not deleted. bd backup remove [flags] **Aliases:** rm [​](https://beads.gascity.com/cli-reference/backup#bd-backup-restore) bd backup restore ------------------------------------------------------------------------------------------ Restore the beads database from a Dolt-native backup. By default, reads from .beads/backup/ (or the configured backup directory). Optionally specify a path to a directory containing a Dolt backup. This restores a full database backup created by ‘bd backup sync’ or an equivalent Dolt backup. JSONL files produced by ‘bd export’ are issue exports, not restore targets for this command. Use —force to overwrite an existing database with the backup contents. The database must already be initialized (run ‘bd init’ first if needed). To initialize and restore in one step, use: bd init && bd backup restore bd backup restore [path] [flags] **Flags:** --force Overwrite existing database with backup contents [​](https://beads.gascity.com/cli-reference/backup#bd-backup-status) bd backup status ---------------------------------------------------------------------------------------- Show last backup status bd backup status [flags] [​](https://beads.gascity.com/cli-reference/backup#bd-backup-sync) bd backup sync ------------------------------------------------------------------------------------ Sync the current beads database to the configured Dolt backup destination. This pushes the entire database state (all branches, full history) to the backup location configured with ‘bd backup init’. The backup is atomic — if the sync fails, the previous backup state is preserved. Run ‘bd backup init <path>’ first to configure a destination. bd backup sync [flags] [bd audit](https://beads.gascity.com/cli-reference/audit) [bd batch](https://beads.gascity.com/cli-reference/batch) ⌘I --- # bd close - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/close#content-area) Generated from `bd help --doc close`. Close one or more issues. If no issue ID is provided, closes the last touched issue (from most recent create, update, show, or close operation). When closing multiple issues, provide one —reason for all IDs or repeat —reason once per ID. Reasons map positionally: the first —reason applies to the first ID, the second —reason to the second ID, regardless of where the flags appear in the command line. bd close [id...] [flags] **Aliases:** done **Flags:** --claim-next Automatically claim the next highest priority available issue --continue Auto-advance to next step in molecule -f, --force Force close pinned issues or unsatisfied gates --no-auto With --continue, show next step but don't claim it -r, --reason string Reason for closing --reason-file string Read close reason from file (use - for stdin) --session string Claude Code session ID (or set CLAUDE_SESSION_ID env var) --suggest-next Show newly unblocked issues after closing [bd children](https://beads.gascity.com/cli-reference/children) [bd comment](https://beads.gascity.com/cli-reference/comment) ⌘I --- # bd comment - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/comment#content-area) Generated from `bd help --doc comment`. Add a comment to an issue. Shorthand for ‘bd comments add <id> “text”’. Examples: bd comment bd-123 “Working on this now” bd comment bd-123 Working on this now echo “comment from pipe” | bd comment bd-123 —stdin bd comment bd-123 —file notes.txt bd comment <id> [text...] [flags] **Flags:** --file string Read comment text from file --stdin Read comment text from stdin [bd close](https://beads.gascity.com/cli-reference/close) [bd comments](https://beads.gascity.com/cli-reference/comments) ⌘I --- # bd compact - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/compact#content-area) Generated from `bd help --doc compact`. Squash Dolt commits older than N days into a single commit. Recent commits (within the retention window) are preserved via cherry-pick. This reduces Dolt storage overhead from auto-commit history while keeping recent change tracking intact. For semantic issue compaction (summarizing closed issues), use ‘bd admin compact’. For full history squash, use ‘bd flatten’. How it works: 1. Identifies commits older than —days threshold 2. Creates a squashed base commit from all old history 3. Cherry-picks recent commits on top 4. Swaps main branch to the compacted version 5. Runs Dolt GC to reclaim space Examples: bd compact —dry-run # Preview: show commit breakdown bd compact —force # Squash commits older than 30 days bd compact —days 7 —force # Keep only last 7 days of history bd compact —days 90 —force # Conservative: squash 90+ day old commits bd compact [flags] **Flags:** --days int Keep commits newer than N days (default 30) --dry-run Preview without making changes -f, --force Confirm commit squash [bd comments](https://beads.gascity.com/cli-reference/comments) [bd completion](https://beads.gascity.com/cli-reference/completion) ⌘I --- # bd comments - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/comments#content-area) Generated from `bd help --doc comments`. View or manage comments on an issue. Examples: [​](https://beads.gascity.com/cli-reference/comments#list-all-comments-on-an-issue-issue-id-is-required-%E2%80%94-there-is-no-%E2%80%9Ccomments-list%E2%80%9D) List all comments on an issue (issue id is required — there is no “comments list”) ==================================================================================================================================================================================================================================================== bd comments bd-123 [​](https://beads.gascity.com/cli-reference/comments#list-comments-in-json-format) List comments in JSON format ================================================================================================================== bd comments bd-123 —json [​](https://beads.gascity.com/cli-reference/comments#add-a-comment) Add a comment ==================================================================================== bd comments add bd-123 “This is a comment” [​](https://beads.gascity.com/cli-reference/comments#add-a-comment-from-a-file) Add a comment from a file ============================================================================================================ bd comments add bd-123 -f notes.txt bd comments [issue-id] [flags] **Flags:** --local-time Show timestamps in local time instead of UTC [​](https://beads.gascity.com/cli-reference/comments#bd-comments-add) bd comments add ---------------------------------------------------------------------------------------- Add a comment to an issue. Examples: [​](https://beads.gascity.com/cli-reference/comments#add-a-comment-2) Add a comment ====================================================================================== bd comments add bd-123 “Working on this now” [​](https://beads.gascity.com/cli-reference/comments#add-a-comment-from-a-file-2) Add a comment from a file ============================================================================================================== bd comments add bd-123 -f notes.txt bd comments add [issue-id] [text] [flags] **Flags:** -a, --author string Add author to comment -f, --file string Read comment text from file [​](https://beads.gascity.com/cli-reference/comments#bd-comments-list) bd comments list ------------------------------------------------------------------------------------------ Invalid — use bd comments <issue-id> to list comments bd comments list [flags] [bd comment](https://beads.gascity.com/cli-reference/comment) [bd compact](https://beads.gascity.com/cli-reference/compact) ⌘I --- # bd context - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/context#content-area) Generated from `bd help --doc context`. Show the effective backend identity information including repository paths, backend configuration, and sync settings. This command reads directly from config files and does not require the database to be open, making it useful for diagnostics in degraded states. Examples: bd context # Show context information bd context —json # Output in JSON format bd context [flags] [bd config](https://beads.gascity.com/cli-reference/config) [bd cook](https://beads.gascity.com/cli-reference/cook) ⌘I --- # bd completion - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/completion#content-area) Generated from `bd help --doc completion`. Generate the autocompletion script for bd for the specified shell. See each sub-command’s help for details on how to use the generated script. bd completion [flags] [​](https://beads.gascity.com/cli-reference/completion#bd-completion-bash) bd completion bash ------------------------------------------------------------------------------------------------ Generate the autocompletion script for the bash shell. This script depends on the ‘bash-completion’ package. If it is not installed already, you can install it via your OS’s package manager. To load completions in your current shell session: source <(bd completion bash) To load completions for every new session, execute once: ### [​](https://beads.gascity.com/cli-reference/completion#linux) Linux: bd completion bash > /etc/bash\_completion.d/bd ### [​](https://beads.gascity.com/cli-reference/completion#macos) macOS: bd completion bash > $(brew —prefix)/etc/bash\_completion.d/bd You will need to start a new shell for this setup to take effect. bd completion bash **Flags:** --no-descriptions disable completion descriptions [​](https://beads.gascity.com/cli-reference/completion#bd-completion-fish) bd completion fish ------------------------------------------------------------------------------------------------ Generate the autocompletion script for the fish shell. To load completions in your current shell session: bd completion fish | source To load completions for every new session, execute once: bd completion fish > ~/.config/fish/completions/bd.fish You will need to start a new shell for this setup to take effect. bd completion fish [flags] **Flags:** --no-descriptions disable completion descriptions [​](https://beads.gascity.com/cli-reference/completion#bd-completion-powershell) bd completion powershell ------------------------------------------------------------------------------------------------------------ Generate the autocompletion script for powershell. To load completions in your current shell session: bd completion powershell | Out-String | Invoke-Expression To load completions for every new session, add the output of the above command to your powershell profile. bd completion powershell [flags] **Flags:** --no-descriptions disable completion descriptions [​](https://beads.gascity.com/cli-reference/completion#bd-completion-zsh) bd completion zsh ---------------------------------------------------------------------------------------------- Generate the autocompletion script for the zsh shell. If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once: echo “autoload -U compinit; compinit” >> ~/.zshrc To load completions in your current shell session: source <(bd completion zsh) To load completions for every new session, execute once: ### [​](https://beads.gascity.com/cli-reference/completion#linux-2) Linux: bd completion zsh > ”${fpath\[1\]}/\_bd” ### [​](https://beads.gascity.com/cli-reference/completion#macos-2) macOS: bd completion zsh > $(brew —prefix)/share/zsh/site-functions/\_bd You will need to start a new shell for this setup to take effect. bd completion zsh [flags] **Flags:** --no-descriptions disable completion descriptions [bd compact](https://beads.gascity.com/cli-reference/compact) [bd config](https://beads.gascity.com/cli-reference/config) ⌘I --- # bd count - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/count#content-area) Generated from `bd help --doc count`. Count issues matching the specified filters. By default, returns the total count of issues matching the filters. Use —by-\* flags to group counts by different attributes. Examples: bd count # Count all issues bd count —status open # Count open issues bd count —by-status # Group count by status bd count —by-priority # Group count by priority bd count —by-type # Group count by issue type bd count —by-assignee # Group count by assignee bd count —by-label # Group count by label bd count —assignee alice —by-status # Count alice’s issues by status bd count —include-infra # Count issues + wisps tier (matches ‘bd list —include-infra —all’ cardinality) bd count [flags] **Flags:** -a, --assignee string Filter by assignee --by-assignee Group count by assignee --by-label Group count by label --by-priority Group count by priority --by-status Group count by status --by-type Group count by issue type --closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339) --closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339) --created-after string Filter issues created after date (YYYY-MM-DD or RFC3339) --created-before string Filter issues created before date (YYYY-MM-DD or RFC3339) --desc-contains string Filter by description substring --empty-description Filter issues with empty description --id string Filter by specific issue IDs (comma-separated) --include-infra Include infrastructure beads and the wisps tier (matches 'bd list --include-infra --all' cardinality) -l, --label strings Filter by labels (AND: must have ALL) --label-any strings Filter by labels (OR: must have AT LEAST ONE) --no-assignee Filter issues with no assignee --no-labels Filter issues with no labels --notes-contains string Filter by notes substring -p, --priority int Filter by priority (0-4: 0=critical, 1=high, 2=medium, 3=low, 4=backlog) --priority-max int Filter by maximum priority (inclusive) --priority-min int Filter by minimum priority (inclusive) -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Note: dependency-blocked issues use 'bd blocked' --title string Filter by title text (case-insensitive substring match) --title-contains string Filter by title substring -t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate) --updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339) --updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339) [bd cook](https://beads.gascity.com/cli-reference/cook) [bd create-form](https://beads.gascity.com/cli-reference/create-form) ⌘I --- # bd cook - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/cook#content-area) Generated from `bd help --doc cook`. Cook transforms a .formula.json file into a proto. By default, cook outputs the resolved formula as JSON to stdout for ephemeral use. The output can be inspected, piped, or saved to a file. Two cooking modes are available: COMPILE-TIME (default, —mode=compile): Produces a proto with {{variable}} placeholders intact. Use for: modeling, estimation, contractor handoff, planning. Variables are NOT substituted - the output shows the template structure. RUNTIME (—mode=runtime or when —var flags provided): Produces a fully-resolved proto with variables substituted. Use for: final validation before pour, seeing exact output. Requires all variables to have values (via —var or defaults). Formulas are high-level workflow templates that support: * Variable definitions with defaults and validation * Step definitions that become issue hierarchies * Composition rules for bonding formulas together * Inheritance via extends The —persist flag enables the legacy behavior of writing the proto to the database. This is useful when you want to reuse the same proto multiple times without re-cooking. For most workflows, prefer ephemeral protos: pour and wisp commands accept formula names directly and cook inline. Examples: bd cook mol-feature.formula.json # Compile-time: keep {{vars}} bd cook mol-feature —var name=auth # Runtime: substitute vars bd cook mol-feature —mode=runtime —var name=auth # Explicit runtime mode bd cook mol-feature —dry-run # Preview steps bd cook mol-release.formula.json —persist # Write to database bd cook mol-release.formula.json —persist —force # Replace existing Output (default): JSON representation of the resolved formula with all steps. Output (—persist): Creates a proto bead in the database with: * ID matching the formula name (e.g., mol-feature) * The “template” label for proto identification * Child issues for each step * Dependencies matching depends\_on relationships bd cook <formula-file> [flags] **Flags:** --dry-run Preview what would be created --force Replace existing proto if it exists (requires --persist) --mode string Cooking mode: compile (keep placeholders) or runtime (substitute vars) --persist Persist proto to database (legacy behavior) --prefix string Prefix to prepend to proto ID (e.g., 'gt-' creates 'gt-mol-feature') --search-path strings Additional paths to search for formula inheritance --var stringArray Variable substitution (key=value), enables runtime mode [bd context](https://beads.gascity.com/cli-reference/context) [bd count](https://beads.gascity.com/cli-reference/count) ⌘I --- # bd create-form - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/create-form#content-area) Generated from `bd help --doc create-form`. Create a new issue using an interactive terminal form. This command provides a user-friendly form interface for creating issues, with fields for title, description, type, priority, labels, and more. Use —parent to create a sub-issue under an existing parent issue. The child will get an auto-generated hierarchical ID (e.g., parent-id.1). The form uses keyboard navigation: * Tab/Shift+Tab: Move between fields * Enter: Submit the form (on the last field or submit button) * Ctrl+C: Cancel and exit * Arrow keys: Navigate within select fields bd create-form [flags] **Flags:** --parent string Parent issue ID for creating a hierarchical child (e.g., 'bd-a3f8e9') [bd count](https://beads.gascity.com/cli-reference/count) [bd create](https://beads.gascity.com/cli-reference/create) ⌘I --- # bd defer - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/defer#content-area) Generated from `bd help --doc defer`. Defer issues to put them on ice for later. Deferred issues are deliberately set aside - not blocked by anything specific, just postponed for future consideration. Unlike blocked issues, there’s no dependency keeping them from being worked. Unlike closed issues, they will be revisited. Deferred issues don’t show in ‘bd ready’ but remain visible in ‘bd list’. Examples: bd defer bd-abc # Defer a single issue (status-based) bd defer bd-abc —until=tomorrow # Defer until specific time bd defer bd-abc —reason=“waiting on API access” bd defer bd-abc bd-def # Defer multiple issues bd defer [id...] [flags] **Flags:** --reason string Record why this issue is being deferred (appended to notes) --until string Defer until specific time (e.g., +1h, tomorrow, next monday) [bd create](https://beads.gascity.com/cli-reference/create) [bd delete](https://beads.gascity.com/cli-reference/delete) ⌘I --- # bd delete - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/delete#content-area) Generated from `bd help --doc delete`. Delete one or more issues and clean up all references to them. This command will: 1. Remove all dependency links (any type, both directions) involving the issues 2. Update text references to “\[deleted:ID\]” in directly connected issues 3. Permanently delete the issues from the database This is a destructive operation that cannot be undone. Use with caution. BATCH DELETION: Delete multiple issues at once: bd delete bd-1 bd-2 bd-3 —force Delete from file (one ID per line): bd delete —from-file deletions.txt —force Preview before deleting: bd delete —from-file deletions.txt —dry-run DEPENDENCY HANDLING: Default: Fails if any issue has dependents not in deletion set bd delete bd-1 bd-2 Cascade: Recursively delete all dependents bd delete bd-1 —cascade —force Force: Delete and orphan dependents bd delete bd-1 —force bd delete <issue-id> [issue-id...] [flags] **Flags:** --cascade Recursively delete all dependent issues --dry-run Preview what would be deleted without making changes -f, --force Actually delete (without this flag, shows preview) --from-file string Read issue IDs from file (one per line) [bd defer](https://beads.gascity.com/cli-reference/defer) [bd dep](https://beads.gascity.com/cli-reference/dep) ⌘I --- # bd create - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/create#content-area) Generated from `bd help --doc create`. Create a new issue (or batch from markdown/graph JSON) bd create [title] [flags] **Aliases:** new **Flags:** --acceptance string Acceptance criteria --append-notes string Append to existing notes (with newline separator) -a, --assignee string Assignee --body-file string Read description from file (use - for stdin) --context string Additional context for the issue --defer string Defer until date (issue hidden from bd ready until then). Same formats as --due --deps strings Dependencies in format 'type:id' or 'id' (e.g., 'discovered-from:bd-20,blocks:bd-15' or 'bd-20') -d, --description string Issue description --design string Design notes --design-file string Read design from file (use - for stdin) --dry-run Preview what would be created without actually creating --due string Due date/time. Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15 --ephemeral Create as ephemeral (short-lived, subject to TTL compaction) -e, --estimate int Time estimate in minutes (e.g., 60 for 1 hour) --event-actor string Entity URI who caused this event (requires --type=event) --event-category string Event category (e.g., patrol.muted, agent.started) (requires --type=event) --event-payload string Event-specific JSON data (requires --type=event) --event-target string Entity URI or bead ID affected (requires --type=event) --external-ref string External reference (e.g., 'gh-9', 'jira-ABC', Linear URL) -f, --file string Create multiple issues from markdown file --force Force creation even if prefix doesn't match database prefix --graph string Create a graph of issues with dependencies from JSON plan file --id string Explicit issue ID (e.g., 'bd-42' for partitioning) -l, --labels strings Labels (comma-separated) --metadata string Set custom metadata (JSON string or @file.json to read from file) --mol-type string Molecule type: swarm (multi-agent), patrol (recurring ops), work (default) --no-history Skip Dolt commit history without making GC-eligible (for permanent agent beads) --no-inherit-labels Don't inherit labels from parent issue --notes string Additional notes --parent string Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9') -p, --priority string Priority (0-4 or P0-P4, 0=highest) (default "2") --repo string Target repository for issue (overrides auto-routing) --silent Output only the issue ID (for scripting) --skills string Required skills for this issue --spec-id string Link to specification document --stdin Read description from stdin (alias for --body-file -) --title string Issue title (alternative to positional argument) -t, --type string Issue type (bug|feature|task|epic|chore|decision); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task") --validate Validate description contains required sections for issue type --waits-for string Spawner issue ID to wait for (creates waits-for dependency for fanout gate) --waits-for-gate string Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children") --wisp-type string Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation [bd create-form](https://beads.gascity.com/cli-reference/create-form) [bd defer](https://beads.gascity.com/cli-reference/defer) ⌘I --- # bd diff - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/diff#content-area) Generated from `bd help --doc diff`. Show the differences in issues between two commits or branches. The refs can be: * Commit hashes (e.g., abc123def) * Branch names (e.g., main, feature-branch) * Special refs like HEAD, HEAD~1 Examples: bd diff main feature-branch # Compare main to feature branch bd diff HEAD~5 HEAD # Show changes in last 5 commits bd diff abc123 def456 # Compare two specific commits bd diff <from-ref> <to-ref> [flags] [bd dep](https://beads.gascity.com/cli-reference/dep) [bd doctor](https://beads.gascity.com/cli-reference/doctor) ⌘I --- # bd recall - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/recall#content-area) Generated from `bd help --doc recall`. Retrieve the full content of a memory by its key. Examples: bd recall dolt-phantoms bd recall auth-jwt bd recall <key> [flags] [bd ready](https://beads.gascity.com/cli-reference/ready) [bd recompute-blocked](https://beads.gascity.com/cli-reference/recompute-blocked) ⌘I --- # bd edit - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/edit#content-area) Generated from `bd help --doc edit`. Edit an issue field using your configured $EDITOR. By default, edits the description. Use flags to edit other fields. Examples: bd edit bd-42 # Edit description bd edit bd-42 —title # Edit title bd edit bd-42 —design # Edit design notes bd edit bd-42 —notes # Edit notes bd edit bd-42 —acceptance # Edit acceptance criteria bd edit [id] [flags] **Flags:** --acceptance Edit the acceptance criteria --description Edit the description (default) --design Edit the design notes --notes Edit the notes --title Edit the title [bd duplicates](https://beads.gascity.com/cli-reference/duplicates) [bd epic](https://beads.gascity.com/cli-reference/epic) ⌘I --- # bd federation - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/federation#content-area) Generated from `bd help --doc federation`. Federation commands require CGO and the Dolt storage backend. This binary was built without CGO support. To use federation features: 1. Use pre-built binaries from GitHub releases, or 2. Build from source with CGO enabled Federation enables synchronized issue tracking across multiple workspaces, each maintaining their own Dolt database while sharing updates via remotes. bd federation [flags] [bd export](https://beads.gascity.com/cli-reference/export) [bd find-duplicates](https://beads.gascity.com/cli-reference/find-duplicates) ⌘I --- # bd gc - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/gc#content-area) Generated from `bd help --doc gc`. Full lifecycle garbage collection for standalone Beads databases. Runs three phases in sequence: 1. DECAY — Delete closed issues older than N days (default 90) 2. COMPACT — Squash old Dolt commits into fewer commits (bd compact) 3. GC — Run Dolt garbage collection to reclaim disk space Each phase can be skipped individually. Use —dry-run to preview all phases without making changes. Examples: bd gc # Full GC with defaults (90 day decay) bd gc —dry-run # Preview what would happen bd gc —older-than 30 # Decay issues closed 30+ days ago bd gc —skip-decay # Skip issue deletion, just compact+GC bd gc —skip-dolt # Skip Dolt GC, just decay+compact bd gc —force # Skip confirmation prompt bd gc [flags] **Flags:** --dry-run Preview without making changes -f, --force Skip confirmation prompts --older-than int Delete closed issues older than N days (default 90) --skip-decay Skip issue deletion phase --skip-dolt Skip Dolt garbage collection phase [bd gate](https://beads.gascity.com/cli-reference/gate) [bd github](https://beads.gascity.com/cli-reference/github) ⌘I --- # bd forget - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/forget#content-area) Generated from `bd help --doc forget`. Remove a memory by its key. Use ‘bd memories’ to see available keys. Examples: bd forget dolt-phantoms bd forget auth-jwt bd forget <key> [flags] [bd flatten](https://beads.gascity.com/cli-reference/flatten) [bd formula](https://beads.gascity.com/cli-reference/formula) ⌘I --- # bd history - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/history#content-area) Generated from `bd help --doc history`. Show the complete version history of an issue, including all commits where the issue was modified. Examples: bd history bd-123 # Show all history for issue bd-123 bd history bd-123 —limit 5 # Show last 5 changes bd history <id> [flags] **Flags:** --limit int Limit number of history entries (0 = all) [bd graph](https://beads.gascity.com/cli-reference/graph) [bd hooks](https://beads.gascity.com/cli-reference/hooks) ⌘I --- # bd link - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/link#content-area) Generated from `bd help --doc link`. Link two issues with a dependency. Shorthand for ‘bd dep add <id1> <id2>’. By default creates a “blocks” dependency (id2 blocks id1). Use —type to specify a different relationship. Examples: bd link bd-123 bd-456 # bd-456 blocks bd-123 bd link bd-123 bd-456 —type related # bd-123 related to bd-456 bd link bd-123 bd-456 —type parent-child bd link <id1> <id2> [flags] **Flags:** -t, --type string Dependency type (blocks|tracks|related|parent-child|discovered-from) (default "blocks") [bd linear](https://beads.gascity.com/cli-reference/linear) [bd lint](https://beads.gascity.com/cli-reference/lint) ⌘I --- # bd note - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/note#content-area) Generated from `bd help --doc note`. Append a note to an issue’s notes field. Shorthand for ‘bd update <id> —append-notes “text”’. Examples: bd note gt-abc “Fixed the flaky test” bd note gt-abc Fixed the flaky test echo “note from pipe” | bd note gt-abc —stdin bd note gt-abc —file notes.txt bd note <id> [text...] [flags] **Flags:** --file string Read note text from file --stdin Read note text from stdin [bd mol](https://beads.gascity.com/cli-reference/mol) [bd notion](https://beads.gascity.com/cli-reference/notion) ⌘I --- # bd onboard - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/onboard#content-area) Generated from `bd help --doc onboard`. Display a minimal snippet to add to your agent instructions file for bd integration. By default, the agent instructions file is AGENTS.md. Use ‘bd init —agents-file’ to configure a different filename (e.g. BEADS.md). This outputs a small (~10 line) snippet that points to ‘bd prime’ for full workflow context. This is the same minimal profile that ‘bd init’ generates by default. This approach: • Keeps your agent file lean (doesn’t bloat with instructions) • bd prime provides dynamic, always-current workflow details • Hooks auto-inject bd prime at session start For agents or environments that do not auto-inject hook output, use ‘bd init —agents-profile=full’ to embed the complete command reference. bd onboard [flags] [bd notion](https://beads.gascity.com/cli-reference/notion) [bd orphans](https://beads.gascity.com/cli-reference/orphans) ⌘I --- # bd info - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/info#content-area) Generated from `bd help --doc info`. Display information about the current database. This command helps debug issues where bd is using an unexpected database. It shows: * The absolute path to the database file * Database statistics (issue count) * Schema information (with —schema flag) * What’s new in recent versions (with —whats-new flag) Examples: bd info bd info —json bd info —schema —json bd info —whats-new bd info —whats-new —json bd info —thanks bd info [flags] **Flags:** --json Output in JSON format --schema Include schema information in output --thanks Show thank you page for contributors --whats-new Show agent-relevant changes from recent versions [bd import](https://beads.gascity.com/cli-reference/import) [bd init-safety](https://beads.gascity.com/cli-reference/init-safety) ⌘I --- # bd memories - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/memories#content-area) Generated from `bd help --doc memories`. List all memories, or search by keyword. Examples: bd memories # list all memories bd memories dolt # search for memories about dolt bd memories “race flag” # search for a phrase bd memories [search] [flags] [bd mail](https://beads.gascity.com/cli-reference/mail) [bd merge-slot](https://beads.gascity.com/cli-reference/merge-slot) ⌘I --- # bd orphans - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/orphans#content-area) Generated from `bd help --doc orphans`. Identify orphaned issues - issues that are referenced in commit messages but remain open or in\_progress in the database. This helps identify work that has been implemented but not formally closed. Examples: bd orphans # Show orphaned issues bd orphans —json # Machine-readable output bd orphans —details # Show full commit information bd orphans —fix # Close orphaned issues with confirmation bd orphans —label theme:personal # Only orphans with this label bd orphans —label-any theme:personal,theme:ventures # Orphans with either label bd orphans [flags] **Flags:** --details Show full commit information -f, --fix Close orphaned issues with confirmation -l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any --label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label [bd onboard](https://beads.gascity.com/cli-reference/onboard) [bd ping](https://beads.gascity.com/cli-reference/ping) ⌘I --- # bd priority - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/priority#content-area) Generated from `bd help --doc priority`. Set the priority of an issue. Shorthand for ‘bd update <id> —priority <n>’. Priority levels: 0 - Critical (security, data loss, broken builds) 1 - High (major features, important bugs) 2 - Medium (default) 3 - Low (polish, optimization) 4 - Backlog (future ideas) Examples: bd priority bd-123 0 # Critical bd priority bd-123 2 # Medium bd priority <id> <n> [flags] [bd prime](https://beads.gascity.com/cli-reference/prime) [bd promote](https://beads.gascity.com/cli-reference/promote) ⌘I --- # bd ping - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/ping#content-area) Generated from `bd help --doc ping`. Lightweight health check that confirms bd can reach its database. Steps: 1. Resolve the .beads workspace 2. Open the store (embedded or server) 3. Run a trivial query (issue count) 4. Report timing Exit 0 on success, exit 1 on failure. Examples: bd ping # Quick connectivity check bd ping —json # Structured output for automation bd ping [flags] [bd orphans](https://beads.gascity.com/cli-reference/orphans) [bd preflight](https://beads.gascity.com/cli-reference/preflight) ⌘I --- # bd preflight - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/preflight#content-area) Generated from `bd help --doc preflight`. Display a checklist of common pre-PR checks for contributors. This command helps catch common issues before pushing to CI: * Tests not run locally * Lint errors * Unformatted Go files * .beads/issues.jsonl pollution * Stale nix vendorHash * Version mismatches Examples: bd preflight # Show checklist bd preflight —check # Run checks automatically bd preflight —check —json # JSON output for programmatic use bd preflight —check —skip-lint # Explicitly skip lint check bd preflight [flags] **Flags:** --check Run checks automatically --fix Auto-fix issues where possible (not yet implemented) --json Output results as JSON --skip-lint Skip lint check explicitly [bd ping](https://beads.gascity.com/cli-reference/ping) [bd prime](https://beads.gascity.com/cli-reference/prime) ⌘I --- # bd promote - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/promote#content-area) Generated from `bd help --doc promote`. Promote a wisp (ephemeral issue) to a permanent bead. This copies the issue from the wisps table (dolt\_ignored) to the permanent issues table (Dolt-versioned), preserving labels, dependencies, events, and comments. The original ID is preserved so all links keep working. A comment is added recording the promotion and optional reason. Examples: bd promote bd-wisp-abc123 bd promote bd-wisp-abc123 —reason “Worth tracking long-term” bd promote <wisp-id> [flags] **Flags:** -r, --reason string Reason for promotion [bd priority](https://beads.gascity.com/cli-reference/priority) [bd prune](https://beads.gascity.com/cli-reference/prune) ⌘I --- # bd q - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/q#content-area) Generated from `bd help --doc q`. Quick capture creates an issue and outputs only the issue ID. Designed for scripting and AI agent integration. Example: bd q “Fix login bug” # Outputs: bd-a1b2 ISSUE=$(bd q “New feature”) # Capture ID in variable bd q “Task” | xargs bd show # Pipe to other commands bd q [title] [flags] **Flags:** -l, --labels strings Labels -p, --priority string Priority (0-4 or P0-P4) (default "2") -t, --type string Issue type (default "task") [bd purge](https://beads.gascity.com/cli-reference/purge) [bd query](https://beads.gascity.com/cli-reference/query) ⌘I --- # bd recompute-blocked - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/recompute-blocked#content-area) Generated from `bd help --doc recompute-blocked`. Recompute the denormalized is\_blocked flag for every issue and wisp. is\_blocked is derived from the dependency graph and maintained automatically by local writes and by a post-pull recompute scoped to what the merge changed. If that scoped recompute is skipped — a recompute that failed after its merge committed, or a conflicted pull resolved by hand — the flag can go stale, and a later pull that merges nothing will not refresh it (bd-6dnrw.37). ‘bd ready’ trusts the flag, so stale values silently hide ready work or surface blocked work. This command runs the full recompute unconditionally and commits the result. It is idempotent: on a consistent database it changes nothing. Works in both embedded and server mode (unlike ‘bd doctor’, which is server-mode only). Examples: bd recompute-blocked # Repair stale is\_blocked flags bd recompute-blocked —json # Machine-parseable {“rows\_corrected”: N} bd recompute-blocked [flags] [bd recall](https://beads.gascity.com/cli-reference/recall) [bd remember](https://beads.gascity.com/cli-reference/remember) ⌘I --- # bd rename - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/rename#content-area) Generated from `bd help --doc rename`. Rename an issue from one ID to another. This updates: * The issue’s primary ID * All references in other issues (descriptions, titles, notes, etc.) * Dependencies pointing to/from this issue * Labels, comments, and events Examples: bd rename bd-w382l bd-dolt # Rename to memorable ID bd rename gt-abc123 gt-auth # Use descriptive ID Note: The new ID must use a valid prefix for this database. bd rename <old-id> <new-id> [flags] [bd rename-prefix](https://beads.gascity.com/cli-reference/rename-prefix) [bd reopen](https://beads.gascity.com/cli-reference/reopen) ⌘I --- # bd remember - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/remember#content-area) Generated from `bd help --doc remember`. Store a memory that persists across sessions and account rotations. Memories are injected at prime time (bd prime) so you have them in every session without manual loading. The positional arg is the memory CONTENT (the key is auto-generated from it unless —key is given). As a convenience, if the arg is a bare key naming an existing memory, it is RECALLED instead of stored (same as ‘bd recall’); a bare key naming nothing is refused. Use —key to store slug-like content. Examples: bd remember “always run tests with -race flag” bd remember “Dolt phantom DBs hide in three places” —key dolt-phantoms bd remember “auth module uses JWT not sessions” —key auth-jwt bd remember dolt-phantoms # bare existing key: reads it (= bd recall) bd remember "<insight>" [flags] **Flags:** --key string Explicit key for the memory (auto-generated from content if not set). If a memory with this key already exists, it will be updated in place [bd recompute-blocked](https://beads.gascity.com/cli-reference/recompute-blocked) [bd rename-prefix](https://beads.gascity.com/cli-reference/rename-prefix) ⌘I --- # bd reopen - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/reopen#content-area) Generated from `bd help --doc reopen`. Reopen closed issues by setting status to ‘open’ and clearing the closed\_at timestamp. This is more explicit than ‘bd update —status open’ and emits a Reopened event. bd reopen [id...] [flags] **Flags:** -r, --reason string Reason for reopening [bd rename](https://beads.gascity.com/cli-reference/rename) [bd repo](https://beads.gascity.com/cli-reference/repo) ⌘I --- # bd restore - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/restore#content-area) Generated from `bd help --doc restore`. Restore the pre-compaction content of a compacted issue. When an issue is compacted, its description/design/notes/acceptance criteria are summarized and the originals are archived to a compaction snapshot. This command recovers that original content. By default it is read-only: it displays the archived content without modifying the database. Pass —apply to write the original content back into the issue and step its compaction level back down. If no archived snapshot exists (e.g. the issue was compacted by an older bd before snapshot archiving), restore falls back to a best-effort reconstruction from Dolt version history, which can only be displayed, not applied. bd restore <issue-id> [flags] **Flags:** --apply Write the restored content back into the issue (default: display only) --json Output restore results in JSON format [bd repo](https://beads.gascity.com/cli-reference/repo) [bd rules](https://beads.gascity.com/cli-reference/rules) ⌘I --- # bd set-state - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/set-state#content-area) Generated from `bd help --doc set-state`. Atomically set operational state on an issue. This command: 1. Creates an event bead recording the state change (source of truth) 2. Removes any existing label for the dimension 3. Adds the new dimension:value label (fast lookup cache) State labels follow the convention <dimension>:<value>, for example: patrol:active, patrol:muted mode:normal, mode:degraded health:healthy, health:failing Examples: bd set-state agent-abc patrol=muted —reason “Investigating stuck worker” bd set-state agent-abc mode=degraded —reason “High error rate detected” bd set-state agent-abc health=healthy The —reason flag provides context for the event bead (recommended). bd set-state <issue-id> <dimension>=<value> [flags] **Flags:** --reason string Reason for the state change (recorded in event) [bd search](https://beads.gascity.com/cli-reference/search) [bd setup](https://beads.gascity.com/cli-reference/setup) ⌘I --- # bd ship - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/ship#content-area) Generated from `bd help --doc ship`. Ship a capability to satisfy cross-project dependencies. This command: 1. Finds issue with export:<capability> label 2. Validates issue is closed (or —force to override) 3. Adds provides:<capability> label External projects can depend on this capability using: bd dep add <issue> external:<project>:<capability> The capability is resolved when the external project has a closed issue with the provides:<capability> label. Examples: bd ship mol-run-assignee # Ship the mol-run-assignee capability bd ship mol-run-assignee —force # Ship even if issue is not closed bd ship mol-run-assignee —dry-run # Preview without making changes bd ship <capability> [flags] **Flags:** --dry-run Preview without making changes --force Ship even if issue is not closed [bd setup](https://beads.gascity.com/cli-reference/setup) [bd show](https://beads.gascity.com/cli-reference/show) ⌘I --- # bd show - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/show#content-area) Generated from `bd help --doc show`. Show issue details bd show [id...] [--id=<id>...] [--current] [flags] **Aliases:** view **Flags:** --as-of string Show issue as it existed at a specific commit hash or branch (requires Dolt) --children Show only the children of this issue --current Show the currently active issue (in-progress, hooked, or last touched) --id stringArray Issue ID (use for IDs that look like flags, e.g., --id=gt--xyz) --include-comments Stream full comment bodies in JSON output (--json only; may be slow on issues with many comments) --include-dependents Stream full dependent issues in JSON output (--json only; may be slow on hub beads) --local-time Show timestamps in local time instead of UTC --long Show all available fields (extended metadata, agent identity, gate fields, etc.) --refs Show issues that reference this issue (reverse lookup) --short Show compact one-line output per issue --thread Show full conversation thread (for messages) -w, --watch Watch for changes and auto-refresh display [bd ship](https://beads.gascity.com/cli-reference/ship) [bd sql](https://beads.gascity.com/cli-reference/sql) ⌘I --- # bd stale - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/stale#content-area) Generated from `bd help --doc stale`. Show issues that haven’t been updated recently and may need attention. This helps identify: * In-progress issues with no recent activity (may be abandoned) * Open issues that have been forgotten * Issues that might be outdated or no longer relevant bd stale [flags] **Flags:** -d, --days int Issues not updated in this many days (default 30) -n, --limit int Maximum issues to show (default 50) -s, --status string Filter by status (open|in_progress|blocked|deferred) [bd sql](https://beads.gascity.com/cli-reference/sql) [bd state](https://beads.gascity.com/cli-reference/state) ⌘I --- # bd status - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/status#content-area) Generated from `bd help --doc status`. Show a quick snapshot of the issue database state and statistics. This command provides a summary of issue counts by state (open, in\_progress, blocked, closed), ready work, extended statistics (pinned issues, average lead time), and recent activity over the last 24 hours from git history. Similar to how ‘git status’ shows working tree state, ‘bd status’ gives you a quick overview of your issue database without needing multiple queries. Use cases: * Quick project health check * Onboarding for new contributors * Integration with shell prompts or CI/CD * Daily standup reference Examples: bd status # Show summary with activity bd status —no-activity # Skip git activity (faster) bd status —json # JSON format output bd status —assigned # Show issues assigned to current user bd stats # Alias for bd status bd status [flags] **Aliases:** stats **Flags:** --all Show all issues (default behavior) --assigned Show issues assigned to current user --no-activity Skip git activity tracking (faster) [bd state](https://beads.gascity.com/cli-reference/state) [bd statuses](https://beads.gascity.com/cli-reference/statuses) ⌘I --- # bd statuses - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/statuses#content-area) Generated from `bd help --doc statuses`. List all valid issue statuses and their categories. Built-in statuses (open, in\_progress, blocked, etc.) are always valid. Additional statuses can be configured via status.custom: bd config set status.custom “in\_review:active,qa\_testing:wip,on\_hold:frozen” Categories control behavior: active — appears in ‘bd ready’ and default ‘bd list’ wip — excluded from ‘bd ready’, visible in default ‘bd list’ done — excluded from ‘bd ready’ and default ‘bd list’ frozen — excluded from ‘bd ready’ and default ‘bd list’ Statuses without a category (legacy format) are valid but excluded from ‘bd ready’. Examples: bd statuses # List all statuses with icons and categories bd statuses —json # Output as JSON bd statuses [flags] [bd status](https://beads.gascity.com/cli-reference/status) [bd supersede](https://beads.gascity.com/cli-reference/supersede) ⌘I --- # bd tag - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/tag#content-area) Generated from `bd help --doc tag`. Add a label to an issue. Shorthand for ‘bd update <id> —add-label <label>’. Examples: bd tag bd-123 bug bd tag bd-123 needs-review bd tag <id> <label> [flags] [bd swarm](https://beads.gascity.com/cli-reference/swarm) [bd todo](https://beads.gascity.com/cli-reference/todo) ⌘I --- # bd undefer - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/undefer#content-area) Generated from `bd help --doc undefer`. Undefer issues to restore them to open status. This brings issues back from the icebox so they can be worked on again. Issues will appear in ‘bd ready’ if they have no blockers. Examples: bd undefer bd-abc # Undefer a single issue bd undefer bd-abc bd-def # Undefer multiple issues bd undefer [id...] [flags] [bd types](https://beads.gascity.com/cli-reference/types) [bd update](https://beads.gascity.com/cli-reference/update) ⌘I --- # bd duplicate - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/duplicate#content-area) Generated from `bd help --doc duplicate`. Mark an issue as a duplicate of a canonical issue. The duplicate issue is automatically closed with a reference to the canonical. This is essential for large issue databases with many similar reports. Examples: bd duplicate bd-abc —of bd-xyz # Mark bd-abc as duplicate of bd-xyz bd duplicate <id> --of <canonical> [flags] **Flags:** --of string Canonical issue ID (required) [bd dolt](https://beads.gascity.com/cli-reference/dolt) [bd duplicates](https://beads.gascity.com/cli-reference/duplicates) ⌘I --- # bd version - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/version#content-area) Generated from `bd help --doc version`. Print version information bd version [flags] [bd vc](https://beads.gascity.com/cli-reference/vc) [bd where](https://beads.gascity.com/cli-reference/where) ⌘I --- # bd flatten - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/flatten#content-area) Generated from `bd help --doc flatten`. Nuclear option: squash ALL Dolt commit history into a single commit. This uses the Tim Sehn recipe: 1. Create a new branch from the current state 2. Soft-reset to the initial commit (preserving all data) 3. Commit everything as a single snapshot 4. Swap main branch to the new flattened branch 5. Run Dolt GC to reclaim space from old history This is irreversible — all commit history is lost. The resulting database has exactly one commit containing all current data. Use this when: * Your .beads/dolt directory has grown very large * You don’t need commit-level history (time travel) * You want to start fresh with minimal storage Examples: bd flatten —dry-run # Preview: show commit count and disk usage bd flatten —force # Actually squash all history bd flatten —force —json # JSON output bd flatten [flags] **Flags:** --dry-run Preview without making changes -f, --force Confirm irreversible history squash [bd find-duplicates](https://beads.gascity.com/cli-reference/find-duplicates) [bd forget](https://beads.gascity.com/cli-reference/forget) ⌘I --- # bd export - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/export#content-area) Generated from `bd help --doc export`. Export all issues to JSONL (newline-delimited JSON) format. Each line is a complete JSON object representing one issue, including its labels, dependencies, and comments. This command is for issue export, migration, and interoperability. It exports records from the issues table; it is not a full database backup and does not capture Dolt branches, commit history, working-set state, or non-issue tables. For supported full backup/restore flows, use ‘bd backup init’, ‘bd backup sync’, and ‘bd backup restore’. By default, exports only regular issues (excluding infrastructure beads like agents, roles, and messages). Use —all to include everything. Memories (from ‘bd remember’) are excluded by default because they may contain sensitive agent context. Use —include-memories or —all to include them. EXAMPLES: bd export # Export issues to stdout bd export -o issues.jsonl # Export issues to file bd export —include-memories # Export issues + memories bd export —all -o full.jsonl # Include infra + templates + gates + memories bd export —scrub -o clean.jsonl # Exclude test/pollution records bd export [flags] **Flags:** --all Include all records (infra, templates, gates, memories) --include-infra Include infrastructure beads (agents, roles, messages) --include-memories Include persistent memories (from 'bd remember') in the export -o, --output string Output file path (default: stdout) --scrub Exclude test/pollution records [bd epic](https://beads.gascity.com/cli-reference/epic) [bd federation](https://beads.gascity.com/cli-reference/federation) ⌘I --- # bd init-safety - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/init-safety#content-area) Generated from `bd help --doc init-safety`. bd init flag safety contract. Every bd init invocation resolves project\_id from exactly one explicitly named source (local reinit, remote adoption, or a fresh mint). When the source is ambiguous, bd init refuses. FLAG SURFACE bd init Mint a new identity. Bootstraps from origin if it has refs/dolt/data. bd init —reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize discarding remote history. If origin has Dolt data this will refuse — pair with —discard-remote to override. bd init —reinit-local \\ Discard the remote’s Dolt history and —discard-remote replace it with the local reinit. First bd dolt push after this will be a history-replacing force-push. bd init —force Deprecated alias for —reinit-local. Kept working for ≥2 releases. bd init —from-jsonl Import from configured import.path. If origin has Dolt data, this refuses unless —discard-remote authorizes replacing that remote history. ADOPTING A REMOTE If you want to use the remote’s existing history, use: bd bootstrap bd init will automatically suggest this when a remote is detected. DESTROY-TOKEN (non-interactive only) When running with no TTY (CI, agents, piped input), —discard-remote requires an explicit —destroy-token value. The token format is: DESTROY-<issue-prefix> For example, if your issue prefix is “bd”, the token is “DESTROY-bd”: bd init —reinit-local —discard-remote —destroy-token=DESTROY-bd In interactive (TTY) mode you confirm via a typed prompt instead. The token is not echoed by bd’s runtime error messages — this is a deliberate guard against pattern-matched one-liners (see docs/adr/0002-init-safety-invariants.md). EXIT CODES 10 refused: remote has Dolt history and you selected local history without —discard-remote 11 refused: existing local data and you declined the destroy confirm 12 refused: —discard-remote passed without a valid —destroy-token (non-interactive mode) RECOVERY If you hit a refusal, see docs/RECOVERY.md for step-by-step recovery playbooks for each exit code. bd init-safety [flags] [bd info](https://beads.gascity.com/cli-reference/info) [bd init](https://beads.gascity.com/cli-reference/init) ⌘I --- # bd lint - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/lint#content-area) Generated from `bd help --doc lint`. Check issues for missing recommended sections based on issue type. By default, lints all open issues. Specify issue IDs to lint specific issues. Section requirements by type: bug: Steps to Reproduce, Acceptance Criteria task: Acceptance Criteria feature: Acceptance Criteria epic: Success Criteria chore: (none) Examples: bd lint # Lint all open issues bd lint bd-abc # Lint specific issue bd lint bd-abc bd-def # Lint multiple issues bd lint —type bug # Lint only bugs bd lint —status all # Lint all issues (including closed) bd lint [issue-id...] [flags] **Flags:** -s, --status string Filter by status (default: open, use 'all' for all) -t, --type string Filter by issue type (bug, task, feature, epic) [bd link](https://beads.gascity.com/cli-reference/link) [bd list](https://beads.gascity.com/cli-reference/list) ⌘I --- # bd rename-prefix - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/rename-prefix#content-area) Generated from `bd help --doc rename-prefix`. Rename the issue prefix for all issues in the database. This will update all issue IDs and all text references across all fields. USE CASES: * Shortening long prefixes (e.g., ‘knowledge-work-’ → ‘kw-’) * Rebranding project naming conventions * Consolidating multiple prefixes after database corruption * Migrating to team naming standards Prefix validation rules: * Max length: 8 characters * Allowed characters: lowercase letters, numbers, hyphens * Must start with a letter * Must end with a hyphen (e.g., ‘kw-’, ‘work-’) * Cannot be empty or just a hyphen Multiple prefix detection and repair: If issues have multiple prefixes (corrupted database), use —repair to consolidate them. The —repair flag will rename all issues with incorrect prefixes to the new prefix, preserving issues that already have the correct prefix. EXAMPLES: bd rename-prefix kw- # Rename from ‘knowledge-work-’ to ‘kw-’ bd rename-prefix mtg- —repair # Consolidate multiple prefixes into ‘mtg-’ bd rename-prefix team- —dry-run # Preview changes without applying NOTE: This is a rare operation. Most users never need this command. bd rename-prefix <new-prefix> [flags] **Flags:** --dry-run Preview changes without applying them --repair Repair database with multiple prefixes by consolidating them [bd remember](https://beads.gascity.com/cli-reference/remember) [bd rename](https://beads.gascity.com/cli-reference/rename) ⌘I --- # bd purge - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/purge#content-area) Generated from `bd help --doc purge`. Permanently delete closed ephemeral beads and their associated data. Closed ephemeral beads (wisps, transient molecules) accumulate rapidly and have no value once closed. This command removes them to reclaim storage. Deletes: issues, dependencies, labels, events, and comments for matching beads. Skips: pinned beads (protected). To delete closed non-ephemeral beads (regular tasks, features, bugs, etc.) use `bd prune` instead. For full Dolt storage reclaim after deleting many rows, follow with `bd flatten` so history can be collapsed and old chunks can be garbage-collected. EXAMPLES: bd purge # Preview what would be purged bd purge —force # Delete all closed ephemeral beads bd purge —older-than 7d —force # Only purge items closed 7+ days ago bd purge —pattern “_\-wisp-_” # Only purge matching ID pattern bd purge —dry-run # Detailed preview with stats bd purge [flags] **Flags:** --dry-run Preview what would be purged with stats -f, --force Actually purge (without this, shows preview) --older-than string Only purge beads closed more than N ago (e.g., 7d, 2w, 30) --pattern string Only purge beads matching ID glob pattern (e.g., *-wisp-*) [bd prune](https://beads.gascity.com/cli-reference/prune) [bd q](https://beads.gascity.com/cli-reference/q) ⌘I --- # bd quickstart - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/quickstart#content-area) Generated from `bd help --doc quickstart`. Display a quick start guide showing common bd workflows and patterns. bd quickstart [flags] [bd query](https://beads.gascity.com/cli-reference/query) [bd ready](https://beads.gascity.com/cli-reference/ready) ⌘I --- # bd sql - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/sql#content-area) Generated from `bd help --doc sql`. Execute a raw SQL query against the underlying database (SQLite or Dolt). Useful for debugging, maintenance, and working around bugs in higher-level commands. Examples: bd sql ‘SELECT COUNT(\*) FROM issues’ bd sql ‘SELECT id, title FROM issues WHERE status = “open” LIMIT 5’ bd sql ‘DELETE FROM dirty\_issues WHERE issue\_id = “bd-abc123”’ bd sql —csv ‘SELECT id, title, status FROM issues’ The query is passed directly to the database. SELECT queries return results as a table (or JSON/CSV with —json/—csv). Non-SELECT queries (INSERT, UPDATE, DELETE) report the number of rows affected. WARNING: Direct database access bypasses the storage layer. Use with caution. bd sql <query> [flags] **Flags:** --csv Output results in CSV format [bd show](https://beads.gascity.com/cli-reference/show) [bd stale](https://beads.gascity.com/cli-reference/stale) ⌘I --- # bd supersede - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/supersede#content-area) Generated from `bd help --doc supersede`. Mark an issue as superseded by a newer version. The superseded issue is automatically closed with a reference to the replacement. Useful for design docs, specs, and evolving artifacts. Examples: bd supersede bd-old —with bd-new # Mark bd-old as superseded by bd-new bd supersede <id> --with <new> [flags] **Flags:** --with string Replacement issue ID (required) [bd statuses](https://beads.gascity.com/cli-reference/statuses) [bd swarm](https://beads.gascity.com/cli-reference/swarm) ⌘I --- # bd types - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/types#content-area) Generated from `bd help --doc types`. List all valid issue types that can be used with bd create —type. Core work types (bug, task, feature, chore, epic, decision) are always valid. Additional types require configuration via types.custom in .beads/config.yaml. Examples: bd types # List all types with descriptions bd types —json # Output as JSON bd types [flags] [bd todo](https://beads.gascity.com/cli-reference/todo) [bd undefer](https://beads.gascity.com/cli-reference/undefer) ⌘I --- # bd duplicates - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/duplicates#content-area) Generated from `bd help --doc duplicates`. Find issues with identical content (title, description, design, acceptance criteria). Groups issues by content hash and reports duplicates with suggested merge targets. The merge target is chosen by: 1. Reference count (most referenced issue wins) 2. Lexicographically smallest ID if reference counts are equal Only groups issues with matching status (open with open, closed with closed). Example: bd duplicates # Show all duplicate groups bd duplicates —auto-merge # Automatically merge all duplicates bd duplicates —dry-run # Show what would be merged bd duplicates [flags] **Flags:** --auto-merge Automatically merge all duplicates --dry-run Show what would be merged without making changes [bd duplicate](https://beads.gascity.com/cli-reference/duplicate) [bd edit](https://beads.gascity.com/cli-reference/edit) ⌘I --- # bd where - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/where#content-area) Generated from `bd help --doc where`. Show the active beads database location, including redirect information. This command is useful for debugging when using redirects, to understand which beads workspace is actually being used. Examples: bd where # Show active beads location bd where —json # Output in JSON format bd where [flags] [bd version](https://beads.gascity.com/cli-reference/version) [bd worktree](https://beads.gascity.com/cli-reference/worktree) ⌘I --- # bd epic - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/epic#content-area) Generated from `bd help --doc epic`. Epic management commands bd epic [flags] [​](https://beads.gascity.com/cli-reference/epic#bd-epic-close-eligible) bd epic close-eligible -------------------------------------------------------------------------------------------------- Close epics where all children are complete bd epic close-eligible [flags] **Flags:** --dry-run Preview what would be closed without making changes [​](https://beads.gascity.com/cli-reference/epic#bd-epic-status) bd epic status ---------------------------------------------------------------------------------- Show epic completion status bd epic status [flags] **Flags:** --eligible-only Show only epics eligible for closure [bd edit](https://beads.gascity.com/cli-reference/edit) [bd export](https://beads.gascity.com/cli-reference/export) ⌘I --- # bd find-duplicates - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/find-duplicates#content-area) Generated from `bd help --doc find-duplicates`. Find issues that are semantically similar but not exact duplicates. Unlike ‘bd duplicates’ which finds exact content matches, find-duplicates uses text similarity or AI to find issues that discuss the same topic with different wording. Approaches: mechanical Token-based text similarity (default, no API key needed) ai LLM-based semantic comparison (requires ANTHROPIC\_API\_KEY or ai.api\_key) The mechanical approach tokenizes titles and descriptions, then computes Jaccard similarity between all issue pairs. It’s fast and free but may miss semantically similar issues with very different wording. The AI approach sends candidate pairs to Claude for semantic comparison. It first uses mechanical pre-filtering to reduce the number of API calls, then asks the LLM to judge whether the remaining pairs are true duplicates. Examples: bd find-duplicates # Mechanical similarity (default) bd find-duplicates —threshold 0.4 # Lower threshold = more results bd find-duplicates —method ai # Use AI for semantic comparison bd find-duplicates —status open # Only check open issues bd find-duplicates —limit 20 # Show top 20 pairs bd find-duplicates —json # JSON output bd find-duplicates [flags] **Aliases:** find-dups **Flags:** -n, --limit int Maximum number of pairs to show (default 50) --method string Detection method: mechanical, ai (default "mechanical") --model string AI model to use (only with --method ai; default from config ai.model) -s, --status string Filter by status (default: non-closed) --threshold float Similarity threshold (0.0-1.0, lower = more results) (default 0.5) [bd federation](https://beads.gascity.com/cli-reference/federation) [bd flatten](https://beads.gascity.com/cli-reference/flatten) ⌘I --- # bd mail - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/mail#content-area) Generated from `bd help --doc mail`. Delegates mail operations to an external mail provider. Agents often type ‘bd mail’ when working with beads, but mail functionality is typically provided by the orchestrator. This command bridges that gap by delegating to the configured mail provider. Configuration (checked in order): 1. BEADS\_MAIL\_DELEGATE or BD\_MAIL\_DELEGATE environment variable 2. ‘mail.delegate’ config setting (bd config set mail.delegate “gt mail”) Examples: [​](https://beads.gascity.com/cli-reference/mail#configure-delegation-one-time-setup) Configure delegation (one-time setup) ============================================================================================================================== `export BEADS_MAIL_DELEGATE="gt mail"` [​](https://beads.gascity.com/cli-reference/mail#or) or ========================================================== bd config set mail.delegate “gt mail” [​](https://beads.gascity.com/cli-reference/mail#then-use-bd-mail-as-if-it-were-gt-mail) Then use bd mail as if it were gt mail ================================================================================================================================== bd mail inbox # Lists inbox bd mail send mayor/ -s “Hi” # Sends mail bd mail read msg-123 # Reads a message bd mail [subcommand] [args...] [flags] [bd list](https://beads.gascity.com/cli-reference/list) [bd memories](https://beads.gascity.com/cli-reference/memories) ⌘I --- # bd prime - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/prime#content-area) Generated from `bd help --doc prime`. Output essential Beads workflow context in AI-optimized markdown format. Automatically detects if MCP server is active and adapts output: * MCP mode: Brief workflow reminders (~50 tokens) * CLI mode: Full command reference (~1-2k tokens) Designed for Claude Code, Gemini CLI, and Codex SessionStart hooks to prevent agents from forgetting bd workflow after context compaction. Config options: * no-git-ops: When true, outputs stealth mode (no git commands in session close protocol). Set via: bd config set no-git-ops true Useful when you want to control when commits happen manually. Workflow customization: * Place a .beads/PRIME.md file in the local clone or resolved workspace to override the default output entirely. * Use —export to dump the default content for customization. * Use —memories-only for hook contexts that should inject only persistent memories. bd prime [flags] **Flags:** --export Output default content (ignores PRIME.md override) --full Force full CLI output (ignore MCP detection) --hook-json Wrap output in the SessionStart hook JSON envelope (Claude Code, Gemini CLI, Codex) --mcp Force MCP mode (minimal output) --memories-only Output only persistent memories for compact hook contexts --stealth Stealth mode (no git operations, flush only) [bd preflight](https://beads.gascity.com/cli-reference/preflight) [bd priority](https://beads.gascity.com/cli-reference/priority) ⌘I --- # bd metrics - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/metrics#content-area) Generated from `bd help --doc metrics`. Show whether anonymous usage metrics are on, see exactly what is sent, and turn them on or off. bd shares anonymous usage metrics to learn how people actually use it — just which commands get run, plus the bd version and OS platform. That’s how we decide what to polish next. We never collect your issues, paths, remotes, identity, or any user-supplied text. bd metrics show the current status and what is collected bd metrics on turn metrics on bd metrics off turn metrics off bd metrics example show real examples of the events bd sends bd metrics [flags] [​](https://beads.gascity.com/cli-reference/metrics#bd-metrics-example) bd metrics example --------------------------------------------------------------------------------------------- Show real examples of the anonymous metrics bd sends bd metrics example [flags] [​](https://beads.gascity.com/cli-reference/metrics#bd-metrics-off) bd metrics off ------------------------------------------------------------------------------------- Turn anonymous usage metrics off bd metrics off [flags] [​](https://beads.gascity.com/cli-reference/metrics#bd-metrics-on) bd metrics on ----------------------------------------------------------------------------------- Turn anonymous usage metrics on bd metrics on [flags] [bd merge-slot](https://beads.gascity.com/cli-reference/merge-slot) [bd migrate](https://beads.gascity.com/cli-reference/migrate) ⌘I --- # bd query - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/query#content-area) Generated from `bd help --doc query`. Query issues using a simple query language that supports compound filters, boolean operators, and date-relative expressions. The query language enables complex filtering that would otherwise require multiple flags or piping through jq. Syntax: field=value Equality comparison field!=value Inequality comparison field>value Greater than field>=value Greater than or equal field<value Less than field<=value Less than or equal Boolean operators (case-insensitive): expr AND expr Both conditions must match expr OR expr Either condition can match NOT expr Negates the condition (expr) Grouping with parentheses Supported fields: status Stored status (open, in\_progress, blocked, deferred, closed). Note: dependency-blocked issues stay “open”; use ‘bd blocked’ to find them priority Priority level (0-4) type Issue type (bug, feature, task, epic, chore, decision) assignee Assigned user (use “none” for unassigned) owner Issue owner label Issue label (use “none” for unlabeled) title Search in title (contains) description Search in description (contains, “none” for empty) notes Search in notes (contains) created Creation date/time updated Last update date/time started Date/time issue first transitioned to in\_progress closed Close date/time id Issue ID (supports wildcards: bd-\*) spec Spec ID (supports wildcards) pinned Boolean (true/false) ephemeral Boolean (true/false) template Boolean (true/false) parent Parent issue ID mol\_type Molecule type (swarm, patrol, work) Date values: Relative durations: 7d (7 days ago), 24h (24 hours ago), 2w (2 weeks ago) Absolute dates: 2025-01-15, 2025-01-15T10:00:00Z Natural language: tomorrow, “next monday”, “in 3 days” Examples: bd query “status=open AND priority>1” bd query “status=open AND priority<=2 AND updated>7d” bd query “(status=open OR status=blocked) AND priority<2” bd query “type=bug AND label=urgent” bd query “NOT status=closed” bd query “assignee=none AND type=task” bd query “created>30d AND status!=closed” bd query “label=frontend OR label=backend” bd query “title=authentication AND priority=0” bd query [expression] [flags] **Flags:** -a, --all Include closed issues (default: exclude closed) -n, --limit int Limit results (default: 50, 0 = unlimited) (default 50) --long Show detailed multi-line output for each issue --offset int Skip the first N matching results (0-based). Only supported under --proxied-server. --parse-only Only parse the query and show the AST (for debugging) -r, --reverse Reverse sort order --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee [bd q](https://beads.gascity.com/cli-reference/q) [bd quickstart](https://beads.gascity.com/cli-reference/quickstart) ⌘I --- # bd search - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/search#content-area) Generated from `bd help --doc search`. Search issues across title and ID (excludes closed issues by default). ID-like queries (e.g., “bd-123”, “hq-319”) use fast exact/prefix matching. Text queries search titles. Use —desc-contains for description search. Use —status all to include closed issues. Examples: bd search “authentication bug” bd search “login” —status open bd search “database” —label backend —limit 10 bd search —query “performance” —assignee alice bd search “bd-5q” # Search by partial ID (fast prefix match) bd search “security” —priority-min 0 —priority-max 2 bd search “bug” —created-after 2025-01-01 bd search “refactor” —status all # Include closed issues bd search “bug” —sort priority bd search “task” —sort created —reverse bd search “api” —desc-contains “endpoint” bd search “cleanup” —no-assignee —no-labels bd search [query] [flags] **Flags:** -a, --assignee string Filter by assignee --closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339) --closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339) --created-after string Filter issues created after date (YYYY-MM-DD or RFC3339) --created-before string Filter issues created before date (YYYY-MM-DD or RFC3339) --desc-contains string Filter by description substring (case-insensitive) --empty-description Filter issues with empty or missing description --external-contains string Filter by external ref substring (case-insensitive) --has-metadata-key string Filter issues that have this metadata key set -l, --label strings Filter by labels (AND: must have ALL) --label-any strings Filter by labels (OR: must have AT LEAST ONE) -n, --limit int Limit results (default: 50) (default 50) --long Show detailed multi-line output for each issue --metadata-field stringArray Filter by metadata field (key=value, repeatable) --no-assignee Filter issues with no assignee --no-labels Filter issues with no labels --notes-contains string Filter by notes substring (case-insensitive) --priority-max string Filter by maximum priority (inclusive, 0-4 or P0-P4) --priority-min string Filter by minimum priority (inclusive, 0-4 or P0-P4) --query string Search query (alternative to positional argument) -r, --reverse Reverse sort order --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed, all). Default excludes closed; use 'all' to include closed. Note: dependency-blocked issues use 'bd blocked' -t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate) --updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339) --updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339) [bd rules](https://beads.gascity.com/cli-reference/rules) [bd set-state](https://beads.gascity.com/cli-reference/set-state) ⌘I --- # bd setup - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/setup#content-area) Generated from `bd help --doc setup`. Setup integration files for AI editors and coding assistants. Recipes define where beads workflow instructions are written. Built-in recipes include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode. Examples: bd setup cursor # Install Cursor IDE integration bd setup codex # Install Codex skill + AGENTS.md guidance + native hooks bd setup codex —global # Install global Codex skill + guidance + native hooks bd setup copilot # Install Copilot CLI plugin + repository instructions bd setup mux —project # Install Mux workspace layer (.mux/AGENTS.md) bd setup mux —global # Install Mux global layer (~/.mux/AGENTS.md) bd setup mux —project —global # Install both Mux layers bd setup —list # Show all available recipes bd setup —print # Print the template to stdout bd setup -o rules.md # Write template to custom path bd setup —add myeditor .myeditor/rules.md # Add custom recipe Use ‘bd setup <recipe> —check’ to verify installation status. Use ‘bd setup <recipe> —remove’ to uninstall. bd setup [recipe] [flags] **Flags:** --add string Add a custom recipe with given name --check Check if integration is installed --global Install globally (claude/codex/mux; writes to ~/.claude/settings.json, $CODEX_HOME/AGENTS.md or ~/.codex/AGENTS.md, or ~/.mux/AGENTS.md) --list List all available recipes -o, --output string Write template to custom path --print Print the template to stdout --project Install for this project only (gemini/mux) --remove Remove the integration --stealth Use stealth mode (claude/gemini) [bd set-state](https://beads.gascity.com/cli-reference/set-state) [bd ship](https://beads.gascity.com/cli-reference/ship) ⌘I --- # bd ready - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/ready#content-area) Generated from `bd help --doc ready`. Show ready work (open issues with no active blockers). Excludes in\_progress, blocked, deferred, and hooked issues. This uses the GetReadyWork API which applies blocker-aware semantics to find truly claimable work. Note: ‘bd list —ready’ uses the same blocker-aware ready-work semantics. Use —mol to filter to a specific molecule’s steps: bd ready —mol bd-patrol # Show ready steps within molecule Use —gated to find molecules ready for gate-resume dispatch: bd ready —gated # Find molecules where a gate closed Use —claim to atomically claim the first ready issue matching the filters: bd ready —claim —json This is useful for agents executing molecules to see which steps can run next. bd ready [flags] **Flags:** -a, --assignee string Filter by assignee --claim Atomically claim the first ready issue matching the filters --exclude-label strings Exclude issues that have ANY of these labels --exclude-type strings Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic) --explain Show dependency-aware reasoning for why issues are ready or blocked --gated Find molecules ready for gate-resume dispatch --has-metadata-key string Filter issues that have this metadata key set --include-deferred Include issues with future defer_until timestamps --include-ephemeral Include ephemeral issues (wisps) in results -l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any --label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label -n, --limit int Maximum issues to show (use 0 for unlimited) (default 100) --metadata-field stringArray Filter by metadata field (key=value, repeatable) --mol string Filter to steps within a specific molecule --mol-type string Filter by molecule type: swarm, patrol, or work --offset int Skip the first N matching results (0-based). Only supported under --proxied-server. --parent string Filter to descendants of this bead/epic --plain Display issues as a plain numbered list --pretty Display issues in a tree format with status/priority symbols (default true) -p, --priority int Filter by priority -s, --sort string Sort policy: priority (default), hybrid, oldest (default "priority") -t, --type string Filter by issue type (task, bug, feature, epic, decision, merge-request). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision -u, --unassigned Show only unassigned issues [bd quickstart](https://beads.gascity.com/cli-reference/quickstart) [bd recall](https://beads.gascity.com/cli-reference/recall) ⌘I --- # bd rules - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/rules#content-area) Generated from `bd help --doc rules`. Audit and compact Claude rules bd rules [flags] [​](https://beads.gascity.com/cli-reference/rules#bd-rules-audit) bd rules audit ----------------------------------------------------------------------------------- Scan rules for contradictions and merge opportunities bd rules audit [flags] **Flags:** --path string Path to rules directory (default ".claude/rules/") --threshold float Jaccard similarity threshold (default 0.6) [​](https://beads.gascity.com/cli-reference/rules#bd-rules-compact) bd rules compact --------------------------------------------------------------------------------------- Merge related rules into composites bd rules compact [flags] **Flags:** --auto Apply audit suggestions --dry-run Preview without applying --group strings Rule names to merge --path string Path to rules directory (default ".claude/rules/") [bd restore](https://beads.gascity.com/cli-reference/restore) [bd search](https://beads.gascity.com/cli-reference/search) ⌘I --- # bd state - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/state#content-area) Generated from `bd help --doc state`. Query the current value of a state dimension from an issue’s labels. State labels follow the convention <dimension>:<value>, for example: patrol:active mode:degraded health:healthy This command extracts the value for a given dimension. Examples: bd state witness-abc patrol # Output: active bd state witness-abc mode # Output: normal bd state witness-abc health # Output: healthy bd state <issue-id> <dimension> [flags] [​](https://beads.gascity.com/cli-reference/state#bd-state-list) bd state list --------------------------------------------------------------------------------- List all state labels (dimension:value format) on an issue. This filters labels to only show those following the state convention. Example: bd state list witness-abc [​](https://beads.gascity.com/cli-reference/state#output) Output: ==================================================================== [​](https://beads.gascity.com/cli-reference/state#patrol-active) patrol: active ================================================================================== [​](https://beads.gascity.com/cli-reference/state#mode-normal) mode: normal ============================================================================== [​](https://beads.gascity.com/cli-reference/state#health-healthy) health: healthy ==================================================================================== bd state list <issue-id> [flags] [bd stale](https://beads.gascity.com/cli-reference/stale) [bd status](https://beads.gascity.com/cli-reference/status) ⌘I --- # bd update - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/update#content-area) Generated from `bd help --doc update`. Update one or more issues. If no issue ID is provided, updates the last touched issue (from most recent create, update, show, or close operation). bd update [id...] [flags] **Flags:** --acceptance string Acceptance criteria --add-label strings Add labels (repeatable) --allow-empty-description Allow empty description replacement when reading from stdin or file --append-notes string Append to existing notes (with newline separator) -a, --assignee string Assignee --await-id string Set gate await_id (e.g., GitHub run ID for gh:run gates) --body-file string Read description from file (use - for stdin) --claim Atomically claim the issue (sets assignee to you, status to in_progress; idempotent if already claimed by you) --defer string Defer until date (empty to clear). Issue hidden from bd ready until then -d, --description string Issue description --design string Design notes --design-file string Read design from file (use - for stdin) --due string Due date/time (empty to clear). Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15 --ephemeral Mark issue as ephemeral (wisp) - not exported to JSONL -e, --estimate int Time estimate in minutes (e.g., 60 for 1 hour) --external-ref string External reference (e.g., 'gh-9', 'jira-ABC', Linear URL) --history Clear no-history flag (re-enable Dolt commit history) --metadata string Set custom metadata (JSON string or @file.json to read from file) --no-history Mark issue as no-history (skip Dolt commits, not GC-eligible) --notes string Additional notes --parent string New parent issue ID (reparents the issue, use empty string to remove parent) --persistent Mark issue as persistent (promote wisp to regular issue) -p, --priority string Priority (0-4 or P0-P4, 0=highest) --remove-label strings Remove labels (repeatable) --session string Claude Code session ID for status=closed (or set CLAUDE_SESSION_ID env var) --set-labels strings Set labels, replacing all existing (repeatable) --set-metadata stringArray Set metadata key=value (repeatable, e.g., --set-metadata team=platform) --spec-id string Link to specification document -s, --status string New status --stdin Read description from stdin (alias for --body-file -) --title string New title -t, --type string New type (bug|feature|task|epic|chore|decision); custom types require types.custom config --unset-metadata stringArray Remove metadata key (repeatable, e.g., --unset-metadata team) [bd undefer](https://beads.gascity.com/cli-reference/undefer) [bd upgrade](https://beads.gascity.com/cli-reference/upgrade) ⌘I --- # CLI Reference - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/index#content-area) Generated from `bd help --docs-root`. This reference covers all 108 live top-level `bd` commands. Regenerate it with: ./scripts/generate-cli-docs.sh [​](https://beads.gascity.com/cli-reference/index#commands) Commands ----------------------------------------------------------------------- * [`bd admin`](https://beads.gascity.com/cli-reference/admin) * [`bd ado`](https://beads.gascity.com/cli-reference/ado) * [`bd assign`](https://beads.gascity.com/cli-reference/assign) * [`bd audit`](https://beads.gascity.com/cli-reference/audit) * [`bd backup`](https://beads.gascity.com/cli-reference/backup) * [`bd batch`](https://beads.gascity.com/cli-reference/batch) * [`bd blocked`](https://beads.gascity.com/cli-reference/blocked) * [`bd bootstrap`](https://beads.gascity.com/cli-reference/bootstrap) * [`bd branch`](https://beads.gascity.com/cli-reference/branch) * [`bd children`](https://beads.gascity.com/cli-reference/children) * [`bd close`](https://beads.gascity.com/cli-reference/close) * [`bd comment`](https://beads.gascity.com/cli-reference/comment) * [`bd comments`](https://beads.gascity.com/cli-reference/comments) * [`bd compact`](https://beads.gascity.com/cli-reference/compact) * [`bd completion`](https://beads.gascity.com/cli-reference/completion) * [`bd config`](https://beads.gascity.com/cli-reference/config) * [`bd context`](https://beads.gascity.com/cli-reference/context) * [`bd cook`](https://beads.gascity.com/cli-reference/cook) * [`bd count`](https://beads.gascity.com/cli-reference/count) * [`bd create`](https://beads.gascity.com/cli-reference/create) * [`bd create-form`](https://beads.gascity.com/cli-reference/create-form) * [`bd defer`](https://beads.gascity.com/cli-reference/defer) * [`bd delete`](https://beads.gascity.com/cli-reference/delete) * [`bd dep`](https://beads.gascity.com/cli-reference/dep) * [`bd diff`](https://beads.gascity.com/cli-reference/diff) * [`bd doctor`](https://beads.gascity.com/cli-reference/doctor) * [`bd dolt`](https://beads.gascity.com/cli-reference/dolt) * [`bd duplicate`](https://beads.gascity.com/cli-reference/duplicate) * [`bd duplicates`](https://beads.gascity.com/cli-reference/duplicates) * [`bd edit`](https://beads.gascity.com/cli-reference/edit) * [`bd epic`](https://beads.gascity.com/cli-reference/epic) * [`bd export`](https://beads.gascity.com/cli-reference/export) * [`bd federation`](https://beads.gascity.com/cli-reference/federation) * [`bd find-duplicates`](https://beads.gascity.com/cli-reference/find-duplicates) * [`bd flatten`](https://beads.gascity.com/cli-reference/flatten) * [`bd forget`](https://beads.gascity.com/cli-reference/forget) * [`bd formula`](https://beads.gascity.com/cli-reference/formula) * [`bd gate`](https://beads.gascity.com/cli-reference/gate) * [`bd gc`](https://beads.gascity.com/cli-reference/gc) * [`bd github`](https://beads.gascity.com/cli-reference/github) * [`bd gitlab`](https://beads.gascity.com/cli-reference/gitlab) * [`bd graph`](https://beads.gascity.com/cli-reference/graph) * [`bd history`](https://beads.gascity.com/cli-reference/history) * [`bd hooks`](https://beads.gascity.com/cli-reference/hooks) * [`bd human`](https://beads.gascity.com/cli-reference/human) * [`bd import`](https://beads.gascity.com/cli-reference/import) * [`bd info`](https://beads.gascity.com/cli-reference/info) * [`bd init`](https://beads.gascity.com/cli-reference/init) * [`bd init-safety`](https://beads.gascity.com/cli-reference/init-safety) * [`bd jira`](https://beads.gascity.com/cli-reference/jira) * [`bd kv`](https://beads.gascity.com/cli-reference/kv) * [`bd label`](https://beads.gascity.com/cli-reference/label) * [`bd linear`](https://beads.gascity.com/cli-reference/linear) * [`bd link`](https://beads.gascity.com/cli-reference/link) * [`bd lint`](https://beads.gascity.com/cli-reference/lint) * [`bd list`](https://beads.gascity.com/cli-reference/list) * [`bd mail`](https://beads.gascity.com/cli-reference/mail) * [`bd memories`](https://beads.gascity.com/cli-reference/memories) * [`bd merge-slot`](https://beads.gascity.com/cli-reference/merge-slot) * [`bd metrics`](https://beads.gascity.com/cli-reference/metrics) * [`bd migrate`](https://beads.gascity.com/cli-reference/migrate) * [`bd mol`](https://beads.gascity.com/cli-reference/mol) * [`bd note`](https://beads.gascity.com/cli-reference/note) * [`bd notion`](https://beads.gascity.com/cli-reference/notion) * [`bd onboard`](https://beads.gascity.com/cli-reference/onboard) * [`bd orphans`](https://beads.gascity.com/cli-reference/orphans) * [`bd ping`](https://beads.gascity.com/cli-reference/ping) * [`bd preflight`](https://beads.gascity.com/cli-reference/preflight) * [`bd prime`](https://beads.gascity.com/cli-reference/prime) * [`bd priority`](https://beads.gascity.com/cli-reference/priority) * [`bd promote`](https://beads.gascity.com/cli-reference/promote) * [`bd prune`](https://beads.gascity.com/cli-reference/prune) * [`bd purge`](https://beads.gascity.com/cli-reference/purge) * [`bd q`](https://beads.gascity.com/cli-reference/q) * [`bd query`](https://beads.gascity.com/cli-reference/query) * [`bd quickstart`](https://beads.gascity.com/cli-reference/quickstart) * [`bd ready`](https://beads.gascity.com/cli-reference/ready) * [`bd recall`](https://beads.gascity.com/cli-reference/recall) * [`bd recompute-blocked`](https://beads.gascity.com/cli-reference/recompute-blocked) * [`bd remember`](https://beads.gascity.com/cli-reference/remember) * [`bd rename`](https://beads.gascity.com/cli-reference/rename) * [`bd rename-prefix`](https://beads.gascity.com/cli-reference/rename-prefix) * [`bd reopen`](https://beads.gascity.com/cli-reference/reopen) * [`bd repo`](https://beads.gascity.com/cli-reference/repo) * [`bd restore`](https://beads.gascity.com/cli-reference/restore) * [`bd rules`](https://beads.gascity.com/cli-reference/rules) * [`bd search`](https://beads.gascity.com/cli-reference/search) * [`bd set-state`](https://beads.gascity.com/cli-reference/set-state) * [`bd setup`](https://beads.gascity.com/cli-reference/setup) * [`bd ship`](https://beads.gascity.com/cli-reference/ship) * [`bd show`](https://beads.gascity.com/cli-reference/show) * [`bd sql`](https://beads.gascity.com/cli-reference/sql) * [`bd stale`](https://beads.gascity.com/cli-reference/stale) * [`bd state`](https://beads.gascity.com/cli-reference/state) * [`bd status`](https://beads.gascity.com/cli-reference/status) * [`bd statuses`](https://beads.gascity.com/cli-reference/statuses) * [`bd supersede`](https://beads.gascity.com/cli-reference/supersede) * [`bd swarm`](https://beads.gascity.com/cli-reference/swarm) * [`bd tag`](https://beads.gascity.com/cli-reference/tag) * [`bd todo`](https://beads.gascity.com/cli-reference/todo) * [`bd types`](https://beads.gascity.com/cli-reference/types) * [`bd undefer`](https://beads.gascity.com/cli-reference/undefer) * [`bd update`](https://beads.gascity.com/cli-reference/update) * [`bd upgrade`](https://beads.gascity.com/cli-reference/upgrade) * [`bd vc`](https://beads.gascity.com/cli-reference/vc) * [`bd version`](https://beads.gascity.com/cli-reference/version) * [`bd where`](https://beads.gascity.com/cli-reference/where) * [`bd worktree`](https://beads.gascity.com/cli-reference/worktree) [FAQ](https://beads.gascity.com/reference/faq) [bd admin](https://beads.gascity.com/cli-reference/admin) ⌘I --- # bd graph - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/graph#content-area) Generated from `bd help --doc graph`. Display a visualization of an issue’s dependency graph. For epics, shows all children and their dependencies. For regular issues, shows the issue and its direct dependencies. With —all, shows all open issues grouped by connected component. Display formats: (default) DAG with columns and box-drawing edges (terminal-native) —box ASCII boxes showing layers, more detailed —compact Tree format, one line per issue, more scannable —dot Graphviz DOT format (pipe to dot -Tsvg > graph.svg) —html Self-contained interactive HTML with D3.js visualization The graph shows execution order: * Layer 0 / leftmost = no dependencies (can start immediately) * Higher layers depend on lower layers * Nodes in the same layer can run in parallel Status icons: ○ open ◐ in\_progress ● blocked ✓ closed ❄ deferred Examples: bd graph issue-id # Terminal DAG visualization (default) bd graph —box issue-id # ASCII boxes with layer grouping bd graph —dot issue-id | dot -Tsvg > graph.svg # SVG via Graphviz bd graph —dot issue-id | dot -Tpng > graph.png # PNG via Graphviz bd graph —html issue-id > graph.html # Interactive browser view bd graph —all —html > all.html # All issues, interactive bd graph [issue-id] [flags] **Flags:** --all Show graph for all open issues --box ASCII boxes showing layers --compact Tree format, one line per issue, more scannable --dot Output Graphviz DOT format (pipe to: dot -Tsvg > graph.svg) --html Output self-contained interactive HTML (redirect to file) [​](https://beads.gascity.com/cli-reference/graph#bd-graph-check) bd graph check ----------------------------------------------------------------------------------- Check the dependency graph for cycles, orphans, and other integrity issues. Returns exit code 0 if the graph is clean, 1 if issues are found. bd graph check [flags] [bd gitlab](https://beads.gascity.com/cli-reference/gitlab) [bd history](https://beads.gascity.com/cli-reference/history) ⌘I --- # bd config - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/config#content-area) Generated from `bd help --doc config`. Manage configuration settings for external integrations and preferences. Configuration is stored per-project in the beads database and is version-control-friendly. Common namespaces: * export.\* Auto-export settings (stored in config.yaml) * import.\* JSONL import settings (stored in config.yaml) * jira.\* Jira integration settings * linear.\* Linear integration settings * github.\* GitHub integration settings * custom.\* Custom integration settings * status.\* Issue status configuration * doctor.suppress.\* Suppress specific bd doctor warnings (GH#1095) Auto-Export (config.yaml): Optional JSONL export to .beads/issues.jsonl after write commands (throttled). Useful for viewers (bv), interchange, and issue-level migration; not a backup. It is not cross-machine sync; use bd dolt push/pull with a Dolt remote. Disabled by default. Enable only for integrations that need fresh JSONL. Auto-staging is separate and disabled by default. Keys: export.auto Enable/disable auto-export (default: false) export.path Output filename relative to .beads/ (default: issues.jsonl) export.interval Minimum time between exports (default: 60s) export.git-add Auto-stage the export file (default: false) Auto-Import (config.yaml): Reads .beads/issues.jsonl by default when a JSONL import path is implied. Use a relative filename/path so the import stays within the project .beads/ directory and remains portable across machines. Keys: import.path Input filename relative to .beads/ (default: issues.jsonl) Custom Status States: You can define custom status states for multi-step pipelines using the status.custom config key. Statuses should be comma-separated. Example: bd config set status.custom “awaiting\_review,awaiting\_testing,awaiting\_docs” This enables issues to use statuses like ‘awaiting\_review’ in addition to the built-in statuses (open, in\_progress, blocked, deferred, closed). Suppressing Doctor Warnings: Suppress specific bd doctor warnings by check name slug: bd config set doctor.suppress.pending-migrations true bd config set doctor.suppress.git-hooks true Check names are converted to slugs: “Git Hooks” → “git-hooks”. Only warnings are suppressed (errors and passing checks always show). To unsuppress: bd config unset doctor.suppress.<slug> Examples: bd config set export.auto true # Enable auto-export for viewer integrations bd config set export.path “beads.jsonl” # Custom export filename bd config set import.path “beads.jsonl” # Custom import filename bd config set export.git-add true # Also stage the export file bd config set jira.url “[https://company.atlassian.net](https://company.atlassian.net/) ” bd config set jira.project “PROJ” bd config set status.custom “awaiting\_review,awaiting\_testing” bd config set doctor.suppress.pending-migrations true bd config set dolt.debug true # Enable Dolt sql-server debug mode (loglevel=debug, —prof cpu) bd config set dolt.local-only true # Skip wiring a Dolt sync remote during bd init bd config get export.auto bd config list bd config unset jira.url bd config [flags] [​](https://beads.gascity.com/cli-reference/config#bd-config-apply) bd config apply -------------------------------------------------------------------------------------- Reconcile actual system state to match declared configuration. Runs drift detection and then fixes any mismatches it finds: * hooks Reinstall git hooks if missing or outdated * remote Add/update Dolt origin remote to match federation.remote * server Start Dolt server if dolt.shared-server is enabled This command is idempotent — safe to run multiple times. Use —dry-run to preview what would change without making modifications. Examples: bd config apply bd config apply —dry-run bd config apply —json bd config apply [flags] **Flags:** --dry-run Show what would change without making modifications [​](https://beads.gascity.com/cli-reference/config#bd-config-drift) bd config drift -------------------------------------------------------------------------------------- Detect drift between declared configuration and actual system state. This is a read-only diagnostic that answers “is my environment consistent with my config?” — no mutations are performed. Checks: * hooks Git hooks installed and up-to-date * remote Dolt remote matches federation.remote config * server Server state matches dolt.shared-server config Exit codes: 0 No drift detected (all checks ok/info/skipped) 1 Drift detected (at least one check has status “drift”) Examples: bd config drift bd config drift —json bd config drift [flags] [​](https://beads.gascity.com/cli-reference/config#bd-config-get) bd config get ---------------------------------------------------------------------------------- Get a configuration value bd config get <key> [flags] [​](https://beads.gascity.com/cli-reference/config#bd-config-list) bd config list ------------------------------------------------------------------------------------ List all configuration bd config list [flags] [​](https://beads.gascity.com/cli-reference/config#bd-config-set) bd config set ---------------------------------------------------------------------------------- Set a configuration value bd config set <key> <value> [flags] **Flags:** --force-git-tracked Allow writing secret keys to git-tracked config files (use with caution) [​](https://beads.gascity.com/cli-reference/config#bd-config-set-many) bd config set-many -------------------------------------------------------------------------------------------- Set multiple configuration values at once with a single auto-commit and auto-push. Each argument must be in key=value format. All values are validated before any writes occur. This is faster and less noisy than separate ‘bd config set’ calls, especially in CI. Examples: bd config set-many ado.state\_map.open=New ado.state\_map.closed=Closed bd config set-many jira.url=[https://example.atlassian.net](https://example.atlassian.net/) jira.project=PROJ bd config set-many <key=value>... [flags] **Flags:** --force-git-tracked Allow writing secret keys to git-tracked config files (use with caution) [​](https://beads.gascity.com/cli-reference/config#bd-config-show) bd config show ------------------------------------------------------------------------------------ Display a unified view of all effective configuration across all sources with annotations showing where each value comes from. Sources (by precedence for Viper-managed keys): * env Environment variable (BD\_\* or BEADS\_\*) * config.yaml Project config file (.beads/config.yaml) * default Built-in default value Additional sources: * metadata Connection settings from .beads/metadata.json * database Integration config stored in the Dolt database * git Git config (e.g., beads.role) Examples: bd config show bd config show —json bd config show —source config.yaml bd config show [flags] **Flags:** --source string Filter by source (e.g., config.yaml, env, default, metadata, database, git) [​](https://beads.gascity.com/cli-reference/config#bd-config-unset) bd config unset -------------------------------------------------------------------------------------- Delete a configuration value bd config unset <key> [flags] [​](https://beads.gascity.com/cli-reference/config#bd-config-validate) bd config validate -------------------------------------------------------------------------------------------- Validate sync-related configuration settings. Checks: * federation.sovereignty is valid (T1, T2, T3, T4, or empty) * federation.remote is set for Dolt sync * Remote URL format is valid (dolthub://, gs://, s3://, az://, file://) * routing.mode is valid (auto, maintainer, contributor, explicit) Examples: bd config validate bd config validate —json bd config validate [flags] [bd completion](https://beads.gascity.com/cli-reference/completion) [bd context](https://beads.gascity.com/cli-reference/context) ⌘I --- # bd import - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/import#content-area) Generated from `bd help --doc import`. Import issues from a JSONL file (newline-delimited JSON) into the database. If no file is specified, imports from the configured import.path under .beads/ (default: issues.jsonl). Use ”-” to read from stdin. This is the incremental counterpart to ‘bd export’: new issues are created and existing issues are updated (upsert semantics). Memory records (lines with “\_type”:“memory”) are automatically detected and imported as persistent memories (equivalent to ‘bd remember’). This makes ‘bd export | bd import’ a full round-trip for both issues and memories. Each JSONL line should map to an issue. The importer accepts every field ‘bd export’ emits — see ‘bd export’ output for the canonical schema. Only “title” is required; everything else is optional. Common fields: title Required. Short summary. description Long-form body. design, notes, Additional content sections. acceptance\_criteria issue\_type bug | feature | task | epic | chore | … priority 0-4 (0 = critical). 0 is preserved (no omitempty). status open | in\_progress | blocked | closed | … (rows with status “tombstone” are skipped) assignee, owner, Ownership metadata. created\_by labels Array of strings. dependencies Array of {issue\_id, depends\_on\_id, type, …}. comments Array of comment objects. external\_ref, Cross-system identifiers (e.g. “gh-9”). source\_system due\_at, defer\_until RFC3339 timestamps for scheduling. metadata Arbitrary JSON object preserved verbatim. Timestamps (created\_at, updated\_at, started\_at, closed\_at) are preserved when present in the JSONL and otherwise filled in by the importer. The legacy “wisp” boolean is accepted as an alias for “ephemeral”. By default a row only rewrites an existing local issue when its updated\_at is strictly newer. Older rows are skipped (reported as stale\_skipped\_ids) and rows with the same updated\_at keep every local column — updated\_at has second granularity, so a timestamp tie can be two distinct same-second updates, and the local row wins the tie (reported as tie\_kept\_local\_ids; the row’s labels/comments/dependencies still merge). The guard is also enforced inside the upsert itself, so a local update that lands while the import is running is preserved rather than overwritten. Existing issues that the import did rewrite are listed with a field-level summary (updated\_issues), so local state changed by an import is visible. To deliberately restore an older snapshot, pass —allow-stale, which imports every row even when it overwrites newer local state. EXAMPLES: bd import # Import from configured import.path bd import backup.jsonl # Import from a specific file bd import -i backup.jsonl # Legacy alias for a specific file bd import - # Read JSONL from stdin cat issues.jsonl | bd import - # Pipe JSONL from another tool bd import —dry-run # Show what would be imported bd import —dedup # Skip issues with duplicate titles bd import —allow-stale old.jsonl # Restore an older snapshot (overwrites newer local rows) bd import —json # Structured output with created and skipped IDs bd import [file|-] [flags] **Flags:** --allow-stale Import rows even when older than the local issue (required to restore an older snapshot) --dedup Skip lines whose title matches an existing open issue --dry-run Show what would be imported without importing -i, --input string Read JSONL from a specific file [bd human](https://beads.gascity.com/cli-reference/human) [bd info](https://beads.gascity.com/cli-reference/info) ⌘I --- # bd kv - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/kv#content-area) Generated from `bd help --doc kv`. Commands for working with the beads key-value store. The key-value store is useful for storing flags, environment variables, or other user-defined data that persists across sessions. Examples: bd kv set mykey myvalue # Set a value bd kv get mykey # Get a value bd kv clear mykey # Delete a key bd kv list # List all key-value pairs bd kv [flags] [​](https://beads.gascity.com/cli-reference/kv#bd-kv-clear) bd kv clear -------------------------------------------------------------------------- Delete a key from the beads key-value store. Examples: bd kv clear feature\_flag bd kv clear api\_endpoint bd kv clear <key> [flags] [​](https://beads.gascity.com/cli-reference/kv#bd-kv-get) bd kv get ---------------------------------------------------------------------- Get a value from the beads key-value store. Examples: bd kv get feature\_flag bd kv get api\_endpoint bd kv get <key> [flags] [​](https://beads.gascity.com/cli-reference/kv#bd-kv-list) bd kv list ------------------------------------------------------------------------ List all key-value pairs in the beads key-value store. Examples: bd kv list bd kv list —json bd kv list [flags] [​](https://beads.gascity.com/cli-reference/kv#bd-kv-set) bd kv set ---------------------------------------------------------------------- Set a key-value pair in the beads key-value store. This is useful for storing flags, environment variables, or other user-defined data that persists across sessions. Examples: bd kv set feature\_flag true bd kv set api\_endpoint [https://api.example.com](https://api.example.com/) bd kv set max\_retries 3 bd kv set <key> <value> [flags] [bd jira](https://beads.gascity.com/cli-reference/jira) [bd label](https://beads.gascity.com/cli-reference/label) ⌘I --- # bd label - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/label#content-area) Generated from `bd help --doc label`. Manage issue labels bd label [flags] [​](https://beads.gascity.com/cli-reference/label#bd-label-add) bd label add ------------------------------------------------------------------------------- Add a label to one or more issues bd label add [issue-id...] [label] [flags] [​](https://beads.gascity.com/cli-reference/label#bd-label-list) bd label list --------------------------------------------------------------------------------- List labels for an issue bd label list [issue-id] [flags] [​](https://beads.gascity.com/cli-reference/label#bd-label-list-all) bd label list-all ----------------------------------------------------------------------------------------- List all unique labels in the database bd label list-all [flags] [​](https://beads.gascity.com/cli-reference/label#bd-label-propagate) bd label propagate ------------------------------------------------------------------------------------------- Push a label from a parent down to all direct children that don’t already have it. Useful for applying branch: labels across an epic’s subtasks. bd label propagate [parent-id] [label] [flags] [​](https://beads.gascity.com/cli-reference/label#bd-label-remove) bd label remove ------------------------------------------------------------------------------------- Remove a label from one or more issues bd label remove [issue-id...] [label] [flags] [bd kv](https://beads.gascity.com/cli-reference/kv) [bd linear](https://beads.gascity.com/cli-reference/linear) ⌘I --- # bd prune - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/prune#content-area) Generated from `bd help --doc prune`. Permanently delete closed non-ephemeral beads and their associated data. Use this to trim closed regular beads (tasks, features, bugs, chores, etc.) that are no longer useful. The common case is a long-lived repo where closed work has piled up and is bloating auto-export or slowing queries. Requires —older-than or —pattern. The flag is a safety gate — without it, a muscle-memory `--force` could wipe every closed bead in the repo. Use `--pattern '*'` if you really do want to sweep everything closed. Deletes: issues, dependencies, labels, events, and comments for matching beads. Skips: pinned beads (protected), open/in-progress beads, and ephemeral beads. To delete closed ephemeral beads (wisps, transient molecules) use `bd purge` instead. For full Dolt storage reclaim after deleting many rows, follow with `bd flatten` so history can be collapsed and old chunks can be garbage-collected. EXAMPLES: bd prune —older-than 30d # Preview closed beads >30d old bd prune —older-than 30d —force # Delete them bd prune —older-than 90d —dry-run # Detailed preview with stats bd prune —pattern "_" —force # Delete all closed regular beads bd prune —pattern “gm-temp-_” —force # Scope to a pattern bd prune [flags] **Flags:** --dry-run Preview what would be pruned with stats -f, --force Actually prune (without this, shows preview) --older-than string Only prune beads closed more than N ago (e.g., 30d, 2w, 60) --pattern string Only prune beads matching ID glob pattern (e.g., 'gm-old-*') [bd promote](https://beads.gascity.com/cli-reference/promote) [bd purge](https://beads.gascity.com/cli-reference/purge) ⌘I --- # bd todo - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/todo#content-area) Generated from `bd help --doc todo`. Manage TODO items as lightweight task issues. TODOs are regular task-type issues with convenient shortcuts: bd todo add “Title” -> bd create “Title” -t task -p 2 bd todo -> bd list —type task —status open bd todo done <id> -> bd close <id> TODOs can be promoted to full issues by changing type or priority: bd update todo-123 —type bug —priority 0 bd todo [flags] [​](https://beads.gascity.com/cli-reference/todo#bd-todo-add) bd todo add ---------------------------------------------------------------------------- Add a new TODO item bd todo add <title> [flags] **Flags:** -d, --description string Description -p, --priority int Priority (0-4, default 2) (default 2) [​](https://beads.gascity.com/cli-reference/todo#bd-todo-done) bd todo done ------------------------------------------------------------------------------ Mark TODO(s) as done bd todo done <id> [<id>...] [flags] **Flags:** --reason string Reason for closing (default: Completed) [​](https://beads.gascity.com/cli-reference/todo#bd-todo-list) bd todo list ------------------------------------------------------------------------------ List TODO items bd todo list [flags] **Flags:** --all Show all TODOs including completed [bd tag](https://beads.gascity.com/cli-reference/tag) [bd types](https://beads.gascity.com/cli-reference/types) ⌘I --- # bd vc - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/vc#content-area) Generated from `bd help --doc vc`. Version control operations for the beads database. These commands provide git-like version control for your issue data, including branching, merging, and viewing history. Note: ‘bd history’, ‘bd diff’, and ‘bd branch’ also work for quick access. This subcommand provides additional operations like merge and commit. bd vc [flags] [​](https://beads.gascity.com/cli-reference/vc#bd-vc-commit) bd vc commit ---------------------------------------------------------------------------- Create a new Dolt commit with all current changes. Examples: bd vc commit -m “Added new feature issues” bd vc commit —message “Fixed priority on several issues” echo “Multi-line message” | bd vc commit —stdin bd vc commit [flags] **Flags:** -m, --message string Commit message --stdin Read commit message from stdin [​](https://beads.gascity.com/cli-reference/vc#bd-vc-merge) bd vc merge -------------------------------------------------------------------------- Merge the specified branch into the current branch. If there are merge conflicts, they will be reported. You can resolve conflicts with —strategy. Examples: bd vc merge feature-xyz # Merge feature-xyz into current branch bd vc merge feature-xyz —strategy ours # Merge, preferring our changes on conflict bd vc merge feature-xyz —strategy theirs # Merge, preferring their changes on conflict bd vc merge <branch> [flags] **Flags:** --strategy string Conflict resolution strategy: 'ours' or 'theirs' [​](https://beads.gascity.com/cli-reference/vc#bd-vc-status) bd vc status ---------------------------------------------------------------------------- Show the current branch, commit hash, and any uncommitted changes. Examples: bd vc status bd vc status [flags] [bd upgrade](https://beads.gascity.com/cli-reference/upgrade) [bd version](https://beads.gascity.com/cli-reference/version) ⌘I --- # bd formula - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/formula#content-area) Generated from `bd help --doc formula`. Manage workflow formulas - the source layer for molecule templates. Formulas are TOML/JSON files that define workflows with composition rules. Define formulas, cook them into protos, then pour or wisp them into work. Search paths (in order): 1. <resolved-beads-dir>/formulas/ (active project) 2. <checkout-root>/.beads/formulas/ (repo-local formulas) 3. ~/.beads/formulas/ (user) 4. $GT\_ROOT/.beads/formulas/ (shared workspace root, if GT\_ROOT set) Commands: list List available formulas from all search paths show Show formula details, steps, and composition rules bd formula [flags] [​](https://beads.gascity.com/cli-reference/formula#bd-formula-convert) bd formula convert --------------------------------------------------------------------------------------------- Convert formula files from JSON to TOML format. TOML format provides better ergonomics: * Multi-line strings without \\n escaping * Human-readable diffs * Comments allowed The convert command reads a .formula.json file and outputs .formula.toml. The original JSON file is preserved (use —delete to remove it). Examples: bd formula convert shiny # Convert shiny.formula.json to .toml bd formula convert ./my.formula.json # Convert specific file bd formula convert —all # Convert all JSON formulas bd formula convert shiny —delete # Convert and remove JSON file bd formula convert shiny —stdout # Print TOML to stdout bd formula convert <formula-name|path> [--all] [flags] **Flags:** --all Convert all JSON formulas --delete Delete JSON file after conversion --stdout Print TOML to stdout instead of file [​](https://beads.gascity.com/cli-reference/formula#bd-formula-list) bd formula list --------------------------------------------------------------------------------------- List all formulas from search paths. Search paths (in order of priority): 1. <resolved-beads-dir>/formulas/ (active project - highest priority) 2. <checkout-root>/.beads/formulas/ (repo-local formulas) 3. ~/.beads/formulas/ (user) 4. $GT\_ROOT/.beads/formulas/ (shared workspace root, if GT\_ROOT set) Formulas in earlier paths shadow those with the same name in later paths. Examples: bd formula list bd formula list —json bd formula list —type workflow bd formula list —type convoy bd formula list [flags] **Flags:** --type string Filter by type (workflow, expansion, aspect, convoy) [​](https://beads.gascity.com/cli-reference/formula#bd-formula-show) bd formula show --------------------------------------------------------------------------------------- Show detailed information about a formula. Displays: * Formula metadata (name, type, description) * Variables with defaults and constraints * Steps with dependencies * Composition rules (extends, aspects, expansions) * Bond points for external composition Examples: bd formula show shiny bd formula show rule-of-five bd formula show security-audit —json bd formula show <formula-name> [flags] [bd forget](https://beads.gascity.com/cli-reference/forget) [bd gate](https://beads.gascity.com/cli-reference/gate) ⌘I --- # CLI Reference - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference#content-area) Generated from `bd help --docs-root`. This reference covers all 108 live top-level `bd` commands. Regenerate it with: ./scripts/generate-cli-docs.sh [​](https://beads.gascity.com/cli-reference#commands) Commands ----------------------------------------------------------------- * [`bd admin`](https://beads.gascity.com/cli-reference/admin) * [`bd ado`](https://beads.gascity.com/cli-reference/ado) * [`bd assign`](https://beads.gascity.com/cli-reference/assign) * [`bd audit`](https://beads.gascity.com/cli-reference/audit) * [`bd backup`](https://beads.gascity.com/cli-reference/backup) * [`bd batch`](https://beads.gascity.com/cli-reference/batch) * [`bd blocked`](https://beads.gascity.com/cli-reference/blocked) * [`bd bootstrap`](https://beads.gascity.com/cli-reference/bootstrap) * [`bd branch`](https://beads.gascity.com/cli-reference/branch) * [`bd children`](https://beads.gascity.com/cli-reference/children) * [`bd close`](https://beads.gascity.com/cli-reference/close) * [`bd comment`](https://beads.gascity.com/cli-reference/comment) * [`bd comments`](https://beads.gascity.com/cli-reference/comments) * [`bd compact`](https://beads.gascity.com/cli-reference/compact) * [`bd completion`](https://beads.gascity.com/cli-reference/completion) * [`bd config`](https://beads.gascity.com/cli-reference/config) * [`bd context`](https://beads.gascity.com/cli-reference/context) * [`bd cook`](https://beads.gascity.com/cli-reference/cook) * [`bd count`](https://beads.gascity.com/cli-reference/count) * [`bd create`](https://beads.gascity.com/cli-reference/create) * [`bd create-form`](https://beads.gascity.com/cli-reference/create-form) * [`bd defer`](https://beads.gascity.com/cli-reference/defer) * [`bd delete`](https://beads.gascity.com/cli-reference/delete) * [`bd dep`](https://beads.gascity.com/cli-reference/dep) * [`bd diff`](https://beads.gascity.com/cli-reference/diff) * [`bd doctor`](https://beads.gascity.com/cli-reference/doctor) * [`bd dolt`](https://beads.gascity.com/cli-reference/dolt) * [`bd duplicate`](https://beads.gascity.com/cli-reference/duplicate) * [`bd duplicates`](https://beads.gascity.com/cli-reference/duplicates) * [`bd edit`](https://beads.gascity.com/cli-reference/edit) * [`bd epic`](https://beads.gascity.com/cli-reference/epic) * [`bd export`](https://beads.gascity.com/cli-reference/export) * [`bd federation`](https://beads.gascity.com/cli-reference/federation) * [`bd find-duplicates`](https://beads.gascity.com/cli-reference/find-duplicates) * [`bd flatten`](https://beads.gascity.com/cli-reference/flatten) * [`bd forget`](https://beads.gascity.com/cli-reference/forget) * [`bd formula`](https://beads.gascity.com/cli-reference/formula) * [`bd gate`](https://beads.gascity.com/cli-reference/gate) * [`bd gc`](https://beads.gascity.com/cli-reference/gc) * [`bd github`](https://beads.gascity.com/cli-reference/github) * [`bd gitlab`](https://beads.gascity.com/cli-reference/gitlab) * [`bd graph`](https://beads.gascity.com/cli-reference/graph) * [`bd history`](https://beads.gascity.com/cli-reference/history) * [`bd hooks`](https://beads.gascity.com/cli-reference/hooks) * [`bd human`](https://beads.gascity.com/cli-reference/human) * [`bd import`](https://beads.gascity.com/cli-reference/import) * [`bd info`](https://beads.gascity.com/cli-reference/info) * [`bd init`](https://beads.gascity.com/cli-reference/init) * [`bd init-safety`](https://beads.gascity.com/cli-reference/init-safety) * [`bd jira`](https://beads.gascity.com/cli-reference/jira) * [`bd kv`](https://beads.gascity.com/cli-reference/kv) * [`bd label`](https://beads.gascity.com/cli-reference/label) * [`bd linear`](https://beads.gascity.com/cli-reference/linear) * [`bd link`](https://beads.gascity.com/cli-reference/link) * [`bd lint`](https://beads.gascity.com/cli-reference/lint) * [`bd list`](https://beads.gascity.com/cli-reference/list) * [`bd mail`](https://beads.gascity.com/cli-reference/mail) * [`bd memories`](https://beads.gascity.com/cli-reference/memories) * [`bd merge-slot`](https://beads.gascity.com/cli-reference/merge-slot) * [`bd metrics`](https://beads.gascity.com/cli-reference/metrics) * [`bd migrate`](https://beads.gascity.com/cli-reference/migrate) * [`bd mol`](https://beads.gascity.com/cli-reference/mol) * [`bd note`](https://beads.gascity.com/cli-reference/note) * [`bd notion`](https://beads.gascity.com/cli-reference/notion) * [`bd onboard`](https://beads.gascity.com/cli-reference/onboard) * [`bd orphans`](https://beads.gascity.com/cli-reference/orphans) * [`bd ping`](https://beads.gascity.com/cli-reference/ping) * [`bd preflight`](https://beads.gascity.com/cli-reference/preflight) * [`bd prime`](https://beads.gascity.com/cli-reference/prime) * [`bd priority`](https://beads.gascity.com/cli-reference/priority) * [`bd promote`](https://beads.gascity.com/cli-reference/promote) * [`bd prune`](https://beads.gascity.com/cli-reference/prune) * [`bd purge`](https://beads.gascity.com/cli-reference/purge) * [`bd q`](https://beads.gascity.com/cli-reference/q) * [`bd query`](https://beads.gascity.com/cli-reference/query) * [`bd quickstart`](https://beads.gascity.com/cli-reference/quickstart) * [`bd ready`](https://beads.gascity.com/cli-reference/ready) * [`bd recall`](https://beads.gascity.com/cli-reference/recall) * [`bd recompute-blocked`](https://beads.gascity.com/cli-reference/recompute-blocked) * [`bd remember`](https://beads.gascity.com/cli-reference/remember) * [`bd rename`](https://beads.gascity.com/cli-reference/rename) * [`bd rename-prefix`](https://beads.gascity.com/cli-reference/rename-prefix) * [`bd reopen`](https://beads.gascity.com/cli-reference/reopen) * [`bd repo`](https://beads.gascity.com/cli-reference/repo) * [`bd restore`](https://beads.gascity.com/cli-reference/restore) * [`bd rules`](https://beads.gascity.com/cli-reference/rules) * [`bd search`](https://beads.gascity.com/cli-reference/search) * [`bd set-state`](https://beads.gascity.com/cli-reference/set-state) * [`bd setup`](https://beads.gascity.com/cli-reference/setup) * [`bd ship`](https://beads.gascity.com/cli-reference/ship) * [`bd show`](https://beads.gascity.com/cli-reference/show) * [`bd sql`](https://beads.gascity.com/cli-reference/sql) * [`bd stale`](https://beads.gascity.com/cli-reference/stale) * [`bd state`](https://beads.gascity.com/cli-reference/state) * [`bd status`](https://beads.gascity.com/cli-reference/status) * [`bd statuses`](https://beads.gascity.com/cli-reference/statuses) * [`bd supersede`](https://beads.gascity.com/cli-reference/supersede) * [`bd swarm`](https://beads.gascity.com/cli-reference/swarm) * [`bd tag`](https://beads.gascity.com/cli-reference/tag) * [`bd todo`](https://beads.gascity.com/cli-reference/todo) * [`bd types`](https://beads.gascity.com/cli-reference/types) * [`bd undefer`](https://beads.gascity.com/cli-reference/undefer) * [`bd update`](https://beads.gascity.com/cli-reference/update) * [`bd upgrade`](https://beads.gascity.com/cli-reference/upgrade) * [`bd vc`](https://beads.gascity.com/cli-reference/vc) * [`bd version`](https://beads.gascity.com/cli-reference/version) * [`bd where`](https://beads.gascity.com/cli-reference/where) * [`bd worktree`](https://beads.gascity.com/cli-reference/worktree) [FAQ](https://beads.gascity.com/reference/faq) [bd admin](https://beads.gascity.com/cli-reference/admin) ⌘I --- # bd list - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/list#content-area) Generated from `bd help --doc list`. List issues bd list [flags] **Flags:** --all Show all issues including closed (overrides default filter) -a, --assignee string Filter by assignee --closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339) --closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339) --created-after string Filter issues created after date (YYYY-MM-DD or RFC3339) --created-before string Filter issues created before date (YYYY-MM-DD or RFC3339) --defer-after string Filter issues deferred after date (supports relative: +6h, tomorrow) --defer-before string Filter issues deferred before date (supports relative: +6h, tomorrow) --deferred Show only issues with defer_until set --desc-contains string Filter by description substring (case-insensitive) --due-after string Filter issues due after date (supports relative: +6h, tomorrow) --due-before string Filter issues due before date (supports relative: +6h, tomorrow) --empty-description Filter issues with empty or missing description --exclude-label strings Exclude issues that have ANY of these labels --exclude-type strings Exclude issue types from results (comma-separated or repeatable, e.g., --exclude-type=convoy,epic) --flat Disable tree format and use legacy flat list output --format string Output format: 'digraph' (for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or Go template --has-metadata-key string Filter issues that have this metadata key set --id string Filter by specific issue IDs (comma-separated, e.g., bd-1,bd-5,bd-10) --include-gates Include gate issues in output (normally hidden) --include-infra Include infrastructure beads (agent/role/message) in output --include-templates Include template molecules in output -l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any --label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label --label-pattern string Filter by label glob pattern (e.g., 'tech-*' matches tech-debt, tech-legacy) --label-regex string Filter by label regex pattern (e.g., 'tech-(debt|legacy)') -n, --limit int Limit results (default 50, use 0 for unlimited) (default 50) --long Show detailed multi-line output for each issue --metadata-field stringArray Filter by metadata field (key=value, repeatable) --mol-type string Filter by molecule type: swarm, patrol, or work --no-assignee Filter issues with no assignee --no-labels Filter issues with no labels --no-pager Disable pager output --no-parent Exclude child issues (show only top-level issues) --no-pinned Exclude pinned issues --notes-contains string Filter by notes substring (case-insensitive) --offset int Skip the first N matching results (0-based). Only supported under --proxied-server. --overdue Show only issues with due_at in the past (not closed) --parent string Filter by parent issue ID (shows children of specified issue) --pinned Show only pinned issues --pretty Display issues in a tree format with status/priority symbols -p, --priority string Priority (0-4 or P0-P4, 0=highest) --priority-max string Filter by maximum priority (inclusive, 0-4 or P0-P4) --priority-min string Filter by minimum priority (inclusive, 0-4 or P0-P4) --ready Show only ready issues (no active blockers, same semantics as bd ready) -r, --reverse Reverse sort order --skip-labels Skip label hydration. The labels field in output will be empty regardless of actual labels. Use only when the caller does not depend on label data. Cannot combine with --label, --label-any, --label-pattern, --label-regex, --exclude-label, or --no-labels. --sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee --spec string Filter by spec_id prefix -s, --status string Filter by stored status (open, in_progress, blocked, deferred, closed). Comma-separated for multiple: --status open,in_progress. Note: repeating -s/--status silently overwrites the previous value — always use the comma-separated form for multi-status filters. --title string Filter by title text (case-insensitive substring match) --title-contains string Filter by title substring (case-insensitive) --tree Hierarchical tree format (default: true; use --flat to disable) (default true) -t, --type string Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision --updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339) --updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339) -w, --watch Watch for changes and auto-update display (implies --pretty) --wisp-type string Filter by wisp type: heartbeat, ping, patrol, gc_report, recovery, error, escalation [bd lint](https://beads.gascity.com/cli-reference/lint) [bd mail](https://beads.gascity.com/cli-reference/mail) ⌘I --- # bd hooks - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/hooks#content-area) Generated from `bd help --doc hooks`. Install, uninstall, or list git hooks for beads integration. The hooks provide: * pre-commit: Run chained hooks before commit * post-merge: Run chained hooks after pull/merge * pre-push: Run chained hooks before push * post-checkout: Run chained hooks after branch checkout * prepare-commit-msg: Add agent identity trailers for forensics bd hooks [flags] [​](https://beads.gascity.com/cli-reference/hooks#bd-hooks-install) bd hooks install --------------------------------------------------------------------------------------- Install git hooks for beads integration. By default, hooks are installed to .git/hooks/ in the current repository. Use —beads to install to .beads/hooks/ (recommended for Dolt backend). Use —shared to install to a versioned directory (.beads-hooks/) that can be committed to git and shared with team members. Hooks use section markers to coexist with existing hooks — any user content outside the markers is preserved across installs and upgrades. Installed hooks: * pre-commit: Run chained hooks before commit * post-merge: Run chained hooks after pull/merge * pre-push: Run chained hooks before push * post-checkout: Run chained hooks after branch checkout * prepare-commit-msg: Add agent identity trailers (for orchestrator agents) bd hooks install [flags] **Flags:** --beads Install hooks to .beads/hooks/ (recommended for Dolt backend) --chain Chain with existing hooks (run them before bd hooks) --force Overwrite existing hooks without backup --shared Install hooks to .beads-hooks/ (versioned) instead of .git/hooks/ [​](https://beads.gascity.com/cli-reference/hooks#bd-hooks-list) bd hooks list --------------------------------------------------------------------------------- Show the status of bd git hooks (installed, outdated, missing). bd hooks list [flags] [​](https://beads.gascity.com/cli-reference/hooks#bd-hooks-run) bd hooks run ------------------------------------------------------------------------------- Execute the logic for a git hook. This command is typically called by thin shim scripts installed in .git/hooks/. Supported hooks: * pre-commit: Run chained hooks before commit * post-merge: Run chained hooks after pull/merge * pre-push: Run chained hooks before push * post-checkout: Run chained hooks after branch checkout * prepare-commit-msg: Add agent identity trailers for forensics The thin shim pattern ensures hook logic is always in sync with the installed bd version - upgrading bd automatically updates hook behavior. bd hooks run <hook-name> [args...] [flags] [​](https://beads.gascity.com/cli-reference/hooks#bd-hooks-uninstall) bd hooks uninstall ------------------------------------------------------------------------------------------- Remove bd git hooks from .git/hooks/ directory. bd hooks uninstall [flags] [bd history](https://beads.gascity.com/cli-reference/history) [bd human](https://beads.gascity.com/cli-reference/human) ⌘I --- # bd doctor - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/doctor#content-area) Generated from `bd help --doc doctor`. Sanity check the beads installation for the current directory or specified path. This command checks: * If .beads/ directory exists * Database version and migration status * Schema compatibility (all required tables and columns present) * Whether using hash-based vs sequential IDs * If CLI version is current (checks GitHub releases) * If Claude plugin is current (when running in Claude Code) * File permissions * Circular dependencies * Git hooks (pre-commit, post-merge, pre-push) * .beads/.gitignore up to date * Metadata.json version tracking (LastBdVersion field) Performance Mode (—perf): Run performance diagnostics on your database: * Times key operations (bd ready, bd list, bd show, etc.) * Collects system info (OS, arch, SQLite version, database stats) * Generates CPU profile for analysis * Outputs shareable report for bug reports Export Mode (—output): Save diagnostics to a JSON file for historical analysis and bug reporting. Includes timestamp and platform info for tracking intermittent issues. Specific Check Mode (—check): Run a specific check in detail. Available checks: * artifacts: Detect and optionally clean beads classic artifacts (stale JSONL, SQLite files, cruft .beads dirs). Use with —clean. * conventions: Check for convention drift (lint warnings, stale issues, orphaned issues). Advisory only - warns, never blocks. * pollution: Detect and optionally clean test issues from database * validate: Run focused data-integrity checks (duplicates, orphaned deps, test pollution, git conflicts). Use with —fix to auto-repair. Deep Validation Mode (—deep): Validate full graph integrity. May be slow on large databases. Additional checks: * Parent consistency: All parent-child deps point to existing issues * Dependency integrity: All deps reference valid issues * Epic completeness: Find epics ready to close (all children closed) * Agent bead integrity: Agent beads have valid state values * Mail thread integrity: Thread IDs reference existing issues * Molecule integrity: Molecules have valid parent-child structures Server Mode (—server): Run health checks for Dolt server mode connections (bd-dolt.2.3): * Server reachable: Can connect to configured host:port? * Dolt version: Is it a Dolt server (not vanilla MySQL)? * Database exists: Does the ‘beads’ database exist? * Schema compatible: Can query beads tables? * Connection pool: Pool health metrics Migration Validation Mode (—migration): Run Dolt migration validation checks with machine-parseable output. Use —migration=pre before migration to verify readiness: * JSONL file exists and is valid (parseable, no corruption) * All JSONL issues are present in SQLite (or explains discrepancies) * No blocking issues prevent migration Use —migration=post after migration to verify completion: * Dolt database exists and is healthy * All issues from JSONL are present in Dolt * No data was lost during migration * Dolt database has no locks or uncommitted changes Combine with —json for machine-parseable output for automation. Agent Mode (—agent): Output diagnostics designed for AI agent consumption. Instead of terse pass/fail messages, each issue includes: * Observed state: what the system actually looks like * Expected state: what it should look like * Explanation: full prose context about the issue and why it matters * Commands: exact remediation commands to run * Source files: where in the codebase to investigate further * Severity: blocking (prevents operation), degraded (partial function), or advisory (informational only) ZFC-compliant: Go observes and reports, the agent decides and acts. Combine with —json for structured agent-facing output. Suppressing Warnings: Suppress specific warnings by setting doctor.suppress.<check-slug> config: bd config set doctor.suppress.pending-migrations true bd config set doctor.suppress.git-hooks true Check names are converted to slugs: “Git Hooks” → “git-hooks”. Only warnings are suppressed; errors and passing checks always show. To unsuppress: bd config unset doctor.suppress.<slug> Examples: bd doctor # Check current directory bd doctor /path/to/repo # Check specific repository bd doctor —json # Machine-readable output bd doctor —agent # Agent-facing diagnostic output bd doctor —agent —json # Structured agent diagnostics (JSON) bd doctor —fix # Automatically fix issues (with confirmation) bd doctor —fix —yes # Automatically fix issues (no confirmation) bd doctor —fix -i # Confirm each fix individually bd doctor —fix —fix-child-parent # Also fix child→parent deps (opt-in) bd doctor —fix —force # Force repair even when database can’t be opened bd doctor —fix —source=jsonl # Rebuild database from a JSONL export bd doctor —dry-run # Preview what —fix would do without making changes bd doctor —perf # Performance diagnostics bd doctor —output diagnostics.json # Export diagnostics to file bd doctor —check=artifacts # Show classic artifacts (JSONL, SQLite, cruft dirs) bd doctor —check=artifacts —clean # Delete safe-to-delete artifacts (with confirmation) bd doctor —check=conventions # Convention drift check (lint, stale, orphans) bd doctor —check=pollution # Show potential test issues bd doctor —check=pollution —clean # Delete test issues (with confirmation) bd doctor —check=validate # Data-integrity checks only bd doctor —check=validate —fix # Auto-fix data-integrity issues bd doctor —deep # Full graph integrity validation bd doctor —server # Dolt server mode health checks bd doctor —migration=pre # Validate readiness for Dolt migration bd doctor —migration=post # Validate Dolt migration completed bd doctor —migration=pre —json # Machine-parseable migration validation bd doctor [path] [flags] **Flags:** --agent Agent-facing diagnostic mode: rich context for AI agents (ZFC-compliant) --check string Run specific check in detail (e.g., 'pollution') --check-health Quick health check for git hooks (silent on success) --clean For pollution check: delete detected test issues --deep Validate full graph integrity --dry-run Preview fixes without making changes --fix Automatically fix issues where possible --fix-child-parent Remove child→parent dependencies (opt-in) -i, --interactive Confirm each fix individually --migration string Run Dolt migration validation: 'pre' (before migration) or 'post' (after migration) --orchestrator Running in orchestrator multi-workspace mode (routes.jsonl is expected, higher duplicate tolerance) --orchestrator-duplicates-threshold int Duplicate tolerance threshold for orchestrator mode (wisps are ephemeral) (default 1000) -o, --output string Export diagnostics to JSON file --perf Run performance diagnostics and generate CPU profile --server Run Dolt server mode health checks (connectivity, version, schema) -v, --verbose Show all checks (default shows only warnings/errors) -y, --yes Skip confirmation prompt (for non-interactive use) [bd diff](https://beads.gascity.com/cli-reference/diff) [bd dolt](https://beads.gascity.com/cli-reference/dolt) ⌘I --- # bd github - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/github#content-area) Generated from `bd help --doc github`. Commands for syncing issues between beads and GitHub. Configuration can be set via ‘bd config’ or environment variables: github.token / GITHUB\_TOKEN - Personal access token github.owner / GITHUB\_OWNER - Repository owner github.repo / GITHUB\_REPO - Repository name github.repository / GITHUB\_REPOSITORY - Combined “owner/repo” format github.url / GITHUB\_API\_URL - Custom API URL (GitHub Enterprise) bd github [flags] [​](https://beads.gascity.com/cli-reference/github#bd-github-pull) bd github pull ------------------------------------------------------------------------------------ Pull one or more items from GitHub. Accepts bead IDs or external references as positional arguments. Equivalent to: bd github sync —pull-only —issues <refs> bd github pull [refs...] [flags] **Flags:** --dry-run Preview pull without making changes [​](https://beads.gascity.com/cli-reference/github#bd-github-push) bd github push ------------------------------------------------------------------------------------ Push one or more beads issues to GitHub. Accepts bead IDs as positional arguments. Equivalent to: bd github sync —push-only —issues <ids> bd github push [bead-ids...] [flags] **Flags:** --dry-run Preview push without making changes [​](https://beads.gascity.com/cli-reference/github#bd-github-repos) bd github repos -------------------------------------------------------------------------------------- List GitHub repositories that the configured token has access to. bd github repos [flags] [​](https://beads.gascity.com/cli-reference/github#bd-github-status) bd github status ---------------------------------------------------------------------------------------- Display current GitHub configuration and sync status. bd github status [flags] [​](https://beads.gascity.com/cli-reference/github#bd-github-sync) bd github sync ------------------------------------------------------------------------------------ Synchronize issues between beads and GitHub. By default, performs bidirectional sync: * Pulls new/updated issues from GitHub to beads * Pushes local beads issues to GitHub Use —pull-only or —push-only to limit direction. bd github sync [flags] **Flags:** --dry-run Show what would be synced without making changes --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues. --prefer-github On conflict, use GitHub version --prefer-local On conflict, keep local beads version --prefer-newer On conflict, use most recent version (default) --pull-only Only pull issues from GitHub --push-only Only push issues to GitHub [bd gc](https://beads.gascity.com/cli-reference/gc) [bd gitlab](https://beads.gascity.com/cli-reference/gitlab) ⌘I --- # bd gitlab - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/gitlab#content-area) Generated from `bd help --doc gitlab`. Commands for syncing issues between beads and GitLab. Configuration can be set via ‘bd config’ or environment variables: gitlab.url / GITLAB\_URL - GitLab instance URL gitlab.token / GITLAB\_TOKEN - Personal access token gitlab.project\_id / GITLAB\_PROJECT\_ID - Project ID or path gitlab.group\_id / GITLAB\_GROUP\_ID - Group ID for group-level sync gitlab.default\_project\_id / GITLAB\_DEFAULT\_PROJECT\_ID - Project for creating issues in group mode bd gitlab [flags] [​](https://beads.gascity.com/cli-reference/gitlab#bd-gitlab-projects) bd gitlab projects -------------------------------------------------------------------------------------------- List GitLab projects that the configured token has access to. bd gitlab projects [flags] [​](https://beads.gascity.com/cli-reference/gitlab#bd-gitlab-pull) bd gitlab pull ------------------------------------------------------------------------------------ Pull one or more items from GitLab. Accepts bead IDs or external references as positional arguments. Equivalent to: bd gitlab sync —pull-only —issues <refs> bd gitlab pull [refs...] [flags] **Flags:** --dry-run Preview pull without making changes [​](https://beads.gascity.com/cli-reference/gitlab#bd-gitlab-push) bd gitlab push ------------------------------------------------------------------------------------ Push one or more beads issues to GitLab. Accepts bead IDs as positional arguments. Equivalent to: bd gitlab sync —push-only —issues <ids> bd gitlab push [bead-ids...] [flags] **Flags:** --dry-run Preview push without making changes [​](https://beads.gascity.com/cli-reference/gitlab#bd-gitlab-status) bd gitlab status ---------------------------------------------------------------------------------------- Display current GitLab configuration and sync status. bd gitlab status [flags] [​](https://beads.gascity.com/cli-reference/gitlab#bd-gitlab-sync) bd gitlab sync ------------------------------------------------------------------------------------ Synchronize issues between beads and GitLab. By default, performs bidirectional sync: * Pulls new/updated issues from GitLab to beads * Pushes local beads issues to GitLab Use —pull-only or —push-only to limit direction. bd gitlab sync [flags] **Flags:** --assignee string Filter by assignee username --dry-run Show what would be synced without making changes --exclude-type string Exclude these issue types from sync (comma-separated) --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --label string Filter by labels (comma-separated, AND logic) --milestone string Filter by milestone title --no-ephemeral Exclude ephemeral/wisp issues from push (default: true) (default true) --parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues. --prefer-gitlab On conflict, use GitLab version --prefer-local On conflict, keep local beads version --prefer-newer On conflict, use most recent version (default) --project string Filter to issues from this project ID (group mode) --pull-only Only pull issues from GitLab --push-only Only push issues to GitLab --type string Only sync these issue types (comma-separated, e.g. 'epic,feature,task') [bd github](https://beads.gascity.com/cli-reference/github) [bd graph](https://beads.gascity.com/cli-reference/graph) ⌘I --- # bd human - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/human#content-area) Generated from `bd help --doc human`. Display a focused help menu showing only the most common commands. bd has 70+ commands - many for AI agents, integrations, and advanced workflows. This command shows the ~15 essential commands that human users need most often. For the full command list, run: bd —help SUBCOMMANDS: human list List all human-needed beads (issues with ‘human’ label) human respond <id> Respond to a human-needed bead (adds comment and closes) human dismiss <id> Dismiss a human-needed bead permanently human stats Show summary statistics for human-needed beads bd human [flags] [​](https://beads.gascity.com/cli-reference/human#bd-human-dismiss) bd human dismiss --------------------------------------------------------------------------------------- Dismiss a human-needed bead permanently without responding. The issue is closed with a “Dismissed” reason and optional note. Examples: bd human dismiss bd-123 bd human dismiss bd-123 —reason “No longer applicable” bd human dismiss <issue-id> [flags] **Flags:** --reason string Reason for dismissal (optional) [​](https://beads.gascity.com/cli-reference/human#bd-human-list) bd human list --------------------------------------------------------------------------------- List all issues labeled with ‘human’ tag. These are issues that require human intervention or input. Examples: bd human list bd human list —status=open bd human list —json bd human list [flags] **Flags:** -s, --status string Filter by status (open, closed, etc.) [​](https://beads.gascity.com/cli-reference/human#bd-human-respond) bd human respond --------------------------------------------------------------------------------------- Respond to a human-needed bead by adding a comment and closing it. The response is added as a comment and the issue is closed with reason “Responded”. Examples: bd human respond bd-123 —response “Use OAuth2 for authentication” bd human respond bd-123 -r “Approved, proceed with implementation” bd human respond <issue-id> [flags] **Flags:** -r, --response string Response text (required) [​](https://beads.gascity.com/cli-reference/human#bd-human-stats) bd human stats ----------------------------------------------------------------------------------- Display summary statistics for human-needed beads. Shows counts for total, pending (open), responded (closed without dismiss), and dismissed beads. Example: bd human stats bd human stats [flags] [bd hooks](https://beads.gascity.com/cli-reference/hooks) [bd import](https://beads.gascity.com/cli-reference/import) ⌘I --- # bd merge-slot - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/merge-slot#content-area) Generated from `bd help --doc merge-slot`. Merge-slot gates serialize conflict resolution in the merge queue. A merge slot is an exclusive access primitive: only one agent can hold it at a time. This prevents “monkey knife fights” where multiple polecats race to resolve conflicts and create cascading conflicts. Each rig has one merge slot bead: <prefix>-merge-slot (labeled gt:slot). The slot uses: * status=open: slot is available * status=in\_progress: slot is held * metadata.holder: who currently holds the slot * metadata.waiters: priority-ordered queue of waiters Examples: bd merge-slot create # Create merge slot for current rig bd merge-slot check # Check if slot is available bd merge-slot acquire # Try to acquire the slot bd merge-slot release # Release the slot bd merge-slot [flags] [​](https://beads.gascity.com/cli-reference/merge-slot#bd-merge-slot-acquire) bd merge-slot acquire ------------------------------------------------------------------------------------------------------ Attempt to acquire the merge slot for exclusive access. If the slot is available (status=open), it will be acquired: * status set to in\_progress * holder set to the requester If the slot is held (status=in\_progress), the command fails unless —wait is passed, which adds the requester to the waiters queue. Use —holder to specify who is acquiring (default: BEADS\_ACTOR env var). bd merge-slot acquire [flags] **Flags:** --holder string Who is acquiring the slot (default: BEADS_ACTOR) --wait Add to waiters list if slot is held [​](https://beads.gascity.com/cli-reference/merge-slot#bd-merge-slot-check) bd merge-slot check -------------------------------------------------------------------------------------------------- Check if the merge slot is available or held. Returns: * available: slot can be acquired * held by <holder>: slot is currently held * not found: no merge slot exists for this rig bd merge-slot check [flags] [​](https://beads.gascity.com/cli-reference/merge-slot#bd-merge-slot-create) bd merge-slot create ---------------------------------------------------------------------------------------------------- Create a merge slot bead for serialized conflict resolution. The slot ID is automatically generated based on the beads prefix (e.g., gt-merge-slot). The slot is created with status=open (available). bd merge-slot create [flags] [​](https://beads.gascity.com/cli-reference/merge-slot#bd-merge-slot-release) bd merge-slot release ------------------------------------------------------------------------------------------------------ Release the merge slot after conflict resolution is complete. Sets status back to open and clears the holder field. If there are waiters, the highest-priority waiter should then acquire. bd merge-slot release [flags] **Flags:** --holder string Who is releasing the slot (for verification) [bd memories](https://beads.gascity.com/cli-reference/memories) [bd metrics](https://beads.gascity.com/cli-reference/metrics) ⌘I --- # bd upgrade - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/upgrade#content-area) Generated from `bd help --doc upgrade`. Commands for checking bd version upgrades and reviewing changes. The upgrade command helps you stay aware of bd version changes: * bd upgrade status: Check if bd version changed since last use * bd upgrade review: Show what’s new since your last version * bd upgrade ack: Acknowledge the current version Version tracking is automatic - bd updates metadata.json on every run. bd upgrade [flags] [​](https://beads.gascity.com/cli-reference/upgrade#bd-upgrade-ack) bd upgrade ack ------------------------------------------------------------------------------------- Mark the current bd version as acknowledged. This updates metadata.json to record that you’ve seen the current version. Mainly useful after reviewing upgrade changes to suppress future upgrade notifications. Note: Version tracking happens automatically, so you don’t need to run this command unless you want to explicitly mark acknowledgement. Examples: bd upgrade ack bd upgrade ack —json bd upgrade ack [flags] [​](https://beads.gascity.com/cli-reference/upgrade#bd-upgrade-review) bd upgrade review ------------------------------------------------------------------------------------------- Show what’s new in bd since the last version you used. Unlike ‘bd info —whats-new’ which shows the last 3 versions, this command shows ALL changes since your specific last version. If you’re upgrading from an old version, you’ll see the complete changelog of everything that changed since then. Examples: bd upgrade review bd upgrade review —json bd upgrade review [flags] [​](https://beads.gascity.com/cli-reference/upgrade#bd-upgrade-status) bd upgrade status ------------------------------------------------------------------------------------------- Check if bd has been upgraded since you last used it. This command uses the version tracking that happens automatically at startup to detect if bd was upgraded. Examples: bd upgrade status bd upgrade status —json bd upgrade status [flags] [bd update](https://beads.gascity.com/cli-reference/update) [bd vc](https://beads.gascity.com/cli-reference/vc) ⌘I --- # bd jira - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/jira#content-area) Generated from `bd help --doc jira`. Synchronize issues between beads and Jira. Configuration: bd config set jira.url “[https://company.atlassian.net](https://company.atlassian.net/) ” bd config set jira.project “PROJ” bd config set jira.projects “PROJ1,PROJ2” # Multiple projects bd config set jira.api\_token “YOUR\_TOKEN” bd config set jira.username “[your\_email@company.com](mailto:your_email@company.com) ” # For Jira Cloud bd config set jira.push\_prefix “hippo” # Only push hippo-\* issues to Jira bd config set jira.push\_prefix “proj1,proj2” # Multiple prefixes (comma-separated) Environment variables (alternative to config): JIRA\_API\_TOKEN - Jira API token JIRA\_USERNAME - Jira username/email JIRA\_PROJECTS - Comma-separated project keys Examples: bd jira sync —pull # Import issues from Jira bd jira sync —push # Export issues to Jira bd jira sync # Bidirectional sync (pull then push) bd jira sync —dry-run # Preview sync without changes bd jira status # Show sync status bd jira [flags] [​](https://beads.gascity.com/cli-reference/jira#bd-jira-pull) bd jira pull ------------------------------------------------------------------------------ Pull one or more items from Jira. Accepts bead IDs or external references as positional arguments. Equivalent to: bd jira sync —pull —issues <refs> bd jira pull [refs...] [flags] **Flags:** --dry-run Preview pull without making changes [​](https://beads.gascity.com/cli-reference/jira#bd-jira-push) bd jira push ------------------------------------------------------------------------------ Push one or more beads issues to Jira. Accepts bead IDs as positional arguments. Equivalent to: bd jira sync —push —issues <ids> bd jira push [bead-ids...] [flags] **Flags:** --dry-run Preview push without making changes [​](https://beads.gascity.com/cli-reference/jira#bd-jira-status) bd jira status ---------------------------------------------------------------------------------- Show the current Jira sync status, including: * Last sync timestamp * Configuration status * Number of issues with Jira links * Issues pending push (no external\_ref) bd jira status [flags] [​](https://beads.gascity.com/cli-reference/jira#bd-jira-sync) bd jira sync ------------------------------------------------------------------------------ Synchronize issues between beads and Jira. Modes: —pull Import issues from Jira into beads —push Export issues from beads to Jira (no flags) Bidirectional sync: pull then push, with conflict resolution Conflict Resolution: By default, newer timestamp wins. Override with: —prefer-local Always prefer local beads version —prefer-jira Always prefer Jira version Examples: bd jira sync —pull # Import from Jira bd jira sync —push —create-only # Push new issues only bd jira sync —dry-run # Preview without changes bd jira sync —prefer-local # Bidirectional, local wins bd jira sync [flags] **Flags:** --create-only Only create new issues, don't update existing --dry-run Preview sync without making changes --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues. --prefer-jira Prefer Jira version on conflicts --prefer-local Prefer local version on conflicts --project strings Project key(s) to sync (overrides configured project/projects) --pull Pull issues from Jira --push Push issues to Jira --state string Issue state to sync: open, closed, all (default "all") [bd init](https://beads.gascity.com/cli-reference/init) [bd kv](https://beads.gascity.com/cli-reference/kv) ⌘I --- # bd init - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/init#content-area) Generated from `bd help --doc init`. Initialize bd in the current directory by creating a .beads/ directory and Dolt database. Optionally specify a custom issue prefix. Dolt is the default (and only supported) storage backend. The legacy SQLite backend has been removed. Use —backend=sqlite to see migration instructions. Use —database to specify an existing server database name, overriding the default prefix-based naming. This is useful when an external tool (e.g. an orchestrator) has already created the database. With —stealth: configures per-repository git settings for invisible beads usage: • .git/info/exclude to prevent beads files from being committed Perfect for personal use without affecting repo collaborators. To set up a specific AI tool, run: bd setup <claude|cursor|aider|…> —stealth By default, beads uses an embedded Dolt engine (no external server needed). Pass —server to use an external dolt sql-server instead. In server mode, set connection details with —server-host, —server-port, and —server-user. Password should be set via BEADS\_DOLT\_PASSWORD environment variable. Auto-export is optional. When enabled, bd exports issues to .beads/issues.jsonl after write commands (throttled to once per 60s). This is for viewers (bv), interchange, and issue-level migration; not backup. Cross-machine sync and backups use Dolt remotes/backups, not JSONL import/export. To enable: bd config set export.auto true Non-interactive mode (—non-interactive or BD\_NON\_INTERACTIVE=1): Skips all interactive prompts, using sensible defaults: • Role defaults to “maintainer” (override with —role) • Fork exclude auto-configured when fork detected • Auto-export left at default (disabled) • —contributor and —team flags are rejected (wizards require interaction) Also auto-detected when stdin is not a terminal or CI=true is set. bd init [flags] **Flags:** --agents-file string Custom filename for agent instructions (default: AGENTS.md) --agents-profile string AGENTS.md profile: 'minimal' (default, pointer to bd prime) or 'full' (complete command reference) --agents-template string Path to custom AGENTS.md template (overrides embedded default) --backend string Storage backend (default: dolt). --backend=sqlite prints deprecation notice. --contributor Run OSS contributor setup wizard --database string Use existing server database name (overrides prefix-based naming) --debug Run the managed Dolt sql-server with --loglevel=debug and CPU profiling (--prof cpu). Persisted to config.yaml as dolt.debug. No effect on externally-managed servers. --destroy-token string Explicit confirmation token for destructive re-init in non-interactive mode (format: 'DESTROY-<prefix>') --discard-remote Authorize discarding the configured remote's Dolt history when re-initializing. Requires --destroy-token in non-interactive mode; see 'bd help init-safety'. --external Server is externally managed (skip server startup); use with --shared-server or --server --force Deprecated alias for --reinit-local. Bypasses only the LOCAL data-safety guard; does NOT authorize remote divergence (see 'bd help init-safety'). --from-jsonl Import issues from configured import.path; refuses remote history unless --discard-remote authorizes replacement --init-if-missing If the workspace is already initialized, skip init and exit 0 instead of failing (idempotent init for scaffolds) --non-interactive Skip all interactive prompts (auto-detected in CI or non-TTY environments) -p, --prefix string Issue prefix (default: current directory name) --proxied-server [EXPERIMENTAL] Use a per-workspace proxied dolt sql-server (proxy + child dolt) rooted at .beads/proxieddb --proxied-server-config-path string [EXPERIMENTAL] Absolute path to an existing dolt sql-server YAML config (proxied-server mode only). When set, bd uses this file instead of auto-generating one. Relative paths are rejected. --proxied-server-external-host string [EXPERIMENTAL] Hostname or IP of an externally-managed dolt sql-server the proxy should front (proxied-server mode only). Mutually exclusive with --proxied-server-external-socket-path. --proxied-server-external-keep-alive duration [EXPERIMENTAL] TCP keepalive period for the proxy→external connection. Zero uses the package default (30s). --proxied-server-external-port int [EXPERIMENTAL] TCP port of the externally-managed dolt sql-server (proxied-server mode only). Required when --proxied-server-external-host is set. --proxied-server-external-socket-path string [EXPERIMENTAL] Absolute unix socket path of the externally-managed dolt sql-server (proxied-server mode only). Mutually exclusive with --proxied-server-external-host. Relative paths are rejected. --proxied-server-external-tls [EXPERIMENTAL] Require TLS when connecting to the externally-managed dolt sql-server (proxied-server mode only). --proxied-server-external-tls-cert-path string [EXPERIMENTAL] Absolute path to a client TLS certificate (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-key-path. Relative paths are rejected. --proxied-server-external-tls-key-path string [EXPERIMENTAL] Absolute path to the client TLS private key (for mTLS to the externally-managed dolt sql-server). Must be paired with --proxied-server-external-tls-cert-path. Relative paths are rejected. --proxied-server-external-user string [EXPERIMENTAL] MySQL user for the externally-managed dolt sql-server (proxied-server mode only). Defaults to "root" when empty. Password is read at runtime from $BEADS_PROXIED_SERVER_EXTERNAL_PASSWORD and is never persisted to disk. --proxied-server-log-path string [EXPERIMENTAL] Absolute path to the proxied dolt sql-server log file (proxied-server mode only). Default: <beadsDir>/proxieddb/server.log. Relative paths are rejected. --proxied-server-root-path string [EXPERIMENTAL] Absolute directory holding the proxied dolt sql-server's lockfiles, pidfiles, and child .dolt repository (proxied-server mode only). Default: <beadsDir>/proxieddb. May not exist yet — bd will create it. Relative paths are rejected. -q, --quiet Suppress output (quiet mode) --reinit-local Re-initialize local .beads/ over existing local data. Does NOT authorize remote divergence; see --discard-remote. --remote string Dolt remote URL to clone from and persist as sync.remote --role string Set beads role without prompting: "maintainer" or "contributor" --server Use external dolt sql-server instead of embedded engine --server-host string Dolt server host (default: 127.0.0.1) --server-port int Dolt server port (default: 3307) --server-socket string Unix domain socket path (overrides host/port) --server-user string Dolt server MySQL user (default: root) --setup-exclude Configure .git/info/exclude to keep beads files local (for forks) --shared-server Enable shared Dolt server mode (all projects share one server at ~/.beads/shared-server/) --skip-agents Skip AGENTS.md and Claude/Codex setup generation --skip-hooks Skip git hooks installation --stealth Enable stealth mode: global gitattributes and gitignore, no local repo tracking --team Run team workflow setup wizard [bd init-safety](https://beads.gascity.com/cli-reference/init-safety) [bd jira](https://beads.gascity.com/cli-reference/jira) ⌘I --- # bd notion - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/notion#content-area) Generated from `bd help --doc notion`. Commands for syncing issues between beads and Notion. bd notion [flags] [​](https://beads.gascity.com/cli-reference/notion#bd-notion-connect) bd notion connect ------------------------------------------------------------------------------------------ Connect bd to an existing Notion database or data source bd notion connect [flags] **Flags:** --url string Existing Notion database or data source URL [​](https://beads.gascity.com/cli-reference/notion#bd-notion-init) bd notion init ------------------------------------------------------------------------------------ Create a dedicated Beads database in Notion bd notion init [flags] **Flags:** --parent string Parent page ID --title string Database title (default "Beads Issues") [​](https://beads.gascity.com/cli-reference/notion#bd-notion-pull) bd notion pull ------------------------------------------------------------------------------------ Pull one or more items from Notion. Accepts bead IDs or external references as positional arguments. Equivalent to: bd notion sync —pull —issues <refs> bd notion pull [refs...] [flags] **Flags:** --dry-run Preview pull without making changes [​](https://beads.gascity.com/cli-reference/notion#bd-notion-push) bd notion push ------------------------------------------------------------------------------------ Push one or more beads issues to Notion. Accepts bead IDs as positional arguments. Equivalent to: bd notion sync —push —issues <ids> bd notion push [bead-ids...] [flags] **Flags:** --dry-run Preview push without making changes [​](https://beads.gascity.com/cli-reference/notion#bd-notion-status) bd notion status ---------------------------------------------------------------------------------------- Show Notion sync status bd notion status [flags] [​](https://beads.gascity.com/cli-reference/notion#bd-notion-sync) bd notion sync ------------------------------------------------------------------------------------ Synchronize issues between beads and Notion. By default this performs bidirectional sync. Use —pull or —push to limit direction. bd notion sync [flags] **Flags:** --create-only Only create missing remote pages, do not update existing ones --dry-run Preview changes without making mutations --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --parent string Limit push to this bead and its descendants (push only). Mutually exclusive with --issues. --prefer-local On conflict, keep the local beads version --prefer-notion On conflict, use the Notion version --pull Only pull issues from Notion --push Only push issues to Notion --state string Issue state to sync: open, closed, or all (default "all") [bd note](https://beads.gascity.com/cli-reference/note) [bd onboard](https://beads.gascity.com/cli-reference/onboard) ⌘I --- # bd repo - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/repo#content-area) Generated from `bd help --doc repo`. Configure and manage multiple repository support for multi-repo hydration. Multi-repo support allows hydrating issues from multiple beads repositories into a single database for unified cross-repo issue tracking. Configuration is stored in .beads/config.yaml under the ‘repos’ section: repos: primary: ”.” additional: * ~/beads-planning * ~/work-repo Examples: bd repo add ~/beads-planning # Add planning repo bd repo add ../other-repo # Add relative path repo bd repo list # Show all configured repos bd repo remove ~/beads-planning # Remove by path bd repo sync # Sync from all configured repos bd repo [flags] [​](https://beads.gascity.com/cli-reference/repo#bd-repo-add) bd repo add ---------------------------------------------------------------------------- Add a repository path to the repos.additional list in config.yaml. The path should point to a directory containing a .beads folder. Paths can be absolute or relative (they are stored as-is). This modifies .beads/config.yaml, which is version-controlled and shared across all clones of this repository. bd repo add <path> [flags] **Flags:** --json Output JSON [​](https://beads.gascity.com/cli-reference/repo#bd-repo-list) bd repo list ------------------------------------------------------------------------------ List all repositories configured in .beads/config.yaml. Shows the primary repository (always ”.”) and any additional repositories configured for hydration. bd repo list [flags] **Flags:** --json Output JSON [​](https://beads.gascity.com/cli-reference/repo#bd-repo-remove) bd repo remove ---------------------------------------------------------------------------------- Remove a repository path from the repos.additional list in config.yaml. The path must exactly match what was added (e.g., if you added “~/foo”, you must remove “~/foo”, not “/home/user/foo”). This command also removes any previously-hydrated issues from the database that came from the removed repository. bd repo remove <path> [flags] **Flags:** --json Output JSON [​](https://beads.gascity.com/cli-reference/repo#bd-repo-sync) bd repo sync ------------------------------------------------------------------------------ Synchronize issues from all configured additional repositories. Reads issues.jsonl from each additional repository and imports them into the primary database with their original prefixes and source\_repo set. Uses mtime caching to skip repos whose JSONL hasn’t changed. Also triggers Dolt push/pull if a remote is configured. bd repo sync [flags] **Flags:** --json Output JSON --verbose Show detailed sync progress [bd reopen](https://beads.gascity.com/cli-reference/reopen) [bd restore](https://beads.gascity.com/cli-reference/restore) ⌘I --- # bd worktree - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/worktree#content-area) Generated from `bd help --doc worktree`. Manage git worktrees with proper beads configuration. Worktrees allow multiple working directories sharing the same git repository, enabling parallel development (e.g., multiple agents or features). Worktrees automatically share the same beads database as the main repository via git common directory discovery — no manual redirect configuration needed. Examples: bd worktree create feature-auth # Create worktree bd worktree create bugfix —branch fix-1 # Create with specific branch name bd worktree list # List all worktrees bd worktree remove feature-auth # Remove worktree (with safety checks) bd worktree info # Show info about current worktree bd worktree [flags] [​](https://beads.gascity.com/cli-reference/worktree#bd-worktree-create) bd worktree create ---------------------------------------------------------------------------------------------- Create a git worktree for parallel development. This command: 1. Creates a git worktree at ./<name> (or specified path) 2. Adds the worktree path to .gitignore (if inside repo root) The worktree automatically shares the same beads database as the main repository via git common directory discovery — no redirect file needed. Examples: bd worktree create feature-auth # Create at ./feature-auth bd worktree create bugfix —branch fix-1 # Create with branch name bd worktree create ../agents/worker-1 # Create at relative path bd worktree create <name> [--branch=<branch>] [flags] **Flags:** --branch string Branch name for the worktree (default: same as name) [​](https://beads.gascity.com/cli-reference/worktree#bd-worktree-info) bd worktree info ------------------------------------------------------------------------------------------ Show information about the current worktree. If the current directory is in a git worktree, shows: * Worktree path and name * Branch * Beads configuration (redirect or main) * Main repository location Examples: bd worktree info # Show current worktree info bd worktree info —json # JSON output bd worktree info [flags] [​](https://beads.gascity.com/cli-reference/worktree#bd-worktree-list) bd worktree list ------------------------------------------------------------------------------------------ List all git worktrees and their beads configuration state. Shows each worktree with: * Name (directory name) * Path (full path) * Branch * Beads state: “redirect” (uses shared db), “shared” (is main), “none” (no beads) Examples: bd worktree list # List all worktrees bd worktree list —json # JSON output bd worktree list [flags] [​](https://beads.gascity.com/cli-reference/worktree#bd-worktree-remove) bd worktree remove ---------------------------------------------------------------------------------------------- Remove a git worktree with safety checks. Before removing, this command checks for: * Uncommitted changes * Unpushed commits * Stashes Use —force to skip safety checks (not recommended). Examples: bd worktree remove feature-auth # Remove with safety checks bd worktree remove feature-auth —force # Skip safety checks bd worktree remove <name> [flags] **Flags:** --force Skip safety checks [bd where](https://beads.gascity.com/cli-reference/where) ⌘I --- # bd migrate - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/migrate#content-area) Generated from `bd help --doc migrate`. Database migration and data transformation commands. Without subcommand, checks and updates database metadata to current version. Subcommands: hooks Plan git hook migration to marker-managed format issues Move issues between repositories schema Apply pending schema migrations (idempotent) sync Set up sync.branch workflow for multi-clone setups bd migrate [flags] **Flags:** --dry-run Show what would be done without making changes --inspect Show migration plan and database state for AI agent analysis --json Output migration statistics in JSON format --update-repo-id Update repository ID (use after changing git remote) --yes Auto-confirm prompts [​](https://beads.gascity.com/cli-reference/migrate#bd-migrate-hooks) bd migrate hooks ----------------------------------------------------------------------------------------- Analyze git hook files and sidecar artifacts for migration to marker-managed format. Modes: —dry-run Preview migration operations without changing files —apply Apply migration operations Examples: bd migrate hooks —dry-run bd migrate hooks —apply bd migrate hooks —apply —yes bd migrate hooks —dry-run —json bd migrate hooks [path] [flags] **Flags:** --apply Apply planned hook migration changes --dry-run Show what would be done without making changes --json Output in JSON format --yes Skip confirmation prompt for --apply [​](https://beads.gascity.com/cli-reference/migrate#bd-migrate-issues) bd migrate issues ------------------------------------------------------------------------------------------- Move issues from one source repository to another with filtering and dependency preservation. This command updates the source\_repo field for selected issues, allowing you to: * Move contributor planning issues to upstream repository * Reorganize issues across multi-phase repositories * Consolidate issues from multiple repos Examples: [​](https://beads.gascity.com/cli-reference/migrate#preview-migration-from-planning-repo-to-current-repo) Preview migration from planning repo to current repo ================================================================================================================================================================= bd migrate-issues —from ~/.beads-planning —to . —dry-run [​](https://beads.gascity.com/cli-reference/migrate#move-all-open-p1-bugs) Move all open P1 bugs =================================================================================================== bd migrate-issues —from ~/repo1 —to ~/repo2 —priority 1 —type bug —status open [​](https://beads.gascity.com/cli-reference/migrate#move-specific-issues-with-their-dependencies) Move specific issues with their dependencies ================================================================================================================================================= bd migrate-issues —from . —to ~/archive —id bd-abc —id bd-xyz —include closure [​](https://beads.gascity.com/cli-reference/migrate#move-issues-with-label-filter) Move issues with label filter =================================================================================================================== bd migrate-issues —from . —to ~/feature-work —label frontend —label urgent bd migrate issues [flags] **Flags:** --dry-run Show plan without making changes --from string Source repository (required) --id strings Specific issue IDs to migrate (can specify multiple) --ids-file string File containing issue IDs (one per line) --include string Include dependencies: none/upstream/downstream/closure (default "none") --label strings Filter by labels (can specify multiple) --priority int Filter by priority (0-4) (default -1) --status string Filter by status (open/closed/all) --strict Fail on orphaned dependencies or missing repos --to string Destination repository (required) --type string Filter by issue type (bug/feature/task/epic/chore/decision) --within-from-only Only include dependencies from source repo (default true) --yes Skip confirmation prompt [​](https://beads.gascity.com/cli-reference/migrate#bd-migrate-schema) bd migrate schema ------------------------------------------------------------------------------------------- Apply pending schema migrations idempotently. Schema migrations also run automatically on store open, so this subcommand is typically a no-op. It exists to make migration explicit and observable in CI, release gates, and recovery scenarios. Example: bd migrate schema bd migrate schema —json bd migrate schema [flags] **Flags:** --json Output in JSON format [​](https://beads.gascity.com/cli-reference/migrate#bd-migrate-sync) bd migrate sync --------------------------------------------------------------------------------------- Configure separate branch workflow for multi-clone setups. This sets the sync.branch config value so that issue data is committed to a dedicated branch, keeping your main branch clean. Example: bd migrate sync beads-sync bd migrate sync <branch> [flags] **Flags:** --dry-run Show what would be done without making changes --json Output in JSON format [bd metrics](https://beads.gascity.com/cli-reference/metrics) [bd mol](https://beads.gascity.com/cli-reference/mol) ⌘I --- # bd swarm - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/swarm#content-area) Generated from `bd help --doc swarm`. Swarm management commands for coordinating parallel work on epics. A swarm is a structured body of work defined by an epic and its children, with dependencies forming a DAG (directed acyclic graph) of work. bd swarm [flags] [​](https://beads.gascity.com/cli-reference/swarm#bd-swarm-create) bd swarm create ------------------------------------------------------------------------------------- Create a swarm molecule to orchestrate parallel work on an epic. The swarm molecule: * Links to the epic it orchestrates * Has mol\_type=swarm for discovery * Specifies a coordinator (optional) * Can be picked up by any coordinator agent If given a single issue (not an epic), it will be auto-wrapped: * Creates an epic with that issue as its only child * Then creates the swarm molecule for that epic Examples: bd swarm create bd-epic-123 # Create swarm for epic bd swarm create bd-epic-123 —coordinator=observer/ # With specific coordinator bd swarm create bd-task-456 # Auto-wrap single issue bd swarm create [epic-id] [flags] **Flags:** --coordinator string Coordinator address (e.g., my-project/witness) --force Create new swarm even if one already exists [​](https://beads.gascity.com/cli-reference/swarm#bd-swarm-list) bd swarm list --------------------------------------------------------------------------------- List all swarm molecules with their status. Shows each swarm molecule with: * Progress (completed/total issues) * Active workers * Epic ID and title Examples: bd swarm list # List all swarms bd swarm list —json # Machine-readable output bd swarm list [flags] [​](https://beads.gascity.com/cli-reference/swarm#bd-swarm-status) bd swarm status ------------------------------------------------------------------------------------- Show the current status of a swarm, computed from beads. Accepts either: * An epic ID (shows status for that epic’s children) * A swarm molecule ID (follows the link to find the epic) Displays issues grouped by state: * Completed: Closed issues * Active: Issues currently in\_progress (with assignee) * Ready: Open issues with all dependencies satisfied * Blocked: Open issues waiting on dependencies The status is COMPUTED from beads, not stored separately. If beads changes, status changes. Examples: bd swarm status gt-epic-123 # Show swarm status by epic bd swarm status gt-swarm-456 # Show status via swarm molecule bd swarm status gt-epic-123 —json # Machine-readable output bd swarm status [epic-or-swarm-id] [flags] [​](https://beads.gascity.com/cli-reference/swarm#bd-swarm-validate) bd swarm validate ----------------------------------------------------------------------------------------- Validate an epic’s structure to ensure it’s ready for swarm execution. Checks for: * Correct dependency direction (requirement-based, not temporal) * Orphaned issues (roots with no dependents) * Missing dependencies (leaves that should depend on something) * Cycles (impossible to resolve) * Disconnected subgraphs Reports: * Ready fronts (waves of parallel work) * Estimated worker-sessions * Maximum parallelism * Warnings for potential issues Examples: bd swarm validate gt-epic-123 # Validate epic structure bd swarm validate gt-epic-123 —verbose # Include detailed issue graph bd swarm validate [epic-id] [flags] **Flags:** --verbose Include detailed issue graph in output [bd supersede](https://beads.gascity.com/cli-reference/supersede) [bd tag](https://beads.gascity.com/cli-reference/tag) ⌘I --- # bd dep - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/dep#content-area) Generated from `bd help --doc dep`. Manage dependencies between issues. When called with an issue ID and —blocks flag, creates a blocking dependency: bd dep <blocker-id> —blocks <blocked-id> This is equivalent to: bd dep add <blocked-id> <blocker-id> Examples: bd dep bd-xyz —blocks bd-abc # bd-xyz blocks bd-abc bd dep add bd-abc bd-xyz # Same as above (bd-abc depends on bd-xyz) bd dep [issue-id] [flags] **Flags:** -b, --blocks string Issue ID that this issue blocks (shorthand for: bd dep add <blocked> <blocker>) --no-cycle-check Skip per-edge cycle checks for speed (bulk wiring); bulk --file adds still run one final whole-graph check before commit [​](https://beads.gascity.com/cli-reference/dep#bd-dep-add) bd dep add ------------------------------------------------------------------------- Add a dependency between two issues. The depends-on-id can be provided as: * A positional argument: bd dep add issue-123 issue-456 * A flag: bd dep add issue-123 —blocked-by issue-456 * A flag: bd dep add issue-123 —depends-on issue-456 The —blocked-by and —depends-on flags are aliases and both mean “issue-123 depends on (is blocked by) the specified issue.” The depends-on-id can be: * A local issue ID (e.g., bd-xyz) * An external reference: external:<project>:<capability> For bulk wiring, pass newline-delimited JSON with —file. Each line must be an object with “from” and “to” fields, and may include “type”. The aliases “issue\_id” and “depends\_on\_id” are also accepted. Use —file - to read stdin. External references are stored as-is and resolved at query time using the external\_projects config. They block the issue until the capability is “shipped” in the target project. Examples: bd dep add bd-42 bd-41 # Positional args bd dep add bd-42 —blocked-by bd-41 # Flag syntax (same effect) bd dep add bd-42 —depends-on bd-41 # Alias (same effect) bd dep add gt-xyz external:beads:mol-run-assignee # Cross-project dependency bd dep add bd-42 bd-41 —no-cycle-check # Skip cycle check (bulk wiring) bd dep add —file deps.jsonl # Bulk JSONL: {“from”:“bd-42”,“to”:“bd-41”} bd dep add [issue-id] [depends-on-id] [flags] **Flags:** --blocked-by string Issue ID that blocks the first issue (alternative to positional arg) --depends-on string Issue ID that the first issue depends on (alias for --blocked-by) --file string Read dependency edges from JSONL file, or '-' for stdin --no-cycle-check Skip per-edge cycle checks for speed (bulk wiring); bulk --file adds still run one final whole-graph check before commit -t, --type string Dependency type (blocks|tracks|related|parent-child|discovered-from|until|caused-by|validates|relates-to|supersedes) (default "blocks") [​](https://beads.gascity.com/cli-reference/dep#bd-dep-cycles) bd dep cycles ------------------------------------------------------------------------------- Detect dependency cycles bd dep cycles [flags] [​](https://beads.gascity.com/cli-reference/dep#bd-dep-list) bd dep list --------------------------------------------------------------------------- List dependencies or dependents of one or more issues with optional type filtering. By default shows dependencies (what issues depend on). Use —direction to control: * down: Show dependencies (what this issue depends on) - default * up: Show dependents (what depends on this issue) Multiple IDs can be provided for batch dep listing. With —json, the output is a flat array of dependency records across all requested issues. Use —type to filter by dependency type (e.g., tracks, blocks, parent-child). Examples: bd dep list gt-abc # Show what gt-abc depends on bd dep list gt-abc gt-def # Batch: deps for both issues bd dep list gt-abc —direction=up # Show what depends on gt-abc bd dep list gt-abc —direction=up -t tracks # Show what tracks gt-abc (convoy tracking) bd dep list [issue-id...] [flags] **Flags:** --direction string Direction: 'down' (dependencies), 'up' (dependents) (default "down") -t, --type string Filter by dependency type (e.g., tracks, blocks, parent-child) [​](https://beads.gascity.com/cli-reference/dep#bd-dep-relate) bd dep relate ------------------------------------------------------------------------------- Create a loose ‘see also’ relationship between two issues. The relates\_to link is bidirectional - both issues will reference each other. This enables knowledge graph connections without blocking or hierarchy. Examples: bd relate bd-abc bd-xyz # Link two related issues bd relate bd-123 bd-456 # Create see-also connection bd dep relate <id1> <id2> [flags] [​](https://beads.gascity.com/cli-reference/dep#bd-dep-remove) bd dep remove ------------------------------------------------------------------------------- Remove a dependency bd dep remove [issue-id] [depends-on-id] [flags] **Aliases:** rm [​](https://beads.gascity.com/cli-reference/dep#bd-dep-tree) bd dep tree --------------------------------------------------------------------------- Show dependency tree rooted at the given issue. By default, shows dependencies (what blocks this issue). Use —direction to control: * down: Show dependencies (what blocks this issue) - default * up: Show dependents (what this issue blocks) * both: Show full graph in both directions Examples: bd dep tree gt-0iqq # Show what blocks gt-0iqq bd dep tree gt-0iqq —direction=up # Show what gt-0iqq blocks bd dep tree gt-0iqq —status=open # Only show open issues bd dep tree gt-0iqq —depth=3 # Limit to 3 levels deep bd dep tree [issue-id] [flags] **Flags:** --direction string Tree direction: 'down' (dependencies), 'up' (dependents), or 'both' --format string Output format: 'mermaid' for Mermaid.js flowchart -d, --max-depth int Maximum tree depth to display (safety limit) (default 50) --reverse Show dependent tree (deprecated: use --direction=up) --show-all-paths Show all paths to nodes (no deduplication for diamond dependencies) --status string Filter to only show issues with this status (open, in_progress, blocked, deferred, closed) [​](https://beads.gascity.com/cli-reference/dep#bd-dep-unrelate) bd dep unrelate ----------------------------------------------------------------------------------- Remove a relates\_to relationship between two issues. Removes the link in both directions. Example: bd unrelate bd-abc bd-xyz bd dep unrelate <id1> <id2> [flags] [bd delete](https://beads.gascity.com/cli-reference/delete) [bd diff](https://beads.gascity.com/cli-reference/diff) ⌘I --- # bd gate - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/gate#content-area) Generated from `bd help --doc gate`. Gates are async wait conditions that block workflow steps. Gates are created automatically when a formula step has a gate field. They must be closed (manually or via watchers) for the blocked step to proceed. Gate types: human - Requires manual bd close (Phase 1) timer - Expires after timeout (Phase 2) gh:run - Waits for GitHub workflow (Phase 3) gh:pr - Waits for PR merge (Phase 3) bead - Waits for cross-rig bead to close (Phase 4) For bead gates, await\_id format is <rig>:<bead-id> (e.g., “other-project:op-abc123”). Examples: bd gate list # Show all open gates bd gate list —all # Show all gates including closed bd gate check # Evaluate all open gates bd gate check —type=bead # Evaluate only bead gates bd gate resolve <id> # Close a gate manually bd gate [flags] [​](https://beads.gascity.com/cli-reference/gate#bd-gate-add-waiter) bd gate add-waiter ------------------------------------------------------------------------------------------ Register an agent as a waiter on a gate bead. When the gate closes, the waiter will receive a wake notification via ‘bd gate wake’. The waiter is typically the worker’s address (e.g., “my-project/workers/agent-1”). This is used by ‘bd done —phase-complete’ to register for gate wake notifications. bd gate add-waiter <gate-id> <waiter> [flags] [​](https://beads.gascity.com/cli-reference/gate#bd-gate-check) bd gate check -------------------------------------------------------------------------------- Evaluate gate conditions and automatically close resolved gates. By default, checks all open gates. Use —type to filter by gate type. Gate types: gh - Check all GitHub gates (gh:run and gh:pr) gh:run - Check GitHub Actions workflow runs gh:pr - Check pull request merge status timer - Check timer gates (auto-expire based on timeout) bead - Check cross-rig bead gates all - Check all gate types GitHub gates use the ‘gh’ CLI to query status: * gh:run checks ‘gh run view <id> —json status,conclusion’ * gh:pr checks ‘gh pr view <id> —json state,title’ A gate is resolved when: * gh:run: status=completed AND conclusion=success * gh:pr: state=MERGED * timer: current time > created\_at + timeout * bead: target bead status=closed A gate is escalated when: * gh:run: status=completed AND conclusion in (failure, canceled) * gh:pr: state=CLOSED Examples: bd gate check # Check all gates bd gate check —type=gh # Check only GitHub gates bd gate check —type=gh:run # Check only workflow run gates bd gate check —type=timer # Check only timer gates bd gate check —type=bead # Check only cross-rig bead gates bd gate check —dry-run # Show what would happen without changes bd gate check —escalate # Escalate expired/failed gates bd gate check [flags] **Flags:** --dry-run Show what would happen without making changes -e, --escalate Escalate failed/expired gates -l, --limit int Limit results (default 100) (default 100) -t, --type string Gate type to check (gh, gh:run, gh:pr, timer, bead, all) [​](https://beads.gascity.com/cli-reference/gate#bd-gate-create) bd gate create ---------------------------------------------------------------------------------- Create an ad-hoc gate issue that blocks another issue until resolved. The blocked issue will not appear in ‘bd ready’ until the gate is resolved via ‘bd gate resolve’. Gate types: human - Requires manual ‘bd gate resolve’ (default) timer - Auto-resolves after —timeout duration gh:run - Waits for GitHub Actions workflow gh:pr - Waits for PR merge Examples: bd gate create —blocks bd-abc bd gate create —type=human —blocks bd-abc —reason=“Need design review” bd gate create —type=timer —blocks bd-abc —timeout=2h bd gate create —type=gh:pr —blocks bd-abc —await-id=42 bd gate create [flags] **Flags:** --await-id string Condition identifier (run ID, PR number, etc.) --blocks string Issue ID to block (required) -r, --reason string Reason for the gate --timeout string Timeout duration (e.g., 2h, 30m) -t, --type string Gate type (human, timer, gh:run, gh:pr) (default "human") [​](https://beads.gascity.com/cli-reference/gate#bd-gate-discover) bd gate discover -------------------------------------------------------------------------------------- Discovers GitHub workflow run IDs for gates awaiting CI/CD completion. This command finds open gates with await\_type=“gh:run” that don’t have an await\_id, queries recent GitHub workflow runs, and matches them using heuristics: * Branch name matching * Commit SHA matching * Time proximity (runs within 5 minutes of gate creation) Once matched, the gate’s await\_id is updated with the GitHub run ID, enabling subsequent polling to check the run’s status. Examples: bd gate discover # Auto-discover run IDs for all matching gates bd gate discover —dry-run # Preview what would be matched (no updates) bd gate discover —branch main —limit 10 # Only match runs on ‘main’ branch bd gate discover [flags] **Flags:** -b, --branch string Filter runs by branch (default: current branch) -n, --dry-run Preview mode: show matches without updating -l, --limit int Max runs to query from GitHub (default 10) -a, --max-age duration Max age for gate/run matching (default 30m0s) [​](https://beads.gascity.com/cli-reference/gate#bd-gate-list) bd gate list ------------------------------------------------------------------------------ List all gate issues in the current beads database. By default, shows only open gates. Use —all to include closed gates. bd gate list [flags] **Flags:** -a, --all Show all gates including closed -n, --limit int Limit results (default 50) (default 50) [​](https://beads.gascity.com/cli-reference/gate#bd-gate-resolve) bd gate resolve ------------------------------------------------------------------------------------ Close a gate issue to unblock the step waiting on it. This is equivalent to ‘bd close <gate-id>’ but with a more explicit name. Use —reason to provide context for why the gate was resolved. bd gate resolve <gate-id> [flags] **Flags:** -r, --reason string Reason for resolving the gate [​](https://beads.gascity.com/cli-reference/gate#bd-gate-show) bd gate show ------------------------------------------------------------------------------ Display details of a gate issue including its waiters. This is similar to ‘bd show’ but validates that the issue is a gate. bd gate show <gate-id> [flags] [bd formula](https://beads.gascity.com/cli-reference/formula) [bd gc](https://beads.gascity.com/cli-reference/gc) ⌘I --- # bd linear - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/linear#content-area) Generated from `bd help --doc linear`. Synchronize issues between beads and Linear. Configuration: bd config set linear.api\_key “YOUR\_API\_KEY” bd config set linear.team\_id “TEAM\_ID” bd config set linear.team\_ids “TEAM\_ID1,TEAM\_ID2” # Multiple teams (comma-separated) bd config set linear.project\_id “PROJECT\_ID” # Optional: sync only this project Environment variables (alternative to config): LINEAR\_API\_KEY - Linear API key (for individual developers) LINEAR\_TEAM\_ID - Linear team ID (UUID, singular) LINEAR\_TEAM\_IDS - Linear team IDs (comma-separated UUIDs) OAuth (for CI workers / automated sync): LINEAR\_OAUTH\_CLIENT\_ID - OAuth app client ID LINEAR\_OAUTH\_CLIENT\_SECRET - OAuth app client secret When both OAuth env vars are set, OAuth client\_credentials flow is used instead of the API key. This allows CI workers to authenticate as an application (actor=application) rather than impersonating a user. Precedence: OAuth > LINEAR\_API\_KEY > config file. Data Mapping (optional, sensible defaults provided): Priority mapping (Linear 0-4 to Beads 0-4): bd config set linear.priority\_map.0 4 # No priority -> Backlog bd config set linear.priority\_map.1 0 # Urgent -> Critical bd config set linear.priority\_map.2 1 # High -> High bd config set linear.priority\_map.3 2 # Medium -> Medium bd config set linear.priority\_map.4 3 # Low -> Low State mapping (Linear state type to Beads status): bd config set linear.state\_map.backlog open bd config set linear.state\_map.unstarted open bd config set linear.state\_map.started in\_progress bd config set linear.state\_map.completed closed bd config set linear.state\_map.canceled closed bd config set linear.state\_map.my\_custom\_state in\_progress # Custom state names Label to issue type mapping: bd config set linear.label\_type\_map.bug bug bd config set linear.label\_type\_map.feature feature bd config set linear.label\_type\_map.epic epic Relation type mapping (Linear relations to Beads dependencies): bd config set linear.relation\_map.blocks blocks bd config set linear.relation\_map.blockedBy blocks bd config set linear.relation\_map.duplicate duplicates bd config set linear.relation\_map.related related ID generation (optional, hash IDs to match bd/Jira hash mode): bd config set linear.id\_mode “hash” # hash (default) bd config set linear.hash\_length “6” # hash length 3-8 (default: 6) Examples: bd linear sync —pull # Import issues from Linear bd linear sync —push # Export issues to Linear bd linear sync # Bidirectional sync (pull then push) bd linear sync —dry-run # Preview sync without changes bd create “Fix login” —external-ref [https://linear.app/team/issue/TEAM-123](https://linear.app/team/issue/TEAM-123) [​](https://beads.gascity.com/cli-reference/linear#link-a-local-issue-to-an-existing-linear-issue) Link a local issue to an existing Linear issue ==================================================================================================================================================== bd linear status # Show sync status bd linear [flags] [​](https://beads.gascity.com/cli-reference/linear#bd-linear-pull) bd linear pull ------------------------------------------------------------------------------------ Pull one or more items from Linear. Accepts bead IDs or external references as positional arguments. Equivalent to: bd linear sync —pull —issues <refs> bd linear pull [refs...] [flags] **Flags:** --dry-run Preview pull without making changes --relations Import Linear relations as bd dependencies when pulling [​](https://beads.gascity.com/cli-reference/linear#bd-linear-push) bd linear push ------------------------------------------------------------------------------------ Push one or more beads issues to Linear. Accepts bead IDs as positional arguments. Equivalent to: bd linear sync —push —issues <ids> bd linear push [bead-ids...] [flags] **Flags:** --dry-run Preview push without making changes [​](https://beads.gascity.com/cli-reference/linear#bd-linear-status) bd linear status ---------------------------------------------------------------------------------------- Show the current Linear sync status, including: * Last sync timestamp * Configuration status * Number of issues with Linear links * Issues pending push (no external\_ref) bd linear status [flags] [​](https://beads.gascity.com/cli-reference/linear#bd-linear-sync) bd linear sync ------------------------------------------------------------------------------------ Synchronize issues between beads and Linear. Modes: —pull Import issues from Linear into beads —push Export issues from beads to Linear —pull-if-stale Pull only if data is stale (skip if fresh) (no flags) Bidirectional sync: pull then push, with conflict resolution Staleness (—pull-if-stale): —threshold 20m How old data must be before pulling (default 20m) A 5-minute debounce prevents agent loops: if a pull completed within 5 minutes, data is always treated as fresh regardless of the threshold. Team Selection: —team ID1,ID2 Override configured team IDs for this sync Multiple teams can be configured via linear.team\_ids (comma-separated). Falls back to linear.team\_id for backward compatibility. Push requires explicit —team when multiple teams are configured. Pull Options: —milestones Reconstruct Linear project milestones as local epic parents Type Filtering (—push only): —type task,feature Only sync issues of these types —exclude-type wisp Exclude issues of these types —include-ephemeral Include ephemeral issues (wisps, etc.); default is to exclude —parent TICKET Only push this ticket and its descendants —relations Import Linear relations as bd dependencies on pull Conflict Resolution: By default, newer timestamp wins. Override with: —prefer-local Always prefer local beads version —prefer-linear Always prefer Linear version Examples: bd linear sync —pull # Import from Linear bd linear sync —pull-if-stale # Pull only if data is stale bd linear sync —pull-if-stale —threshold 5m # Pull if older than 5 minutes bd linear sync —pull —relations # Import Linear blocking relations as bd deps bd linear sync —push —create-only # Push new issues only bd linear sync —push —type=task,feature # Push only tasks and features bd linear sync —push —exclude-type=wisp # Push all except wisps bd linear sync —push —parent=bd-abc123 # Push one ticket tree bd linear sync —dry-run # Preview without changes bd linear sync —prefer-local # Bidirectional, local wins bd linear sync [flags] **Flags:** --create-only Only create new issues, don't update existing --dry-run Preview sync without making changes --exclude-type strings Exclude issues of these types (can be repeated) --include-ephemeral Include ephemeral issues (wisps, etc.) when pushing to Linear --issues string Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent. --milestones Reconstruct Linear project milestones as local epic parents when pulling --no-wait Fail immediately if another sync is running instead of waiting --parent string Limit push to this beads ticket and its descendants --prefer-linear Prefer Linear version on conflicts --prefer-local Prefer local version on conflicts --pull Pull issues from Linear --pull-if-stale Pull only if Linear data is stale (skip if fresh) --push Push issues to Linear --relations Import Linear relations as bd dependencies when pulling --state string Issue state to sync: open, closed, all (default "all") --team strings Team ID(s) to sync (overrides configured team_id/team_ids) --threshold duration Staleness threshold for --pull-if-stale (default 20m) (default 20m0s) --type strings Only sync issues of these types (can be repeated) --update-refs Update external_ref after creating Linear issues (default true) [​](https://beads.gascity.com/cli-reference/linear#bd-linear-teams) bd linear teams -------------------------------------------------------------------------------------- List all teams accessible with your Linear API key. Use this to find the team ID (UUID) needed for configuration. Example: bd linear teams bd config set linear.team\_id “12345678-1234-1234-1234-123456789abc” bd linear teams [flags] [bd label](https://beads.gascity.com/cli-reference/label) [bd link](https://beads.gascity.com/cli-reference/link) ⌘I --- # bd dolt - Beads Documentation > Documentation Index > ------------------- > > Fetch the complete documentation index at: [/llms.txt](https://beads.gascity.com/llms.txt) > > Use this file to discover all available pages before exploring further. [Skip to main content](https://beads.gascity.com/cli-reference/dolt#content-area) Generated from `bd help --doc dolt`. Configure and manage Dolt database settings and server lifecycle. Beads uses a dolt sql-server for all database operations. The server is auto-started transparently when needed. Use these commands for explicit control or diagnostics. Server lifecycle: bd dolt start Start the Dolt server for this project bd dolt stop Stop the Dolt server for this project bd dolt status Show Dolt server status Configuration: bd dolt show Show current Dolt configuration with connection test bd dolt set <k> <v> Set a configuration value bd dolt test Test server connection Version control: bd dolt commit Commit pending changes bd dolt push Push commits to Dolt remote bd dolt pull Pull commits from Dolt remote Remote management: bd dolt remote add <name> <url> Add a Dolt remote bd dolt remote list List configured remotes bd dolt remote remove <name> Remove a Dolt remote Configuration keys for ‘bd dolt set’: database Database name (default: issue prefix or “beads”) host Server host (default: 127.0.0.1) port Server port (auto-detected; override with bd dolt set port <N>) user MySQL user (default: root) data-dir Custom dolt data directory (absolute path; default: .beads/dolt) Flags for ‘bd dolt set’: —update-config Also write to config.yaml for team-wide defaults Examples: bd dolt set database myproject bd dolt set host 192.168.1.100 —update-config bd dolt set data-dir /home/user/.beads-dolt/myproject bd dolt test bd dolt [flags] [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-clean-databases) bd dolt clean-databases ---------------------------------------------------------------------------------------------------- Identify and drop leftover test and agent databases that accumulate on the shared Dolt server from interrupted test runs and terminated agents. Stale database prefixes: testdb\__, doctest\__, doctortest\__, beads\_pt_, beads\_vr\*, beads\_t\* These waste server memory and can degrade performance under concurrent load. Use —dry-run to see what would be dropped without actually dropping. bd dolt clean-databases [flags] **Flags:** --dry-run Show what would be dropped without dropping [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-commit) bd dolt commit ---------------------------------------------------------------------------------- Create a Dolt commit from any uncommitted changes in the working set. This is the primary commit point for batch mode. When auto-commit is set to “batch”, changes accumulate in the working set across multiple bd commands and are committed together here with a descriptive summary message. Also useful before push operations that require a clean working set, or when auto-commit was off or changes were made externally. For more options (—stdin, custom messages), see: bd vc commit bd dolt commit [flags] **Flags:** -m, --message string Commit message (default: auto-generated) [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-killall) bd dolt killall ------------------------------------------------------------------------------------ Find and kill orphan dolt sql-server processes not tracked by the canonical PID file for the current repo’s Dolt data directory. Under an orchestrator, the canonical server lives at $GT\_ROOT/.beads/. Any other dolt sql-server processes using that shared data directory are considered orphans and will be killed. In standalone mode, only dolt sql-server processes using the current project’s Dolt data directory are eligible for cleanup. Other projects’ servers are preserved. bd dolt killall [flags] [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-pull) bd dolt pull ------------------------------------------------------------------------------ Pull commits from the configured Dolt remote into the local database. Requires a Dolt remote to be configured in the database directory. For Hosted Dolt, set DOLT\_REMOTE\_USER and DOLT\_REMOTE\_PASSWORD environment variables for authentication. Use —remote to pull from a specific named remote instead of the default. The remote must already exist (see ‘bd dolt remote add’). bd dolt pull [flags] **Flags:** --remote string Pull from a specific named remote instead of the default [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-push) bd dolt push ------------------------------------------------------------------------------ Push local Dolt commits to the configured remote. Requires a Dolt remote to be configured in the database directory. For Hosted Dolt, set DOLT\_REMOTE\_USER and DOLT\_REMOTE\_PASSWORD environment variables for authentication. Use —force to overwrite remote changes (e.g., when the remote has uncommitted changes in its working set). Use —remote to push to a specific named remote instead of the default. The remote must already exist (see ‘bd dolt remote add’). bd dolt push [flags] **Flags:** --force Force push (overwrite remote changes) --remote string Push to a specific named remote instead of the default [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-remote) bd dolt remote ---------------------------------------------------------------------------------- Manage Dolt remotes for push/pull replication. Subcommands: add <name> <url> Add a new remote list List all configured remotes remove <name> Remove a remote bd dolt remote [flags] ### [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-remote-add) bd dolt remote add Add a Dolt remote bd dolt remote add <name> <url> [flags] ### [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-remote-list) bd dolt remote list List configured Dolt remotes bd dolt remote list [flags] ### [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-remote-remove) bd dolt remote remove Remove a Dolt remote bd dolt remote remove <name> [flags] [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-set) bd dolt set ---------------------------------------------------------------------------- Set a Dolt configuration value in metadata.json. Keys: database Database name (default: issue prefix or “beads”) host Server host (default: 127.0.0.1) port Server port (auto-detected; override with bd dolt set port <N>) user MySQL user (default: root) data-dir Custom dolt data directory (absolute path; default: .beads/dolt) Use —update-config to also write to config.yaml for team-wide defaults. Examples: bd dolt set database myproject bd dolt set host 192.168.1.100 bd dolt set port 3307 —update-config bd dolt set data-dir /home/user/.beads-dolt/myproject bd dolt set <key> <value> [flags] **Flags:** --update-config Also write to config.yaml for team-wide defaults [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-show) bd dolt show ------------------------------------------------------------------------------ Show current Dolt configuration with connection status bd dolt show [flags] [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-start) bd dolt start -------------------------------------------------------------------------------- Start a dolt sql-server for the current beads project. The server runs in the background on a per-project port derived from the project path. PID and logs are stored in .beads/. The server auto-starts transparently when needed, so manual start is rarely required. Use this command for explicit control or diagnostics. bd dolt start [flags] [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-status) bd dolt status ---------------------------------------------------------------------------------- Show the status of the Dolt engine for the current project. In embedded mode, reports that the Dolt engine runs in-process and shows the on-disk data directory. For beads-managed (local) servers, displays PID, port, and data directory from the local PID file. For externally- managed servers — either a remote dolt\_server\_host or a local server managed outside bd (dolt.auto-start: false, e.g. an orchestrator-shared sql-server) — pings the configured endpoint via SQL and reports reachability, server version, and database. bd dolt status [flags] [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-stop) bd dolt stop ------------------------------------------------------------------------------ Stop the dolt sql-server managed by beads for the current project. This sends a graceful shutdown signal. The server will restart automatically on the next bd command unless auto-start is disabled. bd dolt stop [flags] **Flags:** --force Force stop the server [​](https://beads.gascity.com/cli-reference/dolt#bd-dolt-test) bd dolt test ------------------------------------------------------------------------------ Test the connection to the configured Dolt server. This verifies that: 1. The server is reachable at the configured host:port 2. The connection can be established Use this before switching to server mode to ensure the server is running. bd dolt test [flags] [bd doctor](https://beads.gascity.com/cli-reference/doctor) [bd duplicate](https://beads.gascity.com/cli-reference/duplicate) ⌘I ---