beads 1.0.1 flipped the export.auto default to on, so old projects silently start exporting issues.jsonl after upgrade. To opt back out, run:

bd config set export.auto false

New projects get prompted during init, only existing projects will get this nice surprise.

If you’re using dolt’s git export instead, commit the config change and delete the issues.jsonl file.

When dolt’s journal is corrupted, dolt fsck --revive-journal-with-data-loss will truncate it back to the last valid record.

I found this error message when starting dolt up after upgrading the server: invalid journal record at offset 5831169: invalid journal record: CRC checksum does not match.

To recover, go to your dolt DB:

cd ~/.beads/shared-server/dolt/<db> \
  && dolt fsck --revive-journal-with-data-loss

It backs up the journal, truncates to the point it failed, and makes it possible to start the server again. In my case the db came back up with data loss. I did a bd dolt pull and it pulled in what I had pushed most recently, so nothing major was lost.

I’m guessing this happened because installing beads 1.0 also upgraded dolt. If you’re upgrading, it’s worth making sure you’ve done bd vc commit && bd dolt push in all repos beforehand. That means configuring a git remote first.

dolt’s shared server won’t pull until all databases on the server have committed changes, not just the beads project you’re pulling.

You’ll get Error 1105 (HY000): cannot merge with uncommitted changes and it’s confusing when the beads project you’re working in has autocommit on. The uncommitted changes are in a different project that’s also using the shared server.

The fix is to go through your other projects and commit their changes (or enable autocommit by adding dolt.auto-commit: "on" to .beads/config.yml). To find which databases have uncommitted changes:

query=$(bd sql "SHOW DATABASES" 2>/dev/null \
  | grep -v -E "^(Database|--|\(|dolt|information_schema|mysql)" \
  | while read db; do
      echo "SELECT '$db' as db, table_name, status FROM \`$db\`.dolt_status WHERE table_name != 'config'"
    done \
  | paste -sd'|' - | sed 's/|/ UNION ALL /g')
bd sql "$query"

For each project that shows up, go in and run bd vc commit -m 'Snapshot', and then you can pull again.

We’re ignoring changes to the config table because they don’t seem to matter for pulling.

You can manually clone a dolt database from its git remote when bd bootstrap or bd init won’t cooperate.

1. bd dolt stop: stop the server in the git repo you’re restoring so you can operate on its database
2. cd ~/.beads/shared-server/dolt: go to the shared dolt server (it’s .beads/dolt/beads otherwise, I think)
3. rm -rf <prefix>: remove the DB if it exists already
4. dolt clone git+ssh://[email protected]/user/repo.git <prefix>: clone it to your prefix
5. cd - && bd ready: see if you can see the listing

I don’t know why my local just refused with bd bootstrap but this allowed me to fix it manually.

To switch beads from a per-project dolt server to the shared server, do a backup, configure shared-server, and restore.

I was running in “a server per repo” mode and it’s just unnecessary, they clash in annoying ways when switching repos, and once I understood how beads store data in git I embraced dolt and the shared server. I had hesitated because I had somehow connected it with DoltHub, and that’s optional for using beads.

1. bd backup: make sure you have your local database available for restore
2. bd dolt stop: so we don’t conflict on anything
3. bd dolt set shared-server true: to configure this project to use the shared server
4. bd restore: to restore the db

For most of my projects this just worked, but in some cases I had to reset the dolt configuration for the repo.

I tweak the default beads setup to work with Claude instead of the generic agent integration.

As of beads 0.62.0, this is what I run:

# configure agents later
bd init --shared-server --skip-agents

# setup a CLAUDE.md and configure claude hooks to re-prime beads
bd setup claude --project
bd hooks install

# move local settings to project settings
mv .claude/settings{.local,}.json

# amend init commit so .beads-credential-key never enters git
git add .claude/settings.json CLAUDE.md
git commit --amend -CHEAD

# share beads data alongside your git repo
bd dolt remote add origin git+ssh://[email protected]/you/repo.git
echo -e 'sync:\n  git-remote: git+ssh://[email protected]/you/repo.git' >> .beads/config.yaml

The key thing is --skip-agents and then bd setup claude --project instead, so you get Claude-specific hooks rather than the generic agent integration. The dolt remote lines are so your beads data gets stored alongside your git repo.