Beads: Memory and Execution Smarts for Agent-Native Coding

Why your AI coding agent keeps forgetting everything—and how to fix it

Context rot is the defining problem of AI-assisted coding.

Photo by Alexey Demidov on Unsplash

Your agent loses state. Forgets what’s done. Hallucinates progress. You compact the context, and suddenly it’s re-litigating decisions you made an hour ago.

Markdown plans feel lightweight, but they’re part of the problem. Agents can’t query them. No dependency tracking. No structured state to reason about. You end up being the memory layer—copying context back and forth, reminding your agent what it already knew.

Beads solves this.

It’s a git-native issue tracker built for agents. SQLite database, JSONL format, version controlled alongside your code. Your agent can query it, update it, track dependencies, and pick up exactly where it left off.

Claude’s new Tasks feature is inspired by Beads. When Anthropic builds a feature based on an open-source CLI tool, pay attention. This pattern is becoming infrastructure.

---

What goes into Beads (and what doesn’t)

Planning happens outside Beads. Execution happens inside.

I use PLAN.md or PRD-for-sprint.md to define what we’re trying to accomplish. Then I ask Opus to decompose it into epics, create tasks, figure out dependencies—all captured in Beads. The instruction is that each epic and ticket must be self-sufficient to be picked up cold.

Human plans the what. AI decomposes the how.

Sprint — Weekly milestone. I define the goal in markdown with Opus. This lives in PLAN.md, not Beads.

Epic — High-level items from sprint planning. 1-2 epics per sprint ticket. Epics go into Beads.

Task — Granular work items. AI handles the breakdown—subtasks, dependencies, sequencing. Tasks go into Beads.

Between the epic (big picture) and the task (details), Claude has all the information required to pick up any ticket cold.

Tight scope in, deep decomposition out.

I don’t create subtasks manually. I tell Claude to analyze the epic, break it down, identify dependencies, and file the tickets. I review what it created, adjust if needed, then let it execute.

---

Session discipline

I started by churning through epics in one session. Felt productive until context overflow hit—Claude compacting, and then I’d have to ask it to reload state from the ticket.

Then I realized: because tickets are granular and have all the context required, I don’t need to be chained to the Claude session. I was holding onto sessions afraid of losing important context. But the context isn’t in the session—it’s in Beads.

That was liberating.

Now I open Claude, ask it to pick the next task, and go. Shorter sessions. More productive. No context anxiety. One task, execute, restart.

Starting a session:

bd prime is in my CLAUDE.md. It loads the workflow rules, the session close protocol, the available commands. Hooks auto-call this in Claude Code when .beads/ is detected.

Ending a session:

I just tell Claude “land the plane.” The closing discipline is so good that Steve Yegge named the pattern after it. Claude automagically runs through everything:

[ ] git status — check what changed
[ ] git add <files> — stage code changes
[ ] bd sync — commit beads changes
[ ] git commit -m "..." — commit code
[ ] bd sync — commit any new beads changes
[ ] git push — push to remote

Work isn’t done until it’s pushed. Your agent finishes current work before wandering to the next thing.

---

Patterns that work

These emerged from weeks of daily use. None are obvious until you’ve lost context the hard way.

File as you go. When Claude surfaces something during implementation—a bug, a refactor needed, a question for later—file it immediately. bd create captures the context fresh, in the moment. Don’t carry it in your head. Don’t trust yourself to remember. The issue exists, the context is preserved, you pick it up in a future session.

Land the plane. Agents love to wander. They’ll start three things and finish none. The land-the-plane pattern keeps them focused: finish current work before starting new work.

bd ready for what’s next. This shows issues with no blockers—ready to work. Use bd blocked to see what’s stuck in dependency chains. I’ll admit I’m still often picking tasks manually because my dependency graphs aren’t mature yet. But as I get better at upfront decomposition, bd ready becomes the natural entry point.

Kanban for the big picture. Beads is CLI-first, but I run a Kanban UI alongside it. I watch as Claude updates tickets in real-time—what’s moving, what’s stuck, what just closed. Big picture visibility without micromanaging.

One thing I’ve learned: I don’t actually know all the bd commands. Claude does. I just tell it what I want—create a ticket, set dependencies, close these three issues. The CLI is abstracted away. That’s the point.

---

What I had to teach my agents

Beads is agent-native, but agents still need guardrails.

CLI discipline. Claude sometimes forgets to use bd and tries to directly read or write .beads/issues.jsonl. It also confuses bd with beads. Both break things. Add explicit instructions and examples to CLAUDE.md:

Always use `bd` CLI commands — NEVER directly read or write .beads/issues.jsonl

bd list                        # List all issues
bd show <issue-id>             # Show details
bd update <id> --status in_progress
bd close <id>
bd comments add <id> "message"

Ticket hygiene. Claude is eager. It wants to chomp through tasks and move on. It’ll come back and tell you everything is done—and often it’s wrong. I explicitly tell it in CLAUDE.md to update tickets with status and learnings as it goes. This keeps it on track and ensures context isn’t lost. The ticket becomes the record of what actually happened, not what Claude thinks happened.

Sync hygiene. Without bd sync flush, the database can have stale state. Run it before commits. Build it into the session close protocol.

These feel like small things, but they compound. An agent that follows CLI discipline, updates tickets, and syncs properly is an agent that maintains accurate state across sessions. That’s the whole game.

---

The ecosystem forming

Beads is lightweight by design—a CLI and a git-backed database. But an ecosystem is growing around it:

• Kanban UIs for visualization

• Hooks that auto-sync when .beads/ is detected

• Community patterns like epic decomposition and land-the-plane

This is early infrastructure. The primitives are right. The UX will mature. The patterns will standardize.

Context rot was the problem. Beads is the memory layer that solves it. The rest is discipline.

Credit to Steve Yegge for creating Beads and the patterns that make it work. Repo here: https://github.com/steveyegge/beads

---

#AgenticCoding #DevTools #Beads