Beads initialization

Initialize beads issue tracking in a project with manual control over when issue database changes are staged and committed.

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

Manual sync workflow

Committing beads changes

When you've made changes to issues via bd commands, flush the database to JSONL and stage the files manually:

bd hooks run pre-commit   # flush DB→JSONL + stage .beads/*.jsonl files
git commit -m "chore(issues): <description of changes>"

Example commit messages:

• •chore(issues): add epic for CI integration
• •chore(issues): update story status for authentication module
• •chore(issues): close completed infrastructure stories

Importing after git operations

After any git operation that changes commits (pull, checkout, merge, rebase), import JSONL changes back to the database:

bd sync --import-only   # JSONL→DB without staging

This ensures your local beads database stays synchronized with the JSONL files tracked in git.

Rationale

Manual sync workflow provides explicit control over when issue tracking state enters git history, allowing you to:

• •Batch multiple issue operations into single commits
• •Separate issue updates from code changes
• •Review staged issue changes before committing
• •Avoid automatic staging during experimental work

The merge driver remains enabled to handle merge conflicts in JSONL files during collaborative workflows, but it doesn't auto-stage changes during normal operations.

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 only flush to JSONL 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