> ## Documentation Index
> Fetch the complete documentation index at: https://beads.gascity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bd doctor

> Check and fix beads installation health (start here)

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)
```