Skip to main content
Advanced beads functionality.

​
Issue Rename

Rename issues while preserving references: 
bd rename bd-42 bd-new-id
bd rename bd-42 bd-new-id --dry-run  # Preview
Updates:
  • All dependencies pointing to old ID
  • All references in other issues
  • Comments and descriptions

​
Prefix Rename

Change the issue prefix for every issue in the database — for example, shortening knowledge-work- to kw-: 
bd rename-prefix kw- --dry-run  # Preview without applying
bd rename-prefix kw-            # Every knowledge-work-* ID becomes kw-*
The rename updates all issue IDs and all text references across all fields. Prefixes are at most 8 characters of lowercase letters, numbers, and hyphens, must start with a letter, and must end with a hyphen. If a corrupted database contains issues with multiple prefixes, bd rename-prefix <prefix> --repair consolidates them. See bd rename-prefix.

​
Duplicate Detection and Merge

Find issues with identical content (title, description, design, acceptance criteria) and consolidate them: 
bd duplicates              # Report duplicate groups with suggested actions
bd duplicates --dry-run    # Preview what --auto-merge would do
bd duplicates --auto-merge # Merge every duplicate group
Issues are grouped by content hash, and only when their statuses match (open with open, closed with closed). The merge target is the most-referenced issue in each group, falling back to the smallest ID. For each group, --auto-merge:
  • Re-parents children of the duplicates onto the target
  • Closes the duplicates with reason Duplicate of <target>
  • Links each duplicate to the target with a related dependency
To mark a single known duplicate manually: 
bd duplicate bd-42 --of bd-41  # Close bd-42 as a duplicate of bd-41
Closing is permanent, but Dolt version history preserves the original state. Verify results with bd show bd-41 and bd dep tree bd-41.

​
Database Compaction

Reduce database size by compacting old issues: 
# View compaction statistics
bd admin compact --stats

# Preview candidates (30+ days closed)
bd admin compact --analyze --json

# Apply agent-generated summary
bd admin compact --apply --id bd-42 --summary summary.txt

# Immediate deletion (CAUTION!)
bd admin cleanup --force
When to compact:
  • Database > 10MB with old closed issues
  • After major milestones
  • Before archiving project phase

​
Restore from History

Recover the pre-compaction content of a compacted issue: 
bd restore bd-42          # Display the archived original content
bd restore bd-42 --apply  # Write the original content back into the issue
If no archived snapshot exists, bd restore falls back to a best-effort reconstruction from Dolt version history, which can only be displayed, not applied.

​
Database Inspection

bd sql requires Dolt server mode (bd dolt start, see Performance Tuning below); it is not available against the default embedded-mode database. 
# Schema info
bd info --schema --json

# Raw database query (server mode only)
bd sql "SELECT * FROM issues LIMIT 5"

​
Database Redirects

Multiple git clones can share one beads database — useful when several agents or checkout directories work the same issues. Create a .beads/redirect file in the secondary clone containing a single path (relative or absolute) to the target .beads directory: 
# In the secondary clone
mkdir -p .beads
echo "../main-clone/.beads" > .beads/redirect
Check which database is actually in use: 
bd where          # Active .beads location, including redirect info
bd where --json
Limitations and guidance:
  • Redirect chains are not followed — only a single level works, so a redirect must point directly at the real .beads directory.
  • The target directory must exist and contain a valid database.
  • Give separate projects and long-lived forks their own databases instead of redirects.
  • Git worktrees don’t need redirects — linked worktrees discover the repository’s .beads workspace automatically. See Git Worktrees.

​
Extensible Database

For Dolt-backed projects, keep extension state outside the beads database and connect it to beads through stable CLI surfaces: 
# Query issues for integration workflows
bd list --json
bd query "status=open AND priority<=2" --json

# Run direct SQL for inspection (server mode only)
bd sql "SELECT id, title, status FROM issues LIMIT 5"
Custom tables through direct storage access are a legacy SQLite-only pattern. See the bd-example-extension-go example only if you are maintaining a SQLite-backed extension.

​
Audit Data

Beads records issue lifecycle events in the database for audit and recovery workflows. There is no standalone bd events command; inspect current issue state through JSON output, or query the audit tables directly when needed: 
# Current issue state
bd show bd-a1b2 --json

# Recent stored events for one issue (server mode only)
bd sql "SELECT event_type, actor, created_at FROM events WHERE issue_id = 'bd-a1b2' ORDER BY created_at DESC LIMIT 20"
Events:
  • issue.created
  • issue.updated
  • issue.closed
  • dependency.added
  • sync.completed

​
Batch Operations

​
Create Multiple

Bootstrap a new database from a JSONL export: 
# In the source project
bd export -o issues.jsonl

# In the new project: place the export at .beads/issues.jsonl
# (or the configured import.path), then initialize from it
bd init --from-jsonl
Importing records whose IDs already exist updates those issues in place — hash IDs are content-derived and stable, so a matching ID is an update, not a collision.

​
Update Multiple

bd list --status open --priority 4 --json | \
  jq -r '.[].id' | \
  xargs -I {} bd update {} --priority 3

​
Close Multiple

bd list --label "sprint-1" --status open --json | \
  jq -r '.[].id' | \
  xargs -I {} bd close {} --reason "Sprint complete"

​
Integration Access

Use the CLI as the supported integration boundary: 
# Machine-readable issue data
bd show bd-a1b2 --json

# Ready-work queue for automation
bd ready --json

# Direct SQL inspection against the active Dolt database (server mode only)
bd sql "SELECT id, priority, status FROM issues WHERE status != 'closed'"
The storage packages under internal/ are not a public Go API. The MCP server is a stateless adapter over the same boundary: it translates MCP calls into bd CLI invocations and routes each call to the correct .beads workspace based on the working directory. It never caches or stores issue data itself.

​
Performance Tuning

​
Large Databases

# Summarize old closed issues (see Database Compaction above)
bd admin compact --stats

# Reclaim disk space with Dolt garbage collection
bd admin compact --dolt

# Squash Dolt commits older than 30 days (preview first)
bd compact --dry-run
bd compact --force

​
Many Concurrent Agents

Beads uses Dolt server mode to handle concurrent access from multiple agents. The server manages transaction isolation automatically. 
# Start the Dolt server
bd dolt start

# Check server health
bd doctor

​
CI/CD Optimization

In CI/CD environments, beads uses embedded mode by default (no server required): 
# Just run commands directly — no special flags needed
bd list