# uninstall beads

> Source: <https://gist.github.com/banteg/1a539b88b3c8945cd71e4b958f319d8d>
> Published: 2026-01-03 17:45:57+00:00

# Beads Uninstall Script

A comprehensive uninstall/cleanup script for Beads (`bd`) that removes all traces of the tool from a system.

## Usage

```bash
./scripts/uninstall.sh            # dry-run (scan $HOME)
./scripts/uninstall.sh --apply    # perform cleanup
./scripts/uninstall.sh --root DIR --apply
./scripts/uninstall.sh --skip-home --skip-binary
```

## Key Features

- **Dry-run by default** - Shows what would be deleted without making changes. Use `--apply` to actually perform cleanup.

## What It Cleans Up

### Per-Repository Cleanup

- Stops any running bd daemon
- Removes `.beads/` and `.beads-hooks/` directories
- Cleans Beads integration from `AGENTS.md` (removes marked sections)
- Removes bd hooks from `.claude/settings.local.json` and `.gemini/settings.json`
- Deletes `.cursor/rules/beads.mdc`, `.aider.conf.yml`, `.aider/BEADS.md`
- Cleans git hooks that contain bd-related code, restoring backups if they exist
- Removes `merge=beads` from `.gitattributes`
- Cleans Beads entries from `.git/info/exclude`
- Unsets `core.hooksPath` if it points to `.beads-hooks`
- Removes merge driver config (`merge.beads.*`)

### Home Directory Cleanup

- Removes `~/.beads/` and `~/.config/bd/`
- Cleans hooks from `~/.claude/settings.json` and `~/.gemini/settings.json`
- Removes Beads entries from global gitignore
- Removes `~/.beads-planning/` if it has a `.beads` subdirectory

### Binary Cleanup

- Removes `bd` binaries from common locations (`/usr/local/bin`, `/opt/homebrew/bin`, `~/.local/bin`, `~/go/bin`)
- Runs `brew uninstall bd` if installed via Homebrew
- Runs `npm uninstall -g @beads/bd` if installed via npm

## Options

| Flag | Description |
|------|-------------|
| `--apply` | Actually perform deletions (otherwise dry-run) |
| `--root DIR` | Scan a specific directory instead of `$HOME` (repeatable) |
| `--skip-home` | Don't touch home-level files |
| `--skip-binary` | Don't remove the bd binary |
| `-h, --help` | Show help |

## Examples

```bash
# See what would be cleaned (dry-run)
./scripts/uninstall.sh

# Actually clean everything
./scripts/uninstall.sh --apply

# Only clean a specific project directory
./scripts/uninstall.sh --root ~/myproject --skip-home --skip-binary --apply

# Clean multiple directories
./scripts/uninstall.sh --root ~/project1 --root ~/project2 --apply
```