gastownhall__beads/docs/reference/advanced.md

title, description

title	description
Advanced Features	Advanced bd operations for renaming issues and prefixes, merging duplicates, compaction, database redirects, and performance tuning.

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 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. This is the human-facing history — for the machine-facing feed of committed mutations, see the Events Journal. 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