cd /news/developer-tools/uninstall-beads · home › topics › developer-tools › article
[ARTICLE · art-9172] src=gist.github.com ↗ pub= topic=developer-tools verified=true sentiment=· neutral

uninstall beads

The article describes an uninstall script for the Beads (bd) tool that performs a comprehensive cleanup of all its traces from a system. By default, the script runs in dry-run mode to show what would be deleted without making changes, and the `--apply` flag must be used to actually perform the cleanup. The script removes Beads-related files from per-repository directories, the user's home directory, and system binary locations, with options to skip home or binary cleanup and target specific directories.

read2 min views17 publishedJan 3, 2026

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

Usage #

./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 #

./scripts/uninstall.sh

./scripts/uninstall.sh --apply

./scripts/uninstall.sh --root ~/myproject --skip-home --skip-binary --apply

./scripts/uninstall.sh --root ~/project1 --root ~/project2 --apply
source & further reading
gist.github.com — original article OpenCode AI config to deny read access to .env, node_modules, build artifacts, cache dirs and ask before bash execution Download CapCut Pro 2026 for Mac For Agentic Coding
── more in #developer-tools 4 stories · sorted by recency
── more on @beads 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/uninstall-beads] indexed:0 read:2min 2026-01-03 · —