Summary

bd 0.56 removed the embedded Dolt mode (no more CGO) and now requires a running dolt sql-server process for all Dolt-backed projects. While this may simplify the bd codebase and prepare for future multi-user scenarios, it is a significant regression for standalone and desktop use cases.

What worked well with embedded Dolt (bd 0.50–0.55)

• Zero server management — Dolt was embedded, no process to start/stop/monitor
• Native file watcher — instant change detection with zero CPU when idle (OS-level inotify/FSEvents on .beads/ files)
• No network dependency — no port to occupy, no MySQL protocol overhead
• Simple setup — bd init was all that was needed

What broke with server mode (bd 0.56+)

1. Change detection is fundamentally broken

The native file watcher (inotify/FSEvents) can no longer detect data changes because data now lives inside a MySQL server process, not in files that change on disk. Applications must fall back to continuous polling (bd list every 1–5 seconds), which:

• Consumes significantly more CPU than a file watcher (0 CPU → constant bd list calls)
• Introduces detection latency (1–5s vs instant)
• Requires version-gated workarounds (bd_check_changed must always return true in server mode)

2. Server lifecycle management

Applications must now manage the dolt sql-server process: start it, health-check it, handle crashes, manage the port. This is a significant complexity increase for what was previously a transparent embedded database.

3. Migration path removed

bd import and bd migrate --to-dolt were removed. Migrating existing SQLite/JSONL projects to Dolt now requires a manual multi-step process: dolt init → start server → bd init → bd create --id for each issue. This is fragile and slow compared to the previous single-command migration.

4. No actual multi-user benefit today

The server mode architecture is presented as enabling shared/multi-user access. However, in practice today:

• dolt sql-server runs locally on a single machine
• It serves one database from a local .beads/dolt/ directory
• There is no remote access configuration, no authentication, no multi-tenant support
• Each project still requires its own server instance

In other words: it is still single-user local, but with a MySQL server in the middle. The embedded mode was removed to simplify the codebase (no CGO), not to deliver a working multi-user feature.

5. Multiple projects cannot run simultaneously

With embedded Dolt, switching between projects was instant — each project had its own self-contained .beads/ directory, no external process needed. With server mode, each dolt sql-server instance serves a single database. Running multiple projects in parallel (e.g., a dashboard aggregating issues across projects, or simply having two project windows open) requires multiple server instances — one per project. While bd does support configuring the port via --server-port, the fundamental issue remains: applications must manage multiple server processes, coordinate ports, and handle lifecycle for each one. This is significant complexity that didn't exist with the embedded mode.

Suggestion

Consider one of the following:

1. Restore an embedded mode (even if opt-in) for standalone/desktop users who don't need server capabilities. This was the most efficient and simplest architecture for single-user use.

2. Provide a lightweight change-notification mechanism in server mode — for example, a simple IPC signal or SSE endpoint from dolt sql-server that notifies clients when data changes, so applications don't need to poll.

3. At minimum, document the trade-offs so users building applications on top of bd understand that server mode requires polling-based change detection and server lifecycle management.

Environment

• bd 0.56.1
• macOS (Tauri desktop application using bd as the backend)
• ~250 issues per project

We may very well be missing something about the intended architecture and future direction. If so, we'd love to hear about it — any clarification would be greatly appreciated. Thanks in advance for taking the time to respond!