Beads - Memory for your Agent and The Best Damn Issue Tracker Your're Not Using

Posted on:January 24, 2026

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. Built by Yegge in 6 days with Claude, it solves what he calls the “50 First Dates” problem, agents wake up with no memory of yesterday’s work. Beads gives them persistent, structured memory that travels with your code in git.

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:

When you run bd create, it writes to SQLite immediately, then exports to JSONL. When collaborators pull, the JSONL imports to their SQLite. No central server, git IS the database.

Your machine                    Collaborator's machine
─────────────                   ──────────────────────
SQLite (local)                  SQLite (local)
    ↕ auto-sync                     ↕ auto-sync
JSONL (git-tracked)   ←─────→   JSONL (git-tracked)
         └──── git push/pull ────┘

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?

Markdown plans break down during long-horizon work:

As Yegge puts it: “All they know is what’s on disk. If you got competing documents, obsolete documents, conflicting documents… they get dementia.”

Beads replaces this with a single queryable database that syncs via git.

Getting Started

# Install
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Initialize in your project
cd your-project
bd init

# For Claude Code: install hooks
bd setup claude

That’s it. No PostgreSQL, no Redis, no Docker. Just a local SQLite database and a JSONL file that travels with your code.

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:

bd create "Token expiry set to 1 hour instead of 24" -t bug -p 1
bd create "Add token refresh logic" -t task -p 2
bd dep add <refresh-task> <expiry-bug>  # refresh depends on fix

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:

bd create "Implement dark mode toggle" -t feature -p 2 \
  --description "Add toggle in settings, persist preference, apply theme"

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

  1. Think with prompts: Describe the problem, let AI investigate
  2. Create issues: Capture the work discovered (AI or you)
  3. 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:

bd ready                    # What's available?
bd show <id>                # Review before starting
bd update <id> --status in_progress

End:

bd close <id>               # Complete work
bd sync                     # Export and commit
git push                    # Share with team

Four Dependency Types

Beads supports four distinct relationship types:

TypePurposeAffects Ready Work?
blocksX cannot start until Y completesYes
parent-childTask belongs to epicYes (epic blocks children)
relatedConnected but don’t block each otherNo
discovered-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:

bd create "Fix memory leak in image loader" -t bug -p 1 \
  --deps discovered-from:bd-abc123 --json

The leak is now tracked, linked to its discovery context, and won’t be forgotten when the session ends.

Usage Patterns

Pattern 1: Epic Decomposition

For larger features, start with an epic and decompose:

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

Beads supports arbitrary nesting, epics can contain sub-epics, which contain tasks. The dependency graph handles blocking automatically.

Pattern 2: File As You Go

For exploratory work or smaller features:

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

This pattern is less structured but captures work that would otherwise be lost.

Pattern 3: Hybrid (Specs + Beads)

Combine detailed planning documents with Beads execution:

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

The spec provides the “why” and high-level design; Beads provides the “what’s next” and execution tracking.

The “Land the Plane” Protocol

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

Let's land the plane

This triggers a cleanup protocol:

  1. Run quality gates (tests, linting)
  2. File any remaining discovered work as issues
  3. Close finished issues
  4. Pull, sync, and push to remote
  5. Generate a handoff prompt for the next session

The handoff prompt is key, it’s a ready-to-paste summary that the next agent (or tomorrow’s session) can use to immediately orient itself.

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

Init Modes for Different Scenarios

Beads adapts to various collaboration patterns:

bd init                      # Basic interactive setup
bd init --quiet              # Non-interactive (for agents)
bd init --stealth            # Local-only, no repo pollution
bd init --contributor        # OSS fork workflow
bd init --team               # Team member with commit access
bd init --branch beads-sync  # Protected branch workflow

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

Beads uses git as its distributed database:

  1. You make changes → Daemon exports to .beads/issues.jsonl
  2. You commit and push the JSONL file
  3. Collaborators pull → Their daemon auto-imports

Hash-based issue IDs (e.g., bd-a3f2) prevent collisions when multiple agents create issues simultaneously. No more “both agents created bd-10” merge conflicts.

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:

CLI Command → Unix Socket → Daemon → SQLite DB
                              ↓
                        JSONL Export (5s debounce)
                              ↓
                        Git commit/push (if enabled)

The daemon provides:

You can run without the daemon (--no-daemon) for simpler setups, but you’ll need explicit bd sync calls.

Dealing with Context Rot

If your agent forgets about Beads mid-session (which happens as context fills), you have a few options:

Kill sessions earlier. As Yegge notes, “you can just kill your agents after completing each issue. Beads helps agents easily find where they’re supposed to pick up again, so it’s easy to make your sessions throwaway.” If context rot is happening, your session is too long. One task, land the plane, kill it, start fresh.

Remind it. There’s no shame in saying “don’t forget to run bd sync” at the end. Beads is designed so that even when the agent forgets, the state survives.

Make CLAUDE.md / AGENTS.md instructions stickier:

CRITICAL: Track all work in beads. Before starting any task, run `bd ready`.
Before ending any session, run `bd sync`. File discovered work with `bd create`.

Use smaller tasks. If you’re hitting context rot, your tasks are probably too big. The recommended granularity: anything over ~2 minutes of work should be its own issue.

Database Maintenance

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

# Find compaction candidates (closed 30+ days)
bd compact --analyze --json

# Agent summarizes and compacts
bd compact --apply --id bd-42 --summary summary.txt

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

Regular maintenance:

bd doctor        # Health check
bd doctor --fix  # Auto-fix issues
bd cleanup       # Archive closed tasks

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. But the design optimizes for different concerns:

Why Beads favours near-term work:

Practical guidance:

The goal is keeping bd ready crisp and actionable. If your agent runs that command and gets back 47 items including “Research GraphQL federation (someday)” mixed with “Fix auth bug (blocking release),” you’ve lost the value.

Other cases where Beads isn’t the right tool:

The Community Tools Ecosystem

Here’s where Beads diverges sharply from traditional issue trackers: it’s designed like git, a powerful protocol and CLI, while leaving UI and integration to the community. 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.”

This isn’t a gap, it’s intentional architecture. 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)

For developers who live in the terminal, several options have emerged:

Web Interfaces

For teams that want visual dashboards:

Editor Integrations

Orchestration and Multi-Agent Tools

The most interesting development is how Beads has become infrastructure for multi-agent systems:

MCP Agent Mail by Jeffrey Emanuel (@Dicklesworthstone) provides agent-to-agent messaging. Combined with Beads for shared memory, agents can coordinate without human intervention. Yegge describes the pattern: “You just give them a task and tell them to go sort it out amongst themselves. There’s no ego, so they quickly decide on a leader and just split things up.”

beads-orchestration by @AvivK5498 is a multi-agent orchestration skill for Claude Code,. the orchestrator investigates issues, manages beads tasks, and delegates to tech-specific supervisors on isolated branches.

Gas Town is Yegge’s own orchestration layer (still in development) that adds concepts like “convoys” (bundles of beads assigned to agents) and “rigs” (workspace configurations).

The Protocol Advantage

This ecosystem exists because Beads chose the protocol approach:

Any developer can build on Beads because the interface is stable and well-documented. The community has responded with tools in Go, Rust, TypeScript, Node.js, Python, Lua, and Swift, each optimized for different workflows.

If your preferred UI doesn’t exist yet, you can build it!

The Honest Gaps

Beads is designed as passive infrastructure: it’s there when you use it, but doesn’t force itself into your workflow. This creates some friction you should know about:

Claude doesn’t proactively use it. You need to say “track this in beads” or “check bd ready.” The agent won’t spontaneously decide to file issues or check the backlog.

CLAUDE.md instructions fade. By session end, the agent is focused on the immediate task, not cleanup steps. “Land the plane” (sync, push, file remaining work) needs explicit prompting. The hooks help, but they’re not magic.

Session handoff is manual. You need to prompt “check bd ready” at session start. The tool provides memory, but you trigger its use.

Context rot still happens. Even with hooks installed, long sessions can drift. The agent that started by checking bd ready may forget about beads entirely by hour two. The fix: shorter sessions, more explicit prompting, or just accept that you’ll need to remind it.

Collaboration requires setup. The sync branch pattern works, but you need to configure it explicitly. Out of the box, issues travel with code branches, which may not be what you want.

Merge conflicts happen. JSONL is more merge-friendly than SQLite, but Beads is still “a crummy architecture (by pre-AI standards) that requires AI in order to work around all its edge cases where it breaks.” Yegge’s words, not mine. The good news: AI can always get it working.

The bottom line: Beads provides the memory. You provide the discipline to use it.

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?”

The answer:

Four kinds of dependencies chain issues together like beads on a string, making them easy for agents to follow for long distances and reliably perform complex task streams in the right order.

Getting Started Today

# Install
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Initialize
cd your-project
bd init

# For Claude Code users
bd setup claude

# Add to AGENTS.md or CLAUDE.md:
echo "Use 'bd' for task tracking. Run 'bd ready --json' to find work." >> AGENTS.md

# Create your first issue
bd create "My Feature" -t epic -p 1

Then start your next coding session with: “Check beads and pick up the highest priority task.”

Summary

The patterns that actually work:

  1. Think with prompts, capture in issues: Let investigation inform issue creation
  2. Issues are handoff points: Sessions can die, work persists
  3. Use bd ready as your “what next?”: Dependencies handle ordering
  4. Kill sessions freely: Fine-grained issues mean cheap sessions
  5. Be explicit: Beads is opt-in infrastructure, not automatic enforcement

Beads won’t solve context rot by magic. It’s a tool, not a cure. But it gives you something markdown plans never could: structured, queryable, dependency-aware memory that survives session boundaries and syncs through git.

The tool provides the memory. You provide the discipline.

Beads is open source at github.com/steveyegge/beads.