This directory contains git hooks that integrate bd (beads) with your git workflow, solving the race condition between daemon auto-flush and git commits.

The Problem

When using bd in daemon mode, operations trigger a 5-second debounced auto-flush to JSONL. This creates a race condition:

User closes issue via MCP → daemon schedules flush (5 sec delay)
User commits code changes → JSONL appears clean
Daemon flush fires → JSONL modified after commit
Result: dirty working tree showing JSONL changes

The Solution

These git hooks ensure bd changes are always synchronized with your commits:

pre-commit - Flushes pending bd changes to JSONL before commit
post-merge - Imports updated JSONL after git pull/merge

Installation

Quick Install

From your repository root:

./examples/git-hooks/install.sh

This will:

Copy hooks to .git/hooks/
Make them executable
Back up any existing hooks

Manual Install

cp examples/git-hooks/pre-commit .git/hooks/pre-commit
cp examples/git-hooks/post-merge .git/hooks/post-merge
chmod +x .git/hooks/pre-commit .git/hooks/post-merge

How It Works

pre-commit

Before each commit, the hook runs:

bd sync --flush-only

This:

Exports any pending database changes to .beads/issues.jsonl
Stages the JSONL file if modified
Allows the commit to proceed with clean state

The hook is silent on success, fast (no git operations), and safe (fails commit if flush fails).

post-merge

After a git pull or merge, the hook runs:

bd import -i .beads/issues.jsonl

This ensures your local database reflects the merged state. The hook:

Only runs if .beads/issues.jsonl exists
Imports any new issues or updates from the merge
Warns on failure but doesn't block the merge

Note: With hash-based IDs (v0.20.1+), ID collisions don't occur - different issues get different hash IDs.

Compatibility

Auto-sync: Works alongside bd's automatic 5-second debounce
Direct mode: Hooks work in both daemon and --no-daemon mode
Worktrees: Safe to use with git worktrees

Benefits

✅ No more dirty working tree after commits
✅ Database always in sync with git
✅ Automatic collision resolution on merge
✅ Fast and silent operation
✅ Optional - manual bd sync still works

Uninstall

Remove the hooks:

rm .git/hooks/pre-commit .git/hooks/post-merge

Your backed-up hooks (if any) are in .git/hooks/*.backup-*.

See bd-51 for the race condition bug report
See AGENTS.md for the full git workflow
See examples/ for other integrations

README.md

bd Git Hooks