Beads FAQs

Question 1

What is Beads (bd) and how does it help coding agents?

Accepted Answer

Beads is a lightweight, graph-based issue tracker designed to serve as a memory system for AI coding agents. It empowers agents with long-term planning capabilities, helps them manage complex task streams, and prevents 'amnesia' by automatically tracking discovered work, ensuring no problems are silently passed over.

Question 2

What are the key benefits of using Beads with AI agents?

Accepted Answer

Beads offers zero setup, four types of dependency tracking to chain issues, automatic detection of ready-to-work issues, and agent-friendly JSON output for programmatic integration. It transforms how agents handle multi-session tasks, improving organization, focus, and auditability.

Question 3

How does Beads manage its database across multiple machines?

Accepted Answer

Beads employs a unique distributed design. It uses project-local SQLite caches for fast operations, while Git-versioned JSONL records act as the source of truth. This allows agents on different machines to share what feels like a single, centralized database, with Git handling synchronization and AI assisting with merge conflicts.

Question 4

Is Beads designed for human use or AI agent use?

Accepted Answer

While humans can use Beads to query and review issues (e.g., `bd list`, `bd ready`), it is primarily designed for AI coding agents to use on your behalf. Agents automatically file, manage, and reason about issues, integrating seamlessly into their workflow to enhance productivity.

Question 5

How do I install and onboard Beads for my coding agent?

Accepted Answer

You can install Beads via Homebrew, a quick install script, or manually. To onboard, run `bd init` in your project, then add an instruction like `echo "BEFORE ANYTHING ELSE: run 'bd onboard' and follow the instructions" >> AGENTS.md`. Your agent will then self-configure and integrate Beads into your project's documentation.

Beads

About

Key Features

Use Cases