> 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 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?
If there’s any type of memory upgrade for a coding agent I would want, it’s the ability to integrate a RAG into the context.
The information being available is not the problem; the agent not realizing that it doesn’t have all the info is, though. If you put it behind an MCP server, it becomes a matter of ensuring the agent will invoke the MCP at the right moment, which is a whole challenge in itself.
Are there any coding agents out there that enable you to plug middleware in there? I’ve been thinking about MITM’ing Claude Code for this, but wouldn’t mind exploring alternative options.
I've been having a ton of success just from letting them use their default grep-style search tools.
I have a folder called ~/dev/ with several hundred git projects checked out, and I'll tell Claude Code things like "search in ~/dev/ for relevant examples and documentation".
(I'd actually classify what I'm doing there as RAG already.)
What I mean is basically looking at the last (few) messages in the context, translating that to a RAG query, query your embeddings database + BM25 lookup if desired, and if you find something relevant inject that right before the last message in the context.
It’s pretty common in a lot of agents, but I don’t see a way to do that with Claude Code.
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.
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?
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.
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 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.
> 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.
You're absolutely right!
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 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?
Makes me wonder whether you can just give agents [Taskwarrior](https://taskwarrior.org/).
Set the TASKDATA to `./.task/`. Then tell the agents to use the task CLI.
The benefit is most LLMs already understand Taskwarrior. They've never heard of Beads.
If there’s any type of memory upgrade for a coding agent I would want, it’s the ability to integrate a RAG into the context.
The information being available is not the problem; the agent not realizing that it doesn’t have all the info is, though. If you put it behind an MCP server, it becomes a matter of ensuring the agent will invoke the MCP at the right moment, which is a whole challenge in itself.
Are there any coding agents out there that enable you to plug middleware in there? I’ve been thinking about MITM’ing Claude Code for this, but wouldn’t mind exploring alternative options.
What do you mean by a RAG here?
I've been having a ton of success just from letting them use their default grep-style search tools.
I have a folder called ~/dev/ with several hundred git projects checked out, and I'll tell Claude Code things like "search in ~/dev/ for relevant examples and documentation".
(I'd actually classify what I'm doing there as RAG already.)
What I mean is basically looking at the last (few) messages in the context, translating that to a RAG query, query your embeddings database + BM25 lookup if desired, and if you find something relevant inject that right before the last message in the context.
It’s pretty common in a lot of agents, but I don’t see a way to do that with Claude Code.
The Beads project uses Beads 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.
But wouldn't that dedicated branch, pushed to origin, also work for staying synced across multiple machines?
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...
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'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.