docs/ADVANCED.md
This guide covers advanced features for power users and specific use cases.
Change the issue prefix for all issues in your database. This is useful if your prefix is too long or you want to standardize naming.
# Preview changes without applying
bd rename-prefix kw- --dry-run
# Rename from current prefix to new prefix
bd rename-prefix kw-
# JSON output
bd rename-prefix kw- --json
The rename operation:
knowledge-work-1 → kw-1)Prefix validation rules:
Example workflow:
# You have issues like knowledge-work-1, knowledge-work-2, etc.
bd list # Shows knowledge-work-* issues
# Preview the rename
bd rename-prefix kw- --dry-run
# Apply the rename
bd rename-prefix kw-
# Now you have kw-1, kw-2, etc.
bd list # Shows kw-* issues
Find issues with identical content using automated duplicate detection:
# Find all content duplicates in the database
bd duplicates
# Show duplicates in JSON format
bd duplicates --json
# Automatically merge all duplicates
bd duplicates --auto-merge
# Preview what would be merged
bd duplicates --dry-run
# Detect duplicates after initializing from JSONL
bd init --from-jsonl # then: bd duplicates
How it works:
Example output:
🔍 Found 3 duplicate group(s):
━━ Group 1: Fix authentication bug
→ bd-10 (open, P1, 5 references)
bd-42 (open, P1, 0 references)
Suggested: bd merge bd-42 --into bd-10
💡 Run with --auto-merge to execute all suggested merges
AI Agent Workflow:
bd duplicates to check for duplicates--dedupe-after to detect duplicates after collision resolution--auto-merge to automatically consolidate duplicates--dry-run to preview merges before executingConsolidate duplicate issues into a single issue while preserving dependencies and references:
# Merge bd-42 and bd-43 into bd-41
bd merge bd-42 bd-43 --into bd-41
# Merge multiple duplicates at once
bd merge bd-10 bd-11 bd-12 --into bd-10
# Preview merge without making changes
bd merge bd-42 bd-43 --into bd-41 --dry-run
# JSON output
bd merge bd-42 bd-43 --into bd-41 --json
What the merge command does:
Merged into bd-XExample workflow:
# You discover bd-42 and bd-43 are duplicates of bd-41
bd show bd-41 bd-42 bd-43
# Preview the merge
bd merge bd-42 bd-43 --into bd-41 --dry-run
# Execute the merge
bd merge bd-42 bd-43 --into bd-41
# ✓ Merged 2 issue(s) into bd-41
# Verify the result
bd show bd-41 # Now has dependencies from bd-42 and bd-43
bd dep tree bd-41 # Shows unified dependency tree
Important notes:
closed)When agents discover duplicate issues, they should:
bd list --json | grep "similar text"bd show bd-41 bd-42 --jsonbd merge bd-42 --into bd-41bd create "Found duplicates during bd-X" --deps discovered-from:bd-XGit worktrees work with bd. Each worktree can have its own .beads directory, or worktrees can share a database via redirects (see Database Redirects).
With Dolt backend: Each worktree operates directly on the database — no special coordination needed. Use bd dolt push to sync with Dolt remotes when ready.
With Dolt server mode: Multiple worktrees can connect to the same Dolt server for concurrent access without conflicts.
Multiple git clones can share a single beads database using redirect files. This is useful for:
Create a .beads/redirect file pointing to the shared database location:
# In your secondary clone
mkdir -p .beads
echo "../main-clone/.beads" > .beads/redirect
# Or use an absolute path
echo "/path/to/shared/.beads" > .beads/redirect
The redirect file should contain a single path (relative or absolute) to the target .beads directory.
Example setup:
repo/
├── main-clone/
│ └── .beads/
│ └── beads.db ← Actual database
├── agent-1/
│ └── .beads/
│ └── redirect ← Points to ../main-clone/.beads
└── agent-2/
└── .beads/
└── redirect ← Points to ../main-clone/.beads
Use bd where to see which database is actually being used:
bd where
# /path/to/main-clone/.beads
# (via redirect from /path/to/agent-1/.beads)
# prefix: bd
# database: /path/to/main-clone/.beads/beads.db
bd where --json
# {"path": "...", "redirected_from": "...", "prefix": "bd", "database_path": "..."}
Good use cases:
Not recommended for:
.beads directory)With hash-based IDs (v0.20.1+), ID collisions are eliminated. Different issues get different hash IDs, so concurrent creation doesn't cause conflicts.
Dolt handles merge conflicts natively with cell-level merge. When concurrent changes affect the same issue field, Dolt detects and resolves conflicts automatically where possible:
# Pull with automatic merge
bd dolt pull
# Check for unresolved conflicts
bd vc conflicts
# Resolve if needed
bd vc resolve
When you encounter the same ID during a Dolt pull or database bootstrap, it's an update operation, not a collision:
Bootstrapping from an export:
# Export from one database
bd export -o data.jsonl
# Bootstrap a new database from the export
bd init --from-jsonl
Git hooks can be used to integrate beads with your git workflow:
bd hooks install
This installs hooks for beads data consistency checks during git operations.
See DOLT.md for details on how the Dolt backend handles sync natively.
Note: Custom table extensions via
UnderlyingDB()are a SQLite-only pattern. With the Dolt backend, build standalone integration tools using bd's CLI with--jsonflags, or usebd queryfor direct SQL access. See EXTENDING.md for details.
For SQLite-backend users, you can extend bd with your own tables and queries:
See EXTENDING.md for complete documentation.
Understanding the role of each component:
bd commandbd dolt start) for concurrent clients.beads directory based on working directoryKey principle: All heavy lifting (dependency graphs, collision resolution, merge logic) happens in the core bd storage layer. The RPC and MCP layers are thin adapters.