Beads investigation (spawned by Claude on behalf of Ryan, 2026-04-30)

TL;DR

The harmonized draft’s claim that beads’ lifecycle is strictly open → in_progress → closed is wrong. Beads currently ships seven built-in statuses: open, in_progress, blocked, deferred, closed, pinned, hooked. deferred and pinned are explicitly “frozen” — kept around indefinitely, much like seeds’ deferred state.
The harmonized draft paraphrases Yegge’s motivation as “I’m coding, I notice something, I don’t want to forget, I don’t want to context-switch.” Yegge’s actual framing in his own writing is agent-centric, not human-centric: agents lose context across sessions, file beads when they notice unrelated problems mid-task, and use beads to coordinate long-horizon work. The draft’s framing is roughly right but should be re-attributed and ideally re-quoted from his own words.
Yegge has a direct, on-record statement that decisively supports the seeds/beads boundary the post wants to draw: “Everyone is focused on making planning tools, and Beads is an execution tool.” He also says, verbatim, “Beads doesn’t have a planning system. That’s not what it’s for.” This is gold for the post.
However, beads now ships a built-in decision issue type (with adr/dec aliases), a persistent bd remember/bd recall/bd memories memory system, ephemeral “wisp” issues (with their own promote-to-permanent path), comments-with-threading, molecules/formulas, swarms, and a human flag for “flag for human decision.” These features exist. The harmonized draft’s claim that beads has “been growing” these is factually correct in 2026-04.
But the boundary the post wants to draw still holds, because Yegge has explicitly delimited beads as execution-only. The decision/memory/wisp features are about execution-supporting metadata (ADRs about implementation, agent memory across sessions, ephemeral status pings), not deliberation about what to build. The post’s argument should be strengthened, not weakened, by Yegge’s own boundary-statements — and should drop the speculative “beads might absorb seeds eventually” line since Yegge has explicitly said planning is out of scope.

Lifecycle

Beads supports seven built-in statuses, not three. From bd statuses (CLI as of 2026-04-30):

○ open           [active]  Available to work (default)
◐ in_progress    [wip   ]  Actively being worked on
● blocked        [wip   ]  Blocked by a dependency
❄ deferred       [frozen]  Deliberately put on ice for later
✓ closed         [done  ]  Completed
📌 pinned         [frozen]  Persistent, stays open indefinitely
◇ hooked         [wip   ]  Attached to an agent's hook

Custom statuses can be configured via bd config set status.custom. The four categories are active, wip, done, frozen. Note frozen — beads explicitly has lifecycle slots for issues that are kept around without being closed.

There are also commands that relate to lifecycle but aren’t states: bd defer <id>, bd supersede <id>, bd reopen <id>, bd duplicate. The seeds blog’s claim of “open → in_progress → closed” misses at least deferred, pinned, and blocked.

Source: bd statuses CLI output, beads version installed at /home/ryan/.nix-profile/bin/bd, captured 2026-04-30. Same information should appear at https://gastownhall.github.io/beads/ (the official docs site).

Yegge’s stated purpose, verbatim

These quotes are pulled from Yegge’s own Medium articles. The Medium URL is the original publication. The article Introducing Beads is also mirrored at steveyegge.spicytakes.org.

From “Introducing Beads: A coding agent memory system” (2025-11-12)

URL: https://steve-yegge.medium.com/introducing-beads-a-coding-agent-memory-system-637d7d92514a

“It’s an issue tracker. A special one.”

“Beads is a tool that AI has built for itself.”

“The problem we all face with coding agents is that they have no memory between sessions — sessions that only last about ten minutes.”

“Coding agents, when they start to get close to their compaction limit … they start to panic and make executive decisions about getting your task ‘done’ at all costs.”

On the moment of creation:

“On Wednesday Oct 8th, day 37 of my spree, my agent had, for the nth time, expanded yet another phase, and got itself totally lost yet again. I had had enough. On a lark, I said, ‘Screw it. Let’s just move all known work from the plans into an issue tracker.’”

On the “I notice something” framing the seeds draft paraphrases:

“Agents will no longer ignore ‘unrelated’ problems they encounter.”

“Instead your agents will say, ‘I notice all your tests are broken … and I’ve filed issue 397 to get them working again.’”

Note: in Yegge’s framing the agent is the one noticing and filing, not the human. The seeds draft’s “I’m coding, I notice something, I don’t want to forget” reads more like a human’s stream of consciousness. Yegge’s framing is that beads keeps the agent from losing track of work it discovers.

On adoption inside his own workflow:

“My agents have switched — without a hint of ever going back — from using markdown plans, to using the issue tracker exclusively.”

From “Beads Best Practices” (Medium)

URL: https://steve-yegge.medium.com/beads-best-practices-2db636b9760c

