Depends what you mean by “synced”—do you want your beads state to be coupled with commits (eg: checking out an old commit also shows you the beads state at that snapshot)? Using a separate branch would decouple this. I think the coupling is a nice feature, but it isn’t a feature that other bug trackers have, so using a separate branch would make beads more like other bugtrackers. If you see the coupling as noise, though, then it sounds like that is what you want.

The way I understand this, when the agent runs `bd onboard` at startup, it gets the instructions from beads, which might refer to data files in the beads directory. Keeping them in sync via a separate branch would be an unnecessary overhead. Right?

I don't see it as extra overhead - it just changes the git one-liner they use to push and pull their issue tracking content by a few characters.

I like the idea of keeping potentially noisy changes out of my main branch history, since I look at that all the time.

You are right. I dug through the document some more. The setup, as mentioned for protected branches [1], should ideally work without much overhead. It does suggest merging back to main, but the FAQ also mentions that the frequency can be decided individually.

[1] https://github.com/steveyegge/beads/blob/main/docs/PROTECTED...