beads Documentation

1. Project Overview & Quickstart (gastownhall/beads) Copy Chapter

File: README.md Copy Chapter

bd - Beads

Distributed graph issue tracker for AI agents, powered by Dolt.

Platforms: macOS, Linux, Windows, FreeBSD

Docs: https://beads.gascity.com/

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

flowchart LR
    create["bd createnew bead"] --> depgraph["dependencygraph"]
    depgraph --> ready["bd readyclaimable work"]
    ready --> claim["bd update --claimagent takes it"]
    claim --> close["bd closework done"]
    close -->|blockers released| ready
    depgraph <-->|"bd dolt push / pull"| remote[("other machinesand agents")]

⚡ Quick Start Copy Chapter

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Optional: refresh or install richer instructions for your agent
bd setup codex    # Codex CLI - installs skill, AGENTS.md guidance, and hooks
bd setup claude   # Claude Code - installs hooks/settings
bd setup factory  # Factory.ai Droid - creates/updates AGENTS.md

Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

bd init creates or updates AGENTS.md by default so agents can discover the beads workflow, and also installs project Claude/Codex integrations unless you pass --skip-agents or --stealth. Use bd setup --list to see supported integrations, including bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor, and more. See Agent and IDE setup.

Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun bd init/bd setup, or custom instruction files. In those cases, run bd onboard and paste the printed snippet into the file your agent reads.

If your agent is not covered by bd setup, add this minimal AGENTS.md section:

This project uses bd (beads) for issue tracking.

- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show `, `bd update  --claim`, and `bd close `.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.

🛠 Features Copy Chapter

• Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
• Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
• Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
• Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
• Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.
• Graph Links: relates-to, duplicates, supersedes, and replies-to for knowledge graphs.

📖 Essential Commands Copy Chapter

🔗 Hierarchy & Workflow Copy Chapter

Beads supports hierarchical IDs for epics:

• bd-a3f8 (Epic)
• bd-a3f8.1 (Task)
• bd-a3f8.1.1 (Sub-task)

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects. See Git-Free Usage below.

Contributor vs Maintainer: When working on open-source projects:

• Contributors (forked repos): Run bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.
• Maintainers (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.

📦 Installation Copy Chapter

brew install beads           # macOS / Linux (recommended)
npm install @beads/bd     # Node.js users

Other methods: install script | go install | from source | Windows | Arch AUR

Requirements: macOS, Linux, Windows, or FreeBSD. See docs/getting-started/installation.md for complete installation guide.

Upgrading? Replacing the binary is not always the whole story. Short
version: sync remote-backed databases with your current bd, back up with
bd export --all, upgrade the binary, then run bd info --whats-new,
bd hooks install, and bd version. If the upgrade crosses a schema
migration on a remote-backed database, exactly one designated clone runs
bd migrate and bd dolt push; other clones install the new binary
and run bd bootstrap. See the full
upgrade guide
or docs/getting-started/installation.md.

Security And Verification Copy Section

Before trusting any downloaded binary, verify its checksum against the release checksums.txt.

The install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.

On macOS, scripts/install.sh preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via BEADS_INSTALL_RESIGN_MACOS=1.

See docs/reference/antivirus.md for Windows AV false-positive guidance and verification workflow.

💾 Storage Modes Copy Chapter

Beads uses Dolt as its database. Two modes:

• Embedded (default) — bd init. Dolt runs in-process, data lives in
  .beads/embeddeddolt/, single writer. Recommended for most users.
• Server — bd init --server. Connects to an external dolt sql-server
  for multiple concurrent writers; data lives in .beads/dolt/.

Cross-machine sync uses bd dolt push / bd dolt pull against
refs/dolt/data on your git remote; .beads/issues.jsonl is an export for
viewers and interchange, not the source of truth or a backup. Back up and
migrate between modes with bd backup; reclaim space with bd prune /
bd purge.

Full detail — connection flags, sockets, maintenance, backup, and migration —
in the Dolt backend guide.

Schema Version Guard Copy Section

bd checks the database schema version at open time. If the database has been
migrated by a newer binary and an older binary tries to open it, bd exits
with an actionable error rather than issuing queries that fail with cryptic SQL
errors:

schema version mismatch: database is at v45, binary knows up to v42 (3 migrations ahead)

  Your bd binary is stale. Queries for dropped or renamed columns will fail
  with cryptic SQL errors (e.g. "column X could not be found in any table in scope").

  Rebuild from main:
    CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd

  Or install the latest release:
    CGO_ENABLED=0 go install -tags gms_pure_go github.com/steveyegge/beads/cmd/bd@latest

  To proceed despite the risk (some read commands may still work):
    BD_IGNORE_SCHEMA_SKEW=1 bd <command>
    bd --ignore-schema-skew <command>

When this fires: only when the database schema is ahead of the binary
(a newer binary migrated the database; this binary doesn't know those
migrations). Normal upgrades, where the binary migrates the database forward,
are unaffected.

Escape hatch: BD_IGNORE_SCHEMA_SKEW=1 (or --ignore-schema-skew) bypasses
the guard with a warning on stderr. Use this only if you know the forward
migrations are additive and safe for your specific workload.

🌐 Community Tools Copy Chapter

See docs/community-tools.md for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

See docs/related-projects.md for adjacent or complementary projects that solve different problems in the same neighborhood.

🚀 Git-Free Usage Copy Chapter

Beads works without git. The Dolt database is the storage backend — git
integration (hooks, repo discovery, identity) is optional.

# Initialize without git
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# All core commands work with zero git calls
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"

BEADS_DIR tells bd where to put the .beads/ database directory,
bypassing git repo discovery. --stealth sets no-git-ops: true in
config, disabling all git hook installation and git operations.

This is useful for:

• Non-git VCS (Sapling, Jujutsu, Piper) — no .git/ directory needed
• Monorepos — point BEADS_DIR at a specific subdirectory
• CI/CD — isolated task tracking without repo-level side effects
• Evaluation/testing — ephemeral databases in /tmp

📝 Documentation Copy Chapter

• Documentation site | Installing | Sync Concepts | Agent Workflow | Copilot CLI Setup | Copilot VS Code MCP | Articles | Sync Branch Mode | Troubleshooting | FAQ

File: docs/architecture/dolt.md Copy Chapter

title: Dolt Backend for Beads Copy Chapter

Beads uses Dolt as its storage backend. Dolt provides a version-controlled SQL database with cell-level merge, native branching, and two deployment modes.

Why Dolt? Copy Chapter

• Native version control — cell-level diffs and merges, not line-based
• Multi-writer support — server mode enables concurrent agents
• Built-in history — every write creates a Dolt commit
• Native branching — Dolt branches independent of git branches
• Single-binary option — embedded mode for solo users (no server needed)

Getting Started Copy Chapter

Install Dolt (Server Mode Only) Copy Section

Embedded mode includes everything in the bd binary; no separate Dolt install
is needed. Install the standalone dolt CLI only when you want to run server
mode or work directly with the database via dolt sql.

Install a specific version. Do not install releases/latest — see
Which Dolt version to install for the
version to use and why the pin exists.

DOLT_VERSION=2.2.0   # see "Which Dolt version to install" below

os=$(uname -s | tr '[:upper:]' '[:lower:]')
arch=$(uname -m | sed -e 's/^x86_64$/amd64/' -e 's/^aarch64$/arm64/')
curl -fsSL "https://github.com/dolthub/dolt/releases/download/v${DOLT_VERSION}/dolt-${os}-${arch}.tar.gz" \
  | tar -xz -C /tmp
sudo install -m 0755 "/tmp/dolt-${os}-${arch}/bin/dolt" /usr/local/bin/dolt

# Verify you got the version you asked for
dolt version

brew install dolt installs whatever version the Homebrew formula currently
points at, which is not pinned. If you install that way, check dolt version
against the pin below.

Which Dolt version to install Copy Section

Beads pins Dolt to 2.2.0. CI installs that same pin with
scripts/ci/install-dolt.sh, which records the per-version measurements and
the criterion for raising it; raise the pin here and in that script together.

This pin is about the standalone dolt CLI, which only server and
proxied-server mode use. Embedded mode is unaffected either way: it links the
Dolt engine into bd at the version in go.mod, currently the commit tagged
v2.2.0 upstream, no matter which dolt CLI is on your PATH.

Dolt 2.3.0 (released 2026-08-13) regressed CALL DOLT_RESET('--hard'). A few
percent of freshly created databases come up with that procedure unusable —
every call answers Error 1105 (HY000): context canceled, from any session
and any new connection, for the life of that server process. Nothing else
about the database looks wrong: SELECT 1, CALL DOLT_CLEAN(),
CALL DOLT_CHECKOUT('.'), CALL DOLT_COMMIT() and soft resets all work
normally, so the damage is invisible until something needs a hard reset.

Measured by creating fresh databases and immediately calling the procedure:

Versions after 2.3.1 have not been measured. Raise the pin only once a newer
release is confirmed clean by that same measurement — not because it is
newer.

Pin rather than track latest for a second, independent reason: the upstream
releases/latest URL resolves to the most recently created release, not the
highest version, so it can move backwards — v1.88.2 was created on
2026-08-17, after both v2.2.4 and v2.3.0.

If you are already running 2.3.x

Whether a database is affected is decided per database, when it is created —
two databases on the same server can differ — so check each one you care
about, against the server that is actually serving it:

# 1. The working set must be clean first: on a dirty working set a hard
#    reset discards uncommitted changes. If this returns any rows, commit
#    or clean up before step 3.
dolt sql -q "SELECT * FROM dolt_status"

# 2. Control — this must succeed. If it does not, you have a different
#    problem and step 3 proves nothing.
dolt sql -q "SELECT 1"

# 3. On a clean working set this is a no-op on a healthy database.
dolt sql -q "CALL DOLT_RESET('--hard')"

Step 2 succeeding while step 3 answers Error 1105 (HY000): context canceled
is the discriminating result — that database is affected. Both succeeding
means it is not.

The breakage lives in the running server process, not on disk, so restarting
dolt sql-server clears it — verified by re-running the check on an affected
database after a restart, with a healthy database on the same server as the
control. A restart re-rolls the dice for every database, though, so the
durable fix is to move to the pinned version.

This matters because bd flatten and the Dolt-history compaction in
bd admin compact both finish by hard-resetting main onto a temporary
branch, and the merge-settle path behind bd dolt pull / bd sync falls
back to a hard reset when it has to abandon a merge. See
Maintenance.

New Project Copy Section

# Embedded mode (single writer, no server — default for standalone)
bd init

# Server mode (multi-writer, e.g. orchestrator)
gt dolt start           # Start the Dolt server
bd init --server        # Initialize with server mode

Migrate from SQLite (Legacy) Copy Section

If upgrading from an older version that used SQLite:

Note: The bd migrate --to-dolt command was removed in v0.58.0.
For pre-0.50 installations with JSONL data, use the migration script:

bash Copy

scripts/migrate-jsonl-to-dolt.sh

See Troubleshooting if you encounter connection errors after migration.

Migration creates backups automatically. Your original SQLite database is preserved as beads.backup-pre-dolt-*.db.

Modes of Operation Copy Chapter

flowchart LR
    subgraph embedded["Embedded mode (default) — bd init"]
        bd1["bd processDolt runs in-process"] --> d1[(".beads/embeddeddolt/single writer, file-locked")]
    end
    subgraph server["Server mode — bd init --server"]
        bd2["bd (agent 1)"] --> srv["dolt sql-server"]
        bd3["bd (agent 2)"] --> srv
        srv --> d2[(".beads/dolt/concurrent writers")]
    end

Embedded Mode (Solo / Standalone) Copy Section

In-process Dolt engine — no separate server needed. This is the default for
standalone Beads users. The bd binary includes everything; just bd init and go.

• Single-writer (one process at a time)
• Data lives in .beads/embeddeddolt/ alongside your code
• Push to GitHub with bd dolt push — code and issues in one repo
• Zero ops: no server, no ports, no PID files

Server Mode (Multi-Writer / Orchestrator) Copy Section

Connects to a running dolt sql-server for multi-client access.

# Start the server (orchestrator)
gt dolt start

# Or manually
cd ~/.dolt-data/beads && dolt sql-server --port 3307

# Initialize in server mode
bd init --server

# Or switch via environment variable
export BEADS_DOLT_SERVER_MODE=1

# .beads/config.yaml (server mode settings)
dolt:
  mode: server
  host: 127.0.0.1
  port: 3307
  user: root

Configure the connection with flags or environment variables:

Unix domain sockets: Use --server-socket to connect via a Unix socket
instead of TCP. This avoids port conflicts between concurrent projects and is
useful in sandboxed environments (e.g., Claude Code) where file-level access
control is simpler than network allowlists. The Dolt server must be started
with dolt sql-server --socket . Auto-start is not supported in socket
mode.

Switch to server mode when you need:

• Multiple agents writing simultaneously
• Orchestrator multi-rig setups
• Federation with remote peers

Maintenance — `bd prune` and `bd purge` Copy Chapter

bd prune permanently deletes closed non-ephemeral beads to reclaim storage
and shrink auto-exports. bd purge does the same for ephemeral beads (wisps,
transient molecules). Both require --force to execute.

bd prune --older-than 30d              # Preview closed beads >30d old
bd prune --older-than 30d --force      # Delete them
bd prune --older-than 90d --dry-run    # Detailed preview with stats
bd purge --force                       # Delete all closed ephemeral beads

Reference-aware protection: bd prune automatically skips closed beads
whose ID appears in the description, notes, or comments of any open or
in-progress bead. This prevents accidental deletion of ADR, decision, and
verification beads that downstream work still cites. Use
--ignore-references to override when cleaning up known-stale references:

bd prune --older-than 90d --ignore-references --force

bd purge is unaffected — ephemeral beads' references are themselves
transient. For full Dolt storage reclaim after deleting many rows, follow
with bd flatten.

On Dolt 2.3.x, storage-reclaim operations can fail partway. bd flatten
and the Dolt-history compaction in bd admin compact both build a temporary
branch and then hard-reset main onto it, and the merge-settle path behind
bd dolt pull / bd sync falls back to a hard reset when it abandons a
merge. On an affected database that hard reset returns
Error 1105 (HY000): context canceled: bd flatten and bd admin compact
stop at that step, and an abandoned merge is left without its rollback. See
Which Dolt version to install for the check
and the fix.

Migrating Between Backends Copy Chapter

You can migrate data between embedded mode and server mode using bd backup.
Both directions preserve full Dolt commit history.

bd export is not a substitute for this flow. JSONL exports contain issue
records from the issues table for migration and interoperability; they do not
capture Dolt branches, full commit history, working-set state, or non-issue
tables. Use bd backup or a manual Dolt backup when you need a restorable
database backup.

Server → Embedded Copy Section

1. Create a backup from the server-mode project:

   bash Copy

   # In the server-mode project directory
   bd backup init /path/to/backup-dir
   bd backup sync

2. Create a new embedded-mode project and restore:

   bash Copy

   mkdir new-project && cd new-project
   bd init                  # creates an embedded-mode project by default
   bd backup restore --force /path/to/backup-dir

   --force overwrites the freshly-initialized database with the backup
   contents. The restore automatically:

   • Updates metadata.json to match the restored project identity
   • Registers the backup directory for future bd backup sync
   • Backfills the embedded migration tracker (schema_migrations)

3. Verify:

   bash Copy

   bd list
   bd backup status

Embedded → Server Copy Section

1. Create a backup from the embedded-mode project:

   bash Copy

   # In the embedded-mode project directory
   bd backup init /path/to/backup-dir
   bd backup sync

2. Create a new server-mode project and restore:

   bash Copy

   mkdir new-project && cd new-project
   bd init --server         # creates a server-mode project
   bd backup restore --force /path/to/backup-dir

3. Verify:

   bash Copy

   bd list
   bd backup status

Backup Commands Reference Copy Section

Notes Copy Section

• Data locations differ between modes: .beads/embeddeddolt/ (embedded) vs .beads/dolt/ (server)
• The backup directory is a full Dolt backup, not an issues.jsonl export — it can be on a local drive, NAS, or DoltHub
• You can also migrate via Dolt remotes (bd dolt push / bd dolt pull) if both projects share a remote

The sections below are the canonical backend migration reference.

Federation (Peer-to-Peer Sync) Copy Chapter

Federation lets independent Dolt-backed workspaces ("towns") sync issues
directly with each other via bd federation add-peer/sync/status,
without a central hub. Credentials are AES-256 encrypted and stored locally.

See Federation Setup Guide for the full setup guide, including
peer configuration, sovereignty tiers, sync/status/topology details, and
troubleshooting.

Dolt Remotes Copy Chapter

Use bd dolt remote add to configure remotes. This ensures the running Dolt SQL
server sees the remote immediately. Remotes added directly with the dolt CLI
are written to filesystem config and may not be visible to the server until
restart.

# DoltHub (public or private)
bd dolt remote add origin https://doltremoteapi.dolthub.com/org/beads

# S3
bd dolt remote add origin aws://[bucket]/path/to/repo

# GCS
bd dolt remote add origin gs://[bucket]/path/to/repo

# Git SSH (GitHub, GitLab, etc.)
bd dolt remote add origin git+ssh://[email protected]/org/repo.git

# Local file system
bd dolt remote add origin file:///path/to/remote

Push/Pull Copy Section

bd dolt push
bd dolt pull

bd dolt remote add registers the remote through the Dolt store API. SQL
remotes are the source of truth for bd dolt remote list, bd dolt push, and
bd dolt pull.

For git-protocol remotes, credentialed external-server remotes, and cloud
remotes whose credentials are only present in the current shell, bd dolt push
and bd dolt pull automatically materialize a matching local CLI remote before
using the dolt CLI transport. The CLI remote is a local transport mirror, not
a separate configuration source.

If you are upgrading from an older beads version and previously added remotes
with raw dolt remote add, re-register them with bd dolt remote add <name> so they are visible through SQL. bd doctor reports legacy CLI-only or
mismatched CLI remotes under Dolt Remote Migration.

Sharing a Git repo: Dolt stores data under refs/dolt/data, separate
from standard Git refs (refs/heads/, refs/tags/). You can safely point a
git+ssh:// remote at the same repository as your project source code. See
Dolt Git Remotes.

List/Remove Remotes Copy Section

bd dolt remote list            # Shows SQL-configured remotes
bd dolt remote remove origin   # Removes the remote

Contributor Onboarding (Clone Bootstrap) Copy Chapter

When someone clones a repository that uses Dolt backend:

1. Run bd bootstrap in the clone
2. If the git remote has refs/dolt/data (pushed via bd dolt push),
   bd bootstrap auto-detects it and clones the database from the remote
3. Work continues normally — all existing issues are available

No manual steps required beyond bd bootstrap. The auto-detect:

• Probes origin for refs/dolt/data
• Clones the Dolt database from the remote (instead of creating a fresh one)
• Configures the Dolt remote for future bd dolt push/pull

If sync.remote is set in .beads/config.yaml, that takes precedence
over auto-detection. Any Dolt-compatible remote URL is supported (DoltHub,
S3, GCS, file, or git). On brand-new projects, bd init auto-detects
git origin and persists it as sync.remote, so the first bd dolt push
publishes Dolt history to refs/dolt/data on the same git remote.

Verifying Bootstrap Worked Copy Section

bd list              # Should show issues
bd vc status         # Should show the current branch, no uncommitted changes

Troubleshooting Copy Chapter

Server Not Running Copy Section

Symptom: Connection refused errors when using server mode.

failed to create database: dial tcp 127.0.0.1:3307: connect: connection refused

Fix:

gt dolt start        # Orchestrator command
# Or
gt dolt status       # Check if running

Bootstrap Not Running Copy Section

Symptom: bd list shows nothing on fresh clone.

Check:

ls .beads/dolt/            # Should NOT exist (pre-bootstrap)
BD_DEBUG=1 bd list         # See bootstrap output

Force bootstrap:

rm -rf .beads/dolt         # Remove broken state
bd list                    # Re-triggers bootstrap

Database Corruption Copy Section

Symptom: Queries fail, inconsistent data.

Diagnosis:

bd doctor                  # Basic checks
bd doctor --deep           # Full validation
bd doctor --server         # Server mode checks (if applicable)

Recovery options:

1. Repair what's fixable:

   bash Copy

   bd doctor --fix

2. Rebuild from remote:

   bash Copy

   rm -rf .beads/dolt
   bd list                  # Re-triggers bootstrap

Already Committed `.beads/dolt/` to Git Copy Section

If you accidentally committed a Dolt data directory:

1. Update gitignore: bd doctor --fix
2. Remove it from git tracking: git rm --cached -r .beads/dolt/ (or .beads/embeddeddolt/)
3. Commit the removal: git commit -m "fix: remove accidentally committed dolt data"
4. To purge from history, use BFG Repo-Cleaner or git filter-repo

Lock Contention (Embedded Mode) Copy Section

Symptom: "database is locked" errors.

Embedded mode is single-writer (enforced via file lock). If you need concurrent
access, switch to server mode. See Migrating Between Backends.

Configuration Reference Copy Chapter

# .beads/config.yaml

# Dolt settings
dolt:
  # Auto-commit Dolt history after writes (default: on for embedded, off for server)
  auto-commit: on        # on | off

  # Storage mode (default: embedded)
  mode: embedded         # embedded | server
  # Server mode settings (only used when mode: server)
  host: 127.0.0.1
  port: 3307
  user: root
  # Password: env var or credentials file (see below)

  # Shared server mode (GH#2377): all projects share a single Dolt server
  # at ~/.beads/shared-server/. Each project uses its own database (prefix-based).
  # Eliminates port conflicts and reduces resource usage on multi-project machines.
  shared-server: false   # true | false

Environment Variables Copy Section

Credentials File Copy Section

For multi-server setups, you can store passwords in an INI-style credentials file
instead of juggling environment variables per project. Passwords are looked up by
[host:port] section, so each project automatically gets the right password based
on its configured server.

Password resolution order:

1. BEADS_DOLT_PASSWORD env var (highest priority, existing behavior)
2. Credentials file lookup by [host:port] (using the resolved runtime port)
3. Empty string (no password)

Port resolution note: The [host:port] used for credential lookup matches the
resolved runtime port (from the port file, env var, or config — in that priority
order), not necessarily the port stored in metadata.json. This matters when using
IAP tunnels: if your tunnel maps remote:3307 to localhost:3308, store your password
under [127.0.0.1:3308] and the credentials file will match the actual connection.

Default location: ~/.config/beads/credentials (Linux/macOS), %APPDATA%\beads\credentials (Windows)

Override location: Set BEADS_CREDENTIALS_FILE env var.

File format:

# ~/.config/beads/credentials
[127.0.0.1:3307]
password=localDevPassword

[beads.company.com:3307]
password=teamServerPassword

[10.0.1.50:3308]
password=officePassword

Permissions: On Linux/macOS, a warning is printed to stderr if the file is
readable by group or others (mirrors ssh behavior). Set permissions with:

chmod 600 ~/.config/beads/credentials

Dolt Version Control Copy Chapter

Dolt maintains its own version history, separate from Git:

# View an issue's version history across Dolt commits
bd history bd-42

# Show current branch and uncommitted changes
bd vc status

# Create manual checkpoint
bd vc commit -m "Checkpoint before refactor"

Auto-Commit Behavior Copy Section

In embedded mode (standalone default), each bd write command creates a Dolt commit:

bd create "New issue"    # Creates issue + Dolt commit

In server mode (orchestrator), auto-commit defaults to OFF because the server
manages its own transaction lifecycle. Firing DOLT_COMMIT after every write
under concurrent load causes 'database is read only' errors.

Override for batch operations (embedded) or explicit commits (server):

bd --dolt-auto-commit off create "Issue 1"
bd --dolt-auto-commit off create "Issue 2"
bd vc commit -m "Batch: created issues"

Server Management (Orchestrator) Copy Chapter

The orchestrator provides integrated Dolt server management:

gt dolt start            # Start server (background)
gt dolt stop             # Stop server
gt dolt status           # Show server status
gt dolt logs             # View server logs
gt dolt sql              # Open SQL shell

Server runs on port 3307 (avoids MySQL conflict on 3306).

Standalone-to-managed-city handoff Copy Section

When an existing standalone project is later added to a managed city or
orchestrator, avoid letting two Dolt servers become sources of truth for the
same beads database name. A common split-brain symptom is that .beads/dolt-server.port
points at the old standalone server while the shell environment points bd at
the managed server with BEADS_DOLT_PORT or BEADS_DOLT_SERVER_PORT.

Check before migrating:

bd doctor
bd dolt status

bd doctor warns when the runtime managed port differs from the local port
file. The warning is intentionally diagnostic only; do not delete the local port
file until the standalone store has been exported and imported into the managed
server.

Safe manual handoff:

# From the standalone project, without managed-city port overrides:
unset BEADS_DOLT_PORT BEADS_DOLT_SERVER_PORT
bd backup
bd export > /tmp/beads-standalone.jsonl
bd dolt stop

# Then enter the managed-city environment and import into its Dolt server:
bd import /tmp/beads-standalone.jsonl
bd doctor

After bd doctor shows one healthy store and the imported issue count is
correct, archive the old local Dolt data directory instead of deleting it
immediately. Keep the backup until the managed city has been pushed or otherwise
snapshotted.

Shared Server Mode Copy Section

On machines with multiple beads projects, each project normally starts its own Dolt server.
Shared server mode runs a single Dolt server at ~/.beads/shared-server/ that serves all projects:

# Enable for this project (config.yaml key)
bd config set dolt.shared-server true

# Or enable machine-wide via environment variable
export BEADS_DOLT_SHARED_SERVER=1

# Or enable during init
bd init --prefix myproject --shared-server

Benefits:

• No port conflicts between projects (single server on port 3308, avoids orchestrator on 3307)
• Reduced resource usage (one process instead of many)
• Automatic database isolation (each project uses its own database name)

How it works:

• Server state files (PID, port, lock, log) live in ~/.beads/shared-server/
• Dolt data directory: ~/.beads/shared-server/dolt/
• Each project's database is stored as a subdirectory (e.g., ~/.beads/shared-server/dolt/myproject/)
• The file lock mechanism ensures safe concurrent access from multiple projects
• Default port is 3308 (not 3307) to avoid conflict with the orchestrator. Override with BEADS_DOLT_SERVER_PORT or dolt.port in config.yaml

Important: Each project on a shared server must have a unique prefix (database name).
Two projects with the same prefix share the same database — if this happens accidentally,
the project identity check will detect the mismatch and refuse to connect, preventing
silent data corruption. Always use distinct prefixes when running bd init --shared-server.

# Check shared server status from any project
bd dolt status

# Show full configuration including shared mode
bd dolt show

Data Location (Orchestrator) Copy Section

<town-root>/.dolt-data/
├── hq/                  # Town beads (hq-*)
├── my-project/          # Project rig (mp-*)
├── beads/               # Beads rig (bd-*)
└── other-project/       # Other rig (op-*)

Central Dolt Server (macOS LaunchAgent) Copy Section

If you do not use the orchestrator but still want a single persistent Dolt
server for multiple projects on macOS, run a custom LaunchAgent instead of
spawning per-project embedded instances.

Why Not `brew services start dolt`?

After installing Dolt with brew install dolt, the natural next step is
brew services start dolt. However, the Homebrew formula runs
dolt sql-server without the --config flag, and Dolt does not auto-discover
config.yaml from its working directory. The config file must be passed
explicitly with --config <file>.

Setup with a Custom LaunchAgent

Install Dolt and initialize its data directory. Check the installed version
against the pin — Homebrew's formula is not
pinned:

brew install dolt
dolt version
cd /opt/homebrew/var/dolt && dolt init

Configure Dolt for port 3307:

# /opt/homebrew/var/dolt/config.yaml
log_level: info

listener:
  host: 127.0.0.1
  port: 3307
  max_connections: 100

behavior:
  autocommit: true

Create the LaunchAgent plist:

cat > ~/Library/LaunchAgents/com.local.dolt-server.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<dict>
    <key>Label</key>
    <string>com.local.dolt-server</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/dolt</string>
        <string>sql-server</string>
        <string>--config</string>
        <string>/opt/homebrew/var/dolt/config.yaml</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/opt/homebrew/var/dolt</string>
    <key>RunAtLoad</key>
    
    <key>KeepAlive</key>
    
    <key>StandardOutPath</key>
    <string>/opt/homebrew/var/log/dolt.log</string>
    <key>StandardErrorPath</key>
    <string>/opt/homebrew/var/log/dolt-error.log</string>
</dict>

EOF

Load and verify the service:

launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist
mysql -h 127.0.0.1 -P 3307 -u root -e "SELECT 1"

Point beads at the central server:

export BEADS_DOLT_SERVER_MODE=1
export BEADS_DOLT_SERVER_PORT=3307

Manage the service:

# Stop
launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist

# Restart
launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist
launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist

# Check logs
tail -f /opt/homebrew/var/log/dolt.log

Advanced Dolt Usage Copy Chapter

The dolt CLI lets you operate directly on the database for power-user
workflows. The data directory depends on your mode: .beads/embeddeddolt/
(embedded) or .beads/dolt/ (server).

Branching Copy Section

cd .beads/dolt   # or .beads/embeddeddolt for embedded mode
dolt branch feature-x
dolt checkout feature-x

Time Travel Copy Section

dolt log
dolt checkout <commit-hash>
dolt sql -q "SELECT * FROM issues"

Diff and Blame Copy Section

dolt diff main feature-x
dolt blame issues

Migration Cleanup Copy Chapter

After successful migration from SQLite, you may have backup files:

.beads/beads.backup-pre-dolt-20260122-213600.db
.beads/sqlite.backup-pre-dolt-20260123-192812.db

These are safe to delete once you've verified Dolt is working:

# Verify Dolt works
bd list
bd doctor

# Then clean up (after appropriate waiting period)
rm .beads/*.backup-*.db

Recommendation: Keep backups for at least a week before deleting.

See Also Copy Chapter

• Sync Concepts - The conceptual model behind cross-machine sync (Dolt source of truth, wire format, anti-patterns)
• Sync Setup Guide - Setting up sync across multiple computers
• Federation Setup Guide - Peer-to-peer federation setup
• Configuration - Full configuration reference
• Dependencies and Gates - Dependencies and gates
• Git Integration - Git worktrees and protected branches
• Troubleshooting - General troubleshooting

File: docs/architecture/index.md Copy Chapter

title: Architecture Overview Copy Chapter

This document explains how Beads' architecture works with Dolt as its storage backend: the storage layout, the data model, and the sync paths. For the concept model — beads, dependencies, ready work, molecules — see How Beads Works.

Architecture Copy Chapter

Beads uses Dolt as its sole storage backend -- a version-controlled SQL database that provides git-like semantics (branch, merge, diff, push, pull) natively at the database level.

By default, Dolt runs in embedded mode (in-process, no separate server). For multi-writer
setups (multiple agents, orchestrator), switch to server mode which connects to a
running dolt sql-server. See the Dolt Server Mode section below for details.

flowchart TD
    subgraph DOLT["🗄️ Dolt Database"]
        D[("embedded default: .beads/embeddeddolt/server mode: .beads/dolt/*Version-Controlled SQL*")]
    end

    subgraph REMOTE["🌐 Dolt Remotes"]
        R[("DoltHub / S3 / GCS*Sync & Backup*")]
    end

    D <-->|"bd dolt push/pull"| R

    U((User)) -->|"bd createbd update"| D
    D -->|"bd listbd show"| U

    style DOLT fill:#2d5a27,stroke:#4a9c3e,color:#fff
    style REMOTE fill:#1a4a6e,stroke:#3a8ac4,color:#fff

Source of Truth
Dolt is the source of truth. Every write auto-commits to Dolt history, providing full version control, branching, and merge capabilities at the database level.

Recovery is straightforward: pull from a Dolt remote with bd dolt pull, or restore from a Dolt-native backup with bd backup restore.

Why Dolt? Copy Section

• Version-controlled SQL: Full SQL queries with native version control
• Cell-level merge: Concurrent changes merge automatically at the field level
• Multi-writer: Server mode supports concurrent agents
• Native branching: Dolt branches independent of git branches
• Works offline: All queries run against local database
• Portable: bd export produces JSONL for migration and interoperability

Data Model Copy Chapter

The database stores five kinds of records: issues (the beads themselves), dependencies (typed edges such as blocks, parent-child, related, and discovered-from), labels, comments, and events (the audit trail). What each means — and how bd ready computes the claimable frontier from them — is covered in How Beads Works.

Issue IDs are content-derived hashes (bd-a1b2) so that concurrent writers never collide and no central ID coordination is needed. See Hash-based IDs for the design and COLLISION_MATH for the birthday-paradox analysis of hash length vs collision probability.

Issue Schema Copy Section

Core fields on every issue, as stored in Dolt and emitted in bd export JSONL. Optional fields are omitted when empty.

Issues also carry workflow-layer field groups, among others: scheduling (due_at, defer_until), claim leasing (lease_expires_at, heartbeat_at), gates (await_type, await_id, timeout), and molecule/wisp fields (ephemeral, mol_type, bonded_from).

Internal fields — content_hash (a SHA-256 of the issue's canonical content, used for change detection), source_repo, and id_prefix — never appear in exports.

The schema is stable by default: prefer the metadata field for integration-, orchestrator-, or team-specific data before proposing new first-class fields. See the Project Charter's schema boundary.

Data Flow Copy Chapter

Write Path Copy Section

User runs bd create
    → Dolt database updated
    → Auto-committed to Dolt history

Read Path Copy Section

User runs bd list
    → Dolt SQL query
    → Results returned immediately

Sync Path Copy Section

User runs bd dolt push
    → Commits pushed to Dolt remote

User runs bd dolt pull
    → Remote commits fetched and merged

Dolt remotes can live on DoltHub, S3, GCS, a filesystem path, or your existing git remote — issue history rides under refs/dolt/data, separate from code branches. See Sync Concepts for the wire format and setup.

Cross-repo setups can also exchange beads peer-to-peer via federation. Ephemeral wisps are excluded from federation push by default, so execution traces never enter shared history.

Multi-Machine Sync Considerations Copy Section

When working across multiple machines or clones:

1. Always sync before switching machines

   bash Copy

   bd dolt push  # Push changes before leaving

2. Pull before creating new issues

   bash Copy

   bd dolt pull  # Pull changes first on new machine
   bd create "New issue"

3. Avoid parallel edits - If two machines create issues simultaneously without syncing, Dolt's cell-level merge handles most conflicts automatically

See Sync Failures Recovery for data loss prevention in multi-machine workflows (Pattern A5/C3).

Dolt Server Mode Copy Chapter

The Dolt server handles background synchronization and database operations:

• Manages the Dolt database backend
• Handles auto-commit for change tracking
• Provides concurrent access for multiple agents
• Runtime files live directly in .beads/: dolt-server.pid, dolt-server.log, and dolt-server.port

An opt-in shared server mode runs a single Dolt server at ~/.beads/shared-server/ for all projects, enabled with dolt.shared-server: true in config.yaml or BEADS_DOLT_SHARED_SERVER=1 — see Dolt Backend.

Embedded Mode (No Server) Copy Section

Embedded mode is the default (bd init with no flags): Dolt runs in-process, single-writer, with data at .beads/embeddeddolt/ — no server process and no separate Dolt install. Server mode is opt-in via bd init --server; the choice is persisted in .beads/metadata.json.

bd create "CI-generated issue"
bd dolt push

Beyond solo use, embedded mode is a natural fit for:

• CI/CD pipelines (Jenkins, GitHub Actions)
• Docker containers
• Ephemeral environments
• Scripts that should not leave background processes

Multi-Clone Scenarios Copy Section

.beads/
├── embeddeddolt/     # Dolt database (embedded mode, default) — gitignored
├── dolt/             # Dolt database (server mode) — gitignored
├── dolt-server.pid   # Server-mode runtime files (.pid, .log, .port) — gitignored
├── issues.jsonl      # Passive JSONL export for viewers and interchange
├── metadata.json     # Backend config — tracked in git
└── config.yaml       # Project config (optional) — tracked in git

bd dolt stop                 # Stop Dolt server (prevents race conditions)
git worktree prune           # Clean orphaned worktrees
bd dolt pull                 # Pull from Dolt remote
bd dolt start                # Restart server

bd admin [flags]

bd admin cleanup [flags]

--cascade          Recursively delete all dependent issues
      --dry-run          Preview what would be deleted without making changes
      --ephemeral        Only delete closed wisps (transient molecules)
  -f, --force            Actually delete (without this flag, shows error)
      --older-than int   Only delete issues closed more than N days ago (0 = all closed issues)

bd admin compact [flags]

--actor string     Actor name for audit trail (default "agent")
      --all              Process all candidates
      --analyze          Analyze mode: export candidates for agent review
      --apply            Apply mode: accept agent-provided summary
      --auto             Auto mode: AI-powered compaction (legacy)
      --batch-size int   Issues per batch (default 10)
      --dolt             Dolt mode: run Dolt garbage collection on .beads/dolt
      --dry-run          Preview without compacting
      --force            Force compact (bypass checks, requires --id)
      --id string        Compact specific issue
      --json             Output JSON format
      --limit int        Limit number of candidates (0 = no limit)
      --stats            Show compaction statistics
      --summary string   Path to summary file (use '-' for stdin)
      --tier int         Compaction tier (only tier 1 is implemented) (default 1)
      --workers int      Parallel workers (default 5)

bd admin reset [flags]

--force   Actually perform the reset (required)

bd ado [flags]

bd ado projects [flags]

bd ado pull [refs...] [flags]

--dry-run   Preview pull without making changes

bd ado push [bead-ids...] [flags]

--dry-run   Preview push without making changes

bd ado status [flags]

bd ado sync [flags]

--area-path string        Filter to ADO area path (e.g., "Project\Team")
      --bootstrap-match         Enable heuristic matching for first sync
      --dry-run                 Show what would be synced without making changes
      --issues string           Comma-separated bead IDs to sync selectively (e.g., bd-abc,bd-def). Mutually exclusive with --parent.
      --iteration-path string   Filter to ADO iteration path (e.g., "Project\Sprint 1")
      --no-create               Never create new items in either direction (pull or push)
      --parent string           Limit push to this bead and its descendants (push only). Mutually exclusive with --issues.
      --prefer-ado              On conflict, use Azure DevOps version
      --prefer-local            On conflict, keep local beads version
      --prefer-newer            On conflict, use most recent version (default)
      --project strings         Project name(s) to sync (overrides configured project/projects)
      --pull-only               Only pull issues from Azure DevOps
      --push-only               Only push issues to Azure DevOps
      --reconcile               Force reconciliation scan for deleted items
      --states string           Filter to ADO states, comma-separated (e.g., "New,Active,Resolved")
      --types string            Filter to work item types, comma-separated (e.g., "Bug,Task,User Story")

bd assign  <name> [flags]

bd audit [flags]

bd audit label <entry-id> [flags]

--label string    Label value (e.g. "good" or "bad")
      --reason string   Reason for label

bd audit record [flags]

--error string       Error string (llm_call/tool_call)
      --exit-code int      Exit code (tool_call) (default -1)
      --issue-id string    Related issue id (bd-...)
      --kind string        Entry kind (e.g. llm_call, tool_call, label)
      --model string       Model name (llm_call)
      --prompt string      Prompt text (llm_call)
      --response string    Response text (llm_call)
      --stdin              Read a JSON object from stdin (must match audit.Entry schema)
      --tool-name string   Tool name (tool_call)

bd backup [flags]

bd backup init  [flags]

bd backup remove [flags]

bd backup restore [path] [flags]

--force   Overwrite existing database with backup contents

bd backup status [flags]

bd backup sync [flags]

bd batch [flags]

--dry-run          Parse input and echo commands without executing
  -f, --file string      Read commands from file instead of stdin
  -m, --message string   DOLT_COMMIT message (default: 'bd: batch N ops by <actor>')

npx skills add https://mintlify.com/docs

npm i mint

mint dev