(2026-01-24) Bull Beads Memory For Your Agent And The Best Damn Issue Tracker Yourre Not Using

Ian Bull: Beads - Memory for your Agent and The Best Damn Issue Tracker Your're Not Using. Fifteen years ago, while converting the Eclipse Project from CVS to Git, Chris Aniszczyk mused about a distributed issue tracker. The idea stuck with me. I figured someone smarter than me would eventually build it. Turns out Steve Yegge did, but for a reason none of us anticipated: AI agents need external memory.

Beads (bd) is a git-backed issue tracker designed for AI coding agents.

But how do you actually use it? After spending time with beads and digging into community patterns, here’s what I found that works.

The Core Mental Model

Beads stores issues in two places:
SQLite (.beads/beads.db) - fast local queries, gitignored
JSONL (.beads/issues.jsonl) - git-tracked, syncs across machines

The core query is simple:
bd ready --json
This returns unblocked, prioritized work. No parsing markdown. No hallucinating what phase you’re on. Just structured data.

Why Not Markdown Plans?

Getting Started

The Core Workflow: Think → Create → Act

The first question everyone asks: do I start from issues or prompts?

Both work, but they serve different purposes.

Prompt-First (Reactive Work)

You see a bug, you tell the AI about it:
“There’s an auth bug where tokens expire too early. Investigate and fix it.”
The AI investigates, understands the problem, creates issues as it plans.
Then works through them, closing as it goes.

When to use: Ad-hoc bugs, exploration, when you don’t know the full scope yet.

Issue-First (Planned Work)

You know what needs doing, so you create the issue first:

Then tell the AI:

“Work on bd-a1b2”

The AI has a clear target with acceptance criteria.

When to use: Features, planned work, when you want to track progress across sessions.

The Pattern That I Use

Think with prompts: Describe the problem, let AI investigate Create issues: Capture the work discovered (AI or you) Act on issues: Work through bd ready, close when done

The key insight: issues are handoff points. When you kill a session and start fresh, the new agent runs bd ready and knows exactly where to pick up.

Session Bookends

Start

End:

Four Dependency Types

(table) TypePurposeAffects Ready Work?blocksX cannot start until Y completesYesparent-childTask belongs to epicYes (epic blocks children)relatedConnected but don’t block each otherNodiscovered-fromFound while working on another issueNo (audit trail only)

The discovered-from type is particularly powerful. When your agent is fixing a bug and notices a memory leak in an unrelated service, it can file:

Usage Patterns

Pattern 1: Epic Decomposition

For larger features, start with an epic and decompose:

• Create a design doc (or brainstorm with your agent)
• Create an epic: bd create "User Authentication System" -t epic -p 1
• Have the agent decompose into child tasks with dependencies
• Execute via bd ready loop

Pattern 2: File As You Go

For exploratory work or smaller features:

• Start working on something
• When you discover sub-tasks, file them: bd create "Handle edge case X" -p 2 --deps discovered-from:current-task
• When a task will take more than ~2 minutes, file it as a bead

Pattern 3: Hybrid (Specs + Beads)

Combine detailed planning documents with Beads execution:

• Create detailed markdown specs outlining goals and requirements
• Feed the spec to your agent, have it create structured epics/tasks in Beads
• Execute using Beads, track progress there

The “Land the Plane” Protocol

At the end of every session, don’t just stop. Tell your agent to “land the plane”:

Critical: The plane isn’t landed until git push succeeds. Unpushed work causes severe conflicts in multi-agent workflows.

Init Modes for Different Scenarios

Stealth mode is perfect when you want personal task tracking on a shared repo without committing beads files.

Contributor mode routes your planning issues to a separate location, keeping experimental work out of PRs.

Protected branch mode commits to a separate sync branch, then you merge via PR.

How Collaboration Works

Multi-Agent Workflows

For teams running multiple AI agents:

• Git Worktrees: Each agent gets its own worktree and branch. Beads syncs via git. Agents work independently, merge normally.
• Agent Mail: Pair Beads (shared memory) with MCP Agent Mail (messaging). Agents coordinate task claims and handoffs in real-time.

As Jeffrey Emanuel (creator of MCP Agent Mail) described to Yegge: “Beads gives the agents shared memory, and Agent Mail gives them messaging… that’s all they need. You just give them a task and tell them to go sort it out amongst themselves.”

The Daemon

Behind the scenes, a background daemon handles synchronization

Dealing with Context Rot

If your agent forgets about Beads mid-session (which happens as context fills)

Database Maintenance

Over time, closed issues accumulate. Beads provides “agentic memory decay

This replaces detailed issue content with AI-generated summaries, preserving essential context while reducing database size.

Beads Vs. Traditional Issue Trackers

Yegge is explicit about positioning: “Beads isn’t a planning tool, a PRD generator, or Jira. It’s orchestration for what you’re working on today and this week

This doesn’t mean you can’t use Beads for backlogs — there’s a P4 (backlog) priority level, and nothing technically prevents it.

Why Beads favours near-term work:

Ready work detection: The bd ready command surfaces what’s unblocked right now.

Context window efficiency: Beads is designed to give agents only what they need.

Execution over planning: Planning happens in specs, PRDs, design docs. Beads tracks what you’re actively building, not what you might build in Q3.

Practical guidance:

• Use Beads for this week’s work and near-term features you’re actively decomposing
• Keep distant backlog items in your existing system (GitHub Issues, Linear, Notion, a simple markdown file)
• When a backlog item moves to “now,” create a Beads epic and decompose it
• Use P4 priority sparingly for “discovered but not urgent” work that you’ll get to soon

The goal is keeping bd ready crisp and actionable.

Other cases where Beads isn’t the right tool:

The Community Tools Ecosystem

Yegge is explicit about this: “Beads doesn’t have a UI, but it has lots of example UIs that people have built as passion projects

Just as git has GitHub, GitLab, VS Code, and dozens of clients built on top of it, Beads has spawned a rich ecosystem of tools, each solving different workflow problems

Terminal UIs (TUIs)

Web Interfaces

Orchestration and Multi-Agent Tools

The Protocol Advantage

Any developer can build on Beads because the interface is stable and well-documented.

The Honest Gaps

Beads is designed as passive infrastructure

This creates some friction you should know about:

Claude doesn’t proactively use it.

CLAUDE.md instructions fade.

Session handoff is manual

Context rot still happens.

Collaboration requires setup.

Merge conflicts happen.

The Bigger Picture

Beads represents a new category: agent-native infrastructure. Rather than retrofitting AI onto existing issue trackers, it asks: “What would task management look like if designed from scratch for AI agents?”

Getting Started Today

Summary

Editor Integrations