Skip to main content
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)