This is the most important quote for the seeds blog:

“Everyone is focused on making planning tools, and Beads is an execution tool.”

“Beads sits in an utterly unique space … it’s focused on just the tracking, and nothing else”

“Beads doesn’t have a planning system. That’s not what it’s for.”

“The last big category people keep trying to wedge into Beads is orchestration … that stuff doesn’t belong in Beads.”

“You should ask the AI to file beads to track any work that will take it longer than about 2 minutes to finish.”

From “Beads Blows Up” (Medium)

URL: https://steve-yegge.medium.com/beads-blows-up-a0a61bb889b4

“Beads is meant to be the working memory for your active agents. Nothing more nor less.”

“Finished issues and future issues don’t really belong in Beads — it’s best to keep them in a separate store.”

“it’s not meant to be Jira”

This is also gold. Yegge himself says “future issues don’t really belong in Beads” — which is exactly the niche seeds occupies. Things that might become work but haven’t been promoted to active execution yet do not belong in beads, by Yegge’s own description.

From the GitHub README

URL: https://github.com/steveyegge/beads (raw README.md)

Opening line:

“Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.”

Bullet describing graph features:

“Graph Links: relates_to, duplicates, supersedes, and replies_to for knowledge graphs.”

Bullet describing messaging:

“Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.”

Feature inventory

All confirmed via bd <command> --help against the locally installed CLI on 2026-04-30, plus the GitHub README and Yegge’s articles.

`bd remember` / `bd recall` / `bd memories` / `bd forget`

Persistent key-value memory store, scoped to the beads database. From bd remember --help:

“Store a memory that persists across sessions and account rotations. Memories are injected at prime time (bd prime) so you have them in every session without manual loading.”

Examples Yegge gives:

bd remember "always run tests with -race flag"
bd remember "Dolt phantom DBs hide in three places" --key dolt-phantoms
bd remember "auth module uses JWT not sessions" --key auth-jwt

This is not a deliberation log. It’s an insight/rule store. The examples are operational facts (“the auth module uses JWT”) rather than open questions or possibilities. It’s closer to seeds’ “resolved” state than to its “captured” or “exploring” states. There is no question/answer affordance, no parent/child relationship between memories, no abandoned-with-rationale state.

`bd create --type=decision` (or `--type=adr`/`--type=dec`)

Beads has a built-in decision issue type. From bd types:

“decision Architecture decision record (ADR)”

From bd create --help:

“Issue type (bug feature task epic chore decision); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision”

This is an ADR, which is a record of a decision already made about implementation — typically with rationale, alternatives considered, and consequences. It’s not a deliberation tool (“should we do X?”). It’s a record-after-the-fact for execution-relevant architectural choices.

`bd create --ephemeral` / wisps

Wisps are short-lived issues subject to TTL-based compaction. From bd create --help:

--ephemeral    Create as ephemeral (short-lived, subject to TTL compaction)
--wisp-type    Wisp type for TTL-based compaction:
               heartbeat, ping, patrol, gc_report, recovery, error, escalation

Wisps live in a dolt_ignored table (i.e., not version-controlled), and there’s a bd promote command to move a wisp into the permanent issues table:

“Promote a wisp (ephemeral issue) to a permanent bead. This copies the issue from the wisps table (dolt_ignored) to the permanent issues table (Dolt-versioned).”

There’s also bd mol wisp to instantiate a workflow template as an ephemeral wisp (“vapor phase” in the molecule metaphor) and bd mol burn to discard a wisp without preserving it.

The defined wisp types — heartbeat, ping, patrol, gc_report, recovery, error, escalation — are all about agent operations and lifecycle signals, not deliberation. A wisp is closer to a transient log entry that may or may not turn into a real issue. It is not “a thought I had that might become work.”

Comments and threading

bd comment <id> "text" adds a comment to an issue. bd comments <id> lists them. There is also a replies_to graph link in the README’s feature list, used for threading — but threading appears to be a feature of the Message issue type specifically (per the README: “Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation”), used for inter-agent or human-agent communication, not for deliberation on issues.

So “threaded discussions” in beads means agent-to-agent (or agent-to-human) messaging, not threaded debate on whether to take an action. It’s a coordination mechanism, not a deliberation mechanism.

Molecules and formulas

These are workflow templates, not lifecycle features. From bd mol --help:

“Manage molecules — work templates for agent workflows. Protos are template epics with the ‘template’ label. They define a DAG of work that can be spawned to create real issues (molecules).”

Lifecycle: Rig → Cook → Run. Formulas are YAML/JSON workflow definitions; protos are uninstantiated templates; molecules are spawned real issue trees. Wisps can be ephemeral instantiations of protos.

Swarms

