Skip to main content
This guide explains how to remove beads from a repository or remove the bd binary from a machine.

​
Before You Remove Data

Removing .beads/ permanently deletes the local Dolt database. If the issue history matters, make a Dolt-native backup first: 
bd backup init /path/to/beads-backup
bd backup sync
For review, migration, or interoperability, you can also write an issue-table export: 
bd export -o ~/beads-issues-$(date +%Y%m%d).jsonl
bd export is not a complete restorable database backup. It does not preserve Dolt branches, commit history, working-set state, or non-issue tables.

​
Repository Reset

Use bd reset from the repository root. It previews what will be removed by default: 
bd reset
If the preview is correct, run: 
bd reset --force
This removes beads-managed repository data such as:
  • the .beads/ directory
  • beads-managed git hook sections
  • legacy beads sync worktrees under .git/beads-worktrees/

​
Remove Hooks Only

To keep issue data but remove git hooks: 
bd hooks uninstall
This is preferable to manually deleting hook files because beads preserves unrelated user hook content outside its managed hook markers.

​
Manual Cleanup

Use manual cleanup only if bd reset is unavailable or cannot run in the repository. 
# Stop a local Dolt server if one is running.
bd dolt stop 2>/dev/null || true

# Remove beads-managed hooks when bd hooks uninstall is unavailable.
rm -f .git/hooks/pre-commit
rm -f .git/hooks/prepare-commit-msg
rm -f .git/hooks/post-merge
rm -f .git/hooks/pre-push
rm -f .git/hooks/post-checkout

# Remove the local beads database and config.
rm -rf .beads

# Remove legacy sync-branch worktrees from older beads versions.
rm -rf .git/beads-worktrees
git worktree prune
If .gitattributes contains only beads merge-driver configuration, remove it. If it contains other project entries, edit out only the beads line. If beads-specific git config remains, remove it: 
git config --unset beads.role 2>/dev/null || true
git config --unset merge.beads.driver 2>/dev/null || true
git config --unset merge.beads.name 2>/dev/null || true

​
Remove the bd Binary

The CLI is a standalone binary. Remove it according to how it was installed: 
# Homebrew
brew uninstall beads

# Go install
rm -f "$(which bd)"

# Manual install location
rm -f /usr/local/bin/bd
If you installed the MCP package separately, remove that package with the tool you used to install it.

​
Verify Removal

which bd
test ! -e .beads
bd hooks status 2>/dev/null || true
git config --get merge.beads.driver

​
Reinstall Later

To initialize beads again: 
bd init