Does beads store issues in git? Not on your branches any more

Ask a search engine whether beads keeps its issues in git and it says yes: a .beads/issues.jsonl file, committed with your code, merged by a custom driver. The pages it answers from are package docs for beads 0.9 to 0.17.

That was true once. It is not how bd 1.3.1 works, the current release. Beads now keeps issues in Dolt, a version-controlled SQL database, and its changelog has called Dolt the primary datastore since 1.0.5. The JSONL file is an export, off by default, and the README says it is "not the source of truth or a backup".

The data still travels through your git remote. It just does not travel on your branches. We ran five cases with plain git and the release binary to see what that changes in practice.

Where the issues are now

Three places, and only one of them is a file git tracks.

bd init also makes a commit of its own: 19 files in our run, among them an AGENTS.md, a CLAUDE.md, a .claude/settings.json, config for Cursor and Codex, and five git hooks, with core.hooksPath pointed at them. Those are in git. The issues are not.

Five cases

Each case is a fresh repository. Cases 3 to 5 use two clones, A and B, of one bare remote, standing in for two agents on two machines. They sync the way the docs say to: bd dolt push and bd dolt pull.

Cases 3 and 5 are the ones a git-file tracker gets wrong. Two agents touching one task, or both adding tasks, is where a Markdown or JSONL file in git conflicts. Beads merged both with no help. The hash IDs and the field-level merge do what the README claims.

The same field, changed twice

Case 4 is the one worth reading slowly.

Two agents disagree about one value. One says the task is in progress, the other closes it. Beads does not stop. It keeps whichever edit has the later updated_at and moves the close fields together. On the clone where the merge happens it prints:

Notice: auto-merged issue t-…; status, updated_at, closed_at, close_reason
settled last-write-wins (the older side's edit was superseded)

The clone whose edit lost prints Pull complete. and nothing else. Swap the roles (case 4b) and the later edit wins again: a closed task is open again because someone else touched it two seconds later.

This is a reasonable rule and it is written down in beads' own source. It is still a rule, and the losing agent is not told. Our first runs also found its edge. updated_at is shown to the second, and the source sends a row to a person when both timestamps are equal. Without a pause between the two edits, the same case came back once auto-merged and once as "merge conflicts in issues require operator resolution". Two agents editing within the same second can get either outcome.

What this means for branches

Case 1 is the real change, and whether it is a problem depends on how you use branches.

If an agent works on a branch that gets thrown away, its task changes stay. A task it closed is still closed on main. There is nothing to revert, because nothing was committed.

If you review work as a pull request, the task changes are not in the diff. git log will not show when a task was closed, or by whom. That history exists in Dolt (bd dolt log), next to git, not inside it.

If a new person clones the repository, they get no issues until they run bd bootstrap. A teammate who only uses git sees the hooks and the agent files, and none of the work.

The other side is that this is what beads is built to do. One live task list shared by every agent and every machine, whatever branch each one is on, is the point of "distributed graph issue tracker". A task tracker that branches with your code gives each branch its own copy of the truth, and then you have to merge it. Beads chose to keep one copy.

So, does beads store issues in git?

It stores them next to git. They live in a Dolt database, synced through a ref on the same remote as your code. In the 0.x versions the search results describe, it was a JSONL file in your commits. Since 1.0.5 the changelog calls that file an optional export, not "the canonical git-tracked source of truth".

If you want task state to move with a branch and show up in review, that is now a different tool. If you want one list that every agent sees at once, beads 1.x does that, and merged our two-agent cases without help.

FAQ

Can I still keep beads issues in a JSONL file in git?

You can export them there: bd config set export.auto true, and the pre-commit hook refreshes the file. The docs say not to treat it as sync, because JSONL import is upsert-only and cannot tell a deleted issue from one never exported.

Do I need a Dolt server?

No. The default is an embedded engine inside bd, with one writer at a time. Server mode exists for several concurrent writers.

Does beads still use a git merge driver?

Not for the issues in 1.3.1. Merging happens inside Dolt, when you run bd dolt pull. That is why case 1 shows a clean git status: git has nothing to merge.

Is a closed task reopened by a later edit?

In our case 4b, yes: one clone closed the task, the other set it to in progress two seconds later, and after sync both read in_progress. The later updated_at won.