There are a ton of interesting ideas in the README - things like the way it uses the birthday paradox to decide when to increase the length of the hash IDs.
This tool works by storing JSONL in a .beads/ folder. I wonder if it could work using a separate initially-empty "beads" branch for this data instead? That way the beads data (with its noisy commit history) could travel with the repository without adding a ton of noise to the main branch history.
The downside of that is that you wouldn't be able to branch the .beads/ data or keep it synchronized with main on a per-commit basis. I haven't figured out if that would break the system.
The way I read it is beads steers agents to make use of the .beads/ folder to stay in sync across machines. So, my understanding is a dedicated branch for beads data will break the system.
> Agents report that they enjoy working with Beads, and they will use it spontaneously for both recording new work and reasoning about your project in novel ways.
I’m surprised by this wording. I didn’t encounter anyone talking about AI preference yet.
Can a trained LLM develop a preference for a given tool within some context and reliably report on that?
Is “what AI reports enjoying“ aligned with AI’s optimal performance?
The author has a vested interest in AI, that is why it's capabilities may be greatly exaggerated/anthropomorphised as typical for LLM start-ups. Proceed with caution.
I use gh cli to make and track issues on the repo's issue tracker, create and reference the issue in the PR. I use Claude normally, so have Gemini and Codex that sit as automated reviewers (github apps), then get Claude to review the comments. Rinse and repeat. Works quite well and catches some major issues. Reading the PR's yourself (at least skimming them for sanity) is still vital.
I went through the whole readme first and kept wondering what problem the system aims to address. I understood that it is a distributed issue tracker. But how can that lead to a memory upgrade? It also hints at replacing markdown for plans.
So is the issue the format or lack of structure which a local database can bring in?
LLMs famously don't have a memory - every time you start a new conversation with the you are effectively resetting them to a blank slate.
Giving them somewhere to jot down notes is a surprisingly effective way of working around this limitation.
The simplest version of this is to let them read and write files. I often tell my coding agents "append things you figure out to notes.md as you are working" - then in future sessions I can tell them to read or search that file.
Beads is a much more structured way of achieving the same thing. I expect it works well partly because LLM training data makes them familiar with the issue/bug tracker style of working already.
Thanks! It is the structure that matters here, then. Just like you, I ask my agents to keep updating a markdown file locally and use it as a reference during working sessions. This mechanism has worked well for me.
I even occasionally ask agents to move some learnings back to my Claude.md or Agents.md file.
I'm curious whether complicating this behaviour with a database integration would further abstract the work in progress. Are we heading down a slippery slope?
I set up spec-kit first, then updated its templates to tell it to use beads to track features and all that instead of writing markdown files. If nothing else, this is a quality-of-life improvement for me, because recent LLMs seem to have an intense penchant to try to write one or more markdown files per large task. Ending up with loads of markdown poop feels like the new `.DS_Store`, but harder to `.gitignore` because they'll name files whatever floats their boat.
I usually just use a commit agent that has as one of its instructions to review various aspects of the prospective commit, including telling it to consolidate any documentation and remove documentation of completed work except where it should be rolled into lasting documentation of architecture or features. I've not rolled it out in all my projects yet, but for the ones I do, it's gotten rid of the excess files.
Cool stuff. The readme is pretty lengthy so it was a little hard to identify what is the core problem this tool is aiming to solve and how is it tackling it differently than the present solutions.
Funnily, AI already knows what stereotypical AI sounds like, so when I tell Claude to write a README but "make it not sounds like AI, no buzzwords, to the point, no repetition, but also don't overdo it, keep it natural" it does a very decent job.
Actually drastically improves any kind of writing by AI, even if just for my own consumption.
I'm not saying it is or isn't written by an LLM, but, Yegge writes a lot and usually well. It somehow seems unlikely he'd outsource the front page to AI, even if he's a regular user of AI for coding and code docs.
The Beads project uses Bewds itself as an issue tracker, which means their issues data is available here as JSONL:
https://github.com/steveyegge/beads/blob/main/.beads/issues....
Here's that file opened in Datasette Lite which makes it easier to read and adds filters for things like issue type and status:
https://lite.datasette.io/?json=https://github.com/steveyegg...
There are a ton of interesting ideas in the README - things like the way it uses the birthday paradox to decide when to increase the length of the hash IDs.
This tool works by storing JSONL in a .beads/ folder. I wonder if it could work using a separate initially-empty "beads" branch for this data instead? That way the beads data (with its noisy commit history) could travel with the repository without adding a ton of noise to the main branch history.
The downside of that is that you wouldn't be able to branch the .beads/ data or keep it synchronized with main on a per-commit basis. I haven't figured out if that would break the system.
The way I read it is beads steers agents to make use of the .beads/ folder to stay in sync across machines. So, my understanding is a dedicated branch for beads data will break the system.
> Agents report that they enjoy working with Beads, and they will use it spontaneously for both recording new work and reasoning about your project in novel ways.
I’m surprised by this wording. I didn’t encounter anyone talking about AI preference yet.
Can a trained LLM develop a preference for a given tool within some context and reliably report on that?
Is “what AI reports enjoying“ aligned with AI’s optimal performance?
LLM-s also report that they enjoy my questions, in fact they tell me it's a good question literally every time I ask about their weird choices.
I think (hope) it's meant to be a joke.
The author has a vested interest in AI, that is why it's capabilities may be greatly exaggerated/anthropomorphised as typical for LLM start-ups. Proceed with caution.
I use gh cli to make and track issues on the repo's issue tracker, create and reference the issue in the PR. I use Claude normally, so have Gemini and Codex that sit as automated reviewers (github apps), then get Claude to review the comments. Rinse and repeat. Works quite well and catches some major issues. Reading the PR's yourself (at least skimming them for sanity) is still vital.
I went through the whole readme first and kept wondering what problem the system aims to address. I understood that it is a distributed issue tracker. But how can that lead to a memory upgrade? It also hints at replacing markdown for plans.
So is the issue the format or lack of structure which a local database can bring in?
LLMs famously don't have a memory - every time you start a new conversation with the you are effectively resetting them to a blank slate.
Giving them somewhere to jot down notes is a surprisingly effective way of working around this limitation.
The simplest version of this is to let them read and write files. I often tell my coding agents "append things you figure out to notes.md as you are working" - then in future sessions I can tell them to read or search that file.
Beads is a much more structured way of achieving the same thing. I expect it works well partly because LLM training data makes them familiar with the issue/bug tracker style of working already.
Thanks! It is the structure that matters here, then. Just like you, I ask my agents to keep updating a markdown file locally and use it as a reference during working sessions. This mechanism has worked well for me.
I even occasionally ask agents to move some learnings back to my Claude.md or Agents.md file.
I'm curious whether complicating this behaviour with a database integration would further abstract the work in progress. Are we heading down a slippery slope?
I've been trying `beads` out for some projects, in tandem with https://github.com/github/spec-kit with pretty good results.
I set up spec-kit first, then updated its templates to tell it to use beads to track features and all that instead of writing markdown files. If nothing else, this is a quality-of-life improvement for me, because recent LLMs seem to have an intense penchant to try to write one or more markdown files per large task. Ending up with loads of markdown poop feels like the new `.DS_Store`, but harder to `.gitignore` because they'll name files whatever floats their boat.
I usually just use a commit agent that has as one of its instructions to review various aspects of the prospective commit, including telling it to consolidate any documentation and remove documentation of completed work except where it should be rolled into lasting documentation of architecture or features. I've not rolled it out in all my projects yet, but for the ones I do, it's gotten rid of the excess files.
I've found it pretty useful as well. It doesn't compete with gh issues as much as it competes with markdown specs.
It's helpful for getting Claude code to work with tasks that will span multiple context windows.
Cool stuff. The readme is pretty lengthy so it was a little hard to identify what is the core problem this tool is aiming to solve and how is it tackling it differently than the present solutions.
A classic issue of AI generated READMEs. Never to the point, always repetitive and verbose
Funnily, AI already knows what stereotypical AI sounds like, so when I tell Claude to write a README but "make it not sounds like AI, no buzzwords, to the point, no repetition, but also don't overdo it, keep it natural" it does a very decent job.
Actually drastically improves any kind of writing by AI, even if just for my own consumption.
I'm not saying it is or isn't written by an LLM, but, Yegge writes a lot and usually well. It somehow seems unlikely he'd outsource the front page to AI, even if he's a regular user of AI for coding and code docs.
And full of marketing hyperbole. When I have an AI produce a README I always have to ask it to tone it down and keep it factual.
This looks like a ticketing cli
That's exactly what this is, but it's one that's designed with coding agents in mind as its principle users.