bd swarm manages parallel work coordination on epics — a swarm is “a structured body of work defined by an epic and its children, with dependencies forming a DAG.” This is multi-agent coordination on execution work.

Other notable commands

bd q "title" — quick capture, outputs only the issue ID. Surface-level resemblance to seeds’ seeds jot, but creates a full issue (default type: task) bound for the same execution lifecycle.
bd defer <id> --until="date" — hide issue from bd ready until a date.
bd supersede <id> — mark an issue as superseded by a newer one.
bd duplicate and bd find-duplicates — duplicate detection.
bd human <id> — “flag for human decision (list/respond/dismiss).” This is interesting: an issue that beads can’t move forward without human input. Not a deliberation issue type — a flag attached to an existing issue.
bd preflight, bd lint, bd stale — hygiene commands.
bd dep add with types blocks, related, parent-child, discovered-from — typed relationships exist for dependency semantics.

Boundary statements

These are the most useful Yegge quotes for the seeds blog post. All are direct, all are from his own writing.

Beads is execution, not planning

“Everyone is focused on making planning tools, and Beads is an execution tool.” — Beads Best Practices

“Beads doesn’t have a planning system. That’s not what it’s for.” — Beads Best Practices

“make your plan, then tell the agent to file Beads epics and issues for the work.” — Beads Best Practices (paraphrased description of the workflow Yegge recommends)

Beads is for active agent memory, not the full work archive

“Beads is meant to be the working memory for your active agents. Nothing more nor less.” — Beads Blows Up

“Finished issues and future issues don’t really belong in Beads — it’s best to keep them in a separate store.” — Beads Blows Up

This is the strongest possible support for seeds’ niche from Yegge himself. “Future issues don’t really belong in Beads” is precisely what seeds claims to be: a store for things that might become future issues, where most of them probably won’t.

Beads is narrow on purpose

“Beads sits in an utterly unique space … it’s focused on just the tracking, and nothing else” — Beads Best Practices

“The last big category people keep trying to wedge into Beads is orchestration … that stuff doesn’t belong in Beads.” — Beads Best Practices

Yegge actively rejects scope creep. He has not pitched bd memory / bd decision as a deliberation system — they are execution-supporting metadata.

The 2-minute rule

“You should ask the AI to file beads to track any work that will take it longer than about 2 minutes to finish.” — Beads Best Practices

Anything that doesn’t yet pass the “is this work?” test isn’t a beads candidate yet. That’s the seeds niche.

Recommendations for the blog

seeds-1.18 (§”The relationship with beads”)

Current opening line in the harmonized draft (line 119):

“Steve Yegge built beads — short for ‘bug database’ — for a very specific use case: I’m coding, I notice something, I don’t want to forget it, I don’t want to context-switch.”

Issues:

“Bug database” is one plausible expansion of “bd,” but neither the README nor Yegge’s articles confirm it. The README’s actual subtitle is “Distributed graph issue tracker for AI agents.” Yegge’s first article calls it an “issue tracker. A special one.” Drop the etymology unless you can cite it.
“I’m coding, I notice something” reads as a human’s voice, but Yegge frames the noticing as the agent’s action: “agents will say, ‘I notice all your tests are broken … and I’ve filed issue 397.’” Re-attribute the noticing.
Ryan’s own feedback in seeds-1.18 calls out the missing third beat: “revisit the problem later knowing it has been faithfully captured.” That third beat is real — Yegge’s quote about “no memory between sessions” supports it directly.

Suggested rewrite (preserving the post’s voice):

Steve Yegge built beads as, in his words, “an issue tracker. A special one” — and as “a tool that AI has built for itself.” The problem he was solving was that coding agents have, in his framing, “no memory between sessions — sessions that only last about ten minutes.” Beads is what he reached for after, on day 37 of a spree, his agent had “for the nth time, expanded yet another phase, and got itself totally lost.” After installing beads, his agents started saying, “I notice all your tests are broken … and I’ve filed issue 397 to get them working again” — flagging unrelated work without losing the thread of the current task, and trusting that the issue would still be there when somebody came back to it. After several months of heavy use I will tell you flatly that beads has fundamentally changed the way I work with AI on implementation.

Lifecycle bullets (lines 125-128): the “Beads: open → in_progress → closed” claim is factually wrong. Either:

Drop the lifecycle bullet pair entirely — the rhetorical move works without enumerating beads’ states.
Or replace with a citable framing from Yegge himself, e.g.:

Yegge has been explicit about beads’ scope: “Everyone is focused on making planning tools, and Beads is an execution tool.” (Beads Best Practices) He’s also said, of his own tool: “Finished issues and future issues don’t really belong in Beads — it’s best to keep them in a separate store.” (Beads Blows Up) Seeds is a store for things that might become future beads — most of which never will.

This approach uses Yegge’s own words to draw the boundary, which is exactly what Ryan asked for, and it sidesteps the strict-three-state lifecycle claim.

The “bd memory, bd decision, bd wisp, threaded discussions” paragraph (line 128): this paragraph is mostly accurate as enumeration but the inferred direction (“a foray into decision and deliberation capture”) is overstated. From the actual feature surfaces:

bd remember is an operational insight store (“auth uses JWT”) — not deliberation.
bd create --type=decision is an ADR — a record of a decision already made, with rationale.
Wisps are TTL-bound ephemeral issues for agent ops signals (heartbeat, error, gc_report).
Threading is the Message issue type for agent-to-agent coordination.

These features support execution. None of them is structured for “should we do X?” deliberation. The paragraph could be tightened to acknowledge them without overclaiming. Suggested:

As of this writing, beads has grown a few features adjacent to seeds’ territory — bd remember for persistent agent memory, bd create --type=decision for ADRs, ephemeral “wisp” issues, threaded messages between agents. None of them, as far as I can tell, is structured for the deliberation half: “should we do this at all? what about X instead? maybe we can simplify by…” Yegge himself has been explicit about the scope: “Beads doesn’t have a planning system. That’s not what it’s for.” The deliberation goes in the planning tool. The work goes in the execution tool. If a future beads grows a comfortable place for all of that, I’ll happily migrate. The investment isn’t in seeds existing as a separate thing forever. The investment is in the deliberation surviving.

seeds-1.24 (the “beads might absorb seeds” bullet)

Ryan’s note in the seed: “Let’s do that beads investigation before we say beads might absorb seeds eventually. I’m not even sure if that’s a what seeds doesn’t do kind of a thing. And we already said it before. So it feels redundant and perhaps wrong.”

Investigation conclusion: this bullet should be cut, or rewritten with weaker language.

Reasons:

Yegge has been explicit that planning is out of scope. The premise of “beads might absorb seeds” assumes beads will expand into deliberation; Yegge has rejected that. So the bullet leans on a counterfactual Yegge himself has dismissed.
The point is already covered in §”The relationship with beads” via the migration-acceptance line (“If a future beads grows a comfortable place for all of that, I’ll happily migrate”). Repeating it is redundant.

Recommendation: drop seeds-1.24 from the harmonized draft. The “I have no investment in seeds existing as a separate thing forever” beat lives elsewhere and is stronger there.

Net effect on the post

The post is strengthened by the investigation, not weakened. Yegge has on-record statements that draw exactly the boundary Ryan wants to draw, in his own voice. The seeds blog can quote him directly to support the seeds/beads distinction, instead of asserting a lifecycle simplification that is no longer accurate.

Sources

All accessed 2026-04-30 from this Claude session.

Primary (Yegge’s own writing):

README, https://github.com/steveyegge/beads (raw at https://raw.githubusercontent.com/steveyegge/beads/main/README.md)
“Introducing Beads: A coding agent memory system” (2025-11-12), https://steve-yegge.medium.com/introducing-beads-a-coding-agent-memory-system-637d7d92514a (mirror: https://steveyegge.spicytakes.org/post/2025-11-12-introducing-beads-a-coding-agent-memory-system)
“The Beads Revolution: How I Built the TODO System That AI Agents Actually Want to Use,” https://steve-yegge.medium.com/the-beads-revolution-how-i-built-the-todo-system-that-ai-agents-actually-want-to-use-228a5f9be2a9
“Beads Blows Up,” https://steve-yegge.medium.com/beads-blows-up-a0a61bb889b4
“Beads Best Practices,” https://steve-yegge.medium.com/beads-best-practices-2db636b9760c
“The Future of Coding Agents,” https://steve-yegge.medium.com/the-future-of-coding-agents-e9451a84207c

CLI introspection (locally installed beads, version at /home/ryan/.nix-profile/bin/bd):

bd statuses (status enumeration)
bd types (type enumeration including built-in decision)
bd create --help (flags for --ephemeral, --wisp-type, --type=decision)
bd remember --help, bd recall --help, bd memories --help, bd forget --help
bd promote --help (wisp → permanent bead)
bd mol --help, bd formula --help (workflow templates)
bd swarm --help (multi-agent coordination)
bd comment --help, bd comments --help
bd prime, bd onboard, bd quickstart (Yegge-authored official prose embedded in the CLI)

Yegge-authored prose embedded in the CLI itself (these are also primary-source):

bd prime includes the line: “Memory: Use bd remember 'insight' for persistent knowledge across sessions.”
bd quickstart includes: “bd is designed for AI-supervised workflows.”
bd onboard recommends adding to AGENTS.md: “This project uses bd (beads) for issue tracking.”