Beads initialization

Initialize beads issue tracking in a project with dolt database persistence.

Initialize without auto-staging hooks

bd init --skip-hooks -p <prefix> -q

Replace <prefix> with the project-specific issue prefix (e.g., INFRA, TS, CLAN).

The --skip-hooks flag prevents installation of git hooks that would automatically stage .beads/*.jsonl files on every commit. We keep the default merge driver (no --skip-merge-driver) since it only activates during merge conflicts and doesn't auto-stage.

For completely invisible beads usage without affecting repository collaborators, consider --stealth mode instead (see below).

Alternative: Stealth mode (invisible beads)

For personal use without affecting repository collaborators:

bd init --stealth -p <prefix> -q

Stealth mode configures beads to be completely invisible to git:

• Adds .beads/ to .git/info/exclude (local gitignore, not committed)
• Sets up Claude Code integration automatically
• Perfect for personal issue tracking without team coordination

With stealth mode, beads changes remain local and never enter git history.

Post-init cleanup

After bd init completes, perform these cleanup steps:

# Review AGENTS.md - the new auto-generated version is minimal and useful:
# - Points to 'bd onboard' for getting started
# - Contains brief quick reference commands
# - Includes session completion protocol
# Customize if needed, or keep the generated version.

echo "README.md" >> .beads/.gitignore

Dolt persistence

After initializing beads and creating the initial issue structure, mutations auto-commit to the dolt database. Push to the dolt remote for backup:

bd dolt push

Rationale

Beads uses a dolt database backend for issue persistence. Mutations auto-commit when dolt.auto-commit is enabled, eliminating manual serialization steps. The bd dolt push command replicates state to the git remote via refs/dolt/data for backup and cross-machine sync.

Configuring no-git-ops mode

To suppress git commands in AI agent session protocols:

bd config set no-git-ops true

This configures bd prime to output stealth mode instructions, ensuring agents perform beads operations without attempting git operations. Useful when you want manual control over when commits happen.

See also

Additional commands for working with beads:

• bd onboard - Display integration snippet for AGENTS.md
• bd prime - Show AI-optimized workflow context
• bd quickstart - View quick start guide
• bd setup - Install AI editor integrations