- Category
- AI Agents
- Rank
- No. 107Tools index
- Pricing
- Open Source
- Type
- TOOL
- Use case
- Agent Building
- Interfaces
- CLI · Desktop · API
- Builder
- @steveyegge
- GitHub
- 27.4k stars
- Latest release
- v1.3.1-rc.1
- Date
About
A distributed graph issue tracker designed for AI coding agents that provides persistent, structured memory using a dependency-aware graph. It replaces messy markdown plans and allows agents to handle long-horizon tasks without losing context.
What it does
Beads turns project work into a database-backed queue that agents can operate directly. Teams create issues, connect blockers and related work, then ask for tasks whose prerequisites are complete. Agents can atomically claim those tasks, record discoveries and memories, and close finished work. Dolt supplies versioned history, branching, merges, and remote synchronization across machines.
Why it's ranked here
Beads is unusually serious about coordination, not merely task capture. Atomic claims, collision-resistant identifiers, automatic ready-work detection, cross-repository dependencies, audit history, and schema guards address concrete failure modes in multi-agent work. The cost is operational weight: Dolt storage, migrations, synchronization procedures, and build constraints demand more care than a text checklist.
What's good
Dependency state drives the work queue, so closing a blocker can release the next task automatically. Hash-based identifiers reduce collisions across branches and agents. JSON output supports automation, while atomic claiming limits duplicate work. Reusable formulas can instantiate dependency-ordered workflows. Persistent memories return through agent context, and old closed work can be compacted to reduce context use.
Tradeoffs
The default embedded database permits only one writer, so concurrent writers require an external Dolt server. Remote-backed upgrades can require backups, schema migration by one designated clone, synchronization, and bootstrapping elsewhere. Building from source requires CGO and a specific pure-Go regex build tag. The exported JSONL data is neither the source of truth nor a backup. Graphical interfaces mainly come from separate community projects.
How to use it well
Use Beads when coding agents share long-running, dependency-heavy work across sessions, branches, machines, or repositories. Start with the embedded mode for one writer, then adopt server mode only when simultaneous writes justify it. Feed agents JSON, claim ready work atomically, record discoveries as linked issues, and synchronize Dolt deliberately. Keep a separate recall system for durable design decisions and rationale, because Beads primarily answers what work should happen next.
Technical notes+
README.md defines embedded Dolt at .beads/embeddeddolt/ and server-backed storage at .beads/dolt/, with refs/dolt/data used for remote synchronization. go.mod declares module github.com/steveyegge/beads, Go 1.26.5, Cobra, Viper, Dolt drivers, OpenTelemetry, SQL mocks, and testcontainers. Makefile builds ./cmd/bd with CGO enabled and the gms_pure_go tag, and includes regression, migration, cross-version, package, and OpenAPI drift checks. internal/httpapi/server.go implements the v0 HTTP service with bounded connections, request deadlines, stalled-write protection, optional bearer authentication, loopback-oriented defaults, and explicit non-loopback safeguards. docs/CLI_REFERENCE.md documents the broad command surface, while docs/reference/index.md identifies a stable JSON output contract and an events journal for external tooling.
Observed
- Primary language
- Go, declared by go.mod and used to build the bd binary.
- Install surface
- Homebrew, npm global package, install script, Go installation, source builds, Windows instructions, and Arch AUR are documented.
- Interfaces
- Command-line interface with JSON output, plus a versioned HTTP API implemented in the repository.
- Platform support
- macOS, Linux, Windows, and FreeBSD.
- Storage
- Dolt database with embedded single-writer and external-server multi-writer modes.
- Automation contract
- The documentation describes stable JSON output and a durable events journal for external tooling.
Read from README.md, go.mod, Makefile, internal/httpapi/server.go, docs/index.md, docs/RECOVERY.md, docs/CLI_REFERENCE.md, docs/community-tools.md, docs/related-projects.md, docs/recovery/index.md, docs/reference/index.md, docs/workflows/index.md, docs/cli-reference/gc.md, docs/cli-reference/kv.md, docs/multi-agent/index.md.
What it can do
Track issues in a distributed graph structure
Issue data and dependencies → Structured graph of interconnected issues
Store persistent memory for AI coding agents
Agent context and task information → Persistent structured memory storage
Replace markdown plans with dependency-aware graphs
Unstructured markdown planning documents → Structured dependency graph representation
Handle long-horizon tasks without losing context
Complex multi-step coding tasks → Maintained task context and progress tracking
Maintain dependency relationships between tasks
Tasks and their interconnections → Dependency-aware task graph
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.