Skip to content
Get packs

Beads

A local issue tracker that gives coding agents a persistent, dependency-aware task memory.

GitHub Download v1.3.2
Stars
28.4k
Forks
1.9k
Licence
MIT
Language
Go
Last update
4 days ago
Type
Dev tool

What it is

Beads (the `bd` command) stores tasks as a graph of linked issues in a version-controlled database powered by Dolt. Coding agents use it in place of loose markdown TODO lists so they can keep track of long, multi-step work without losing context. It can also sync between machines through a Git remote.

  • Have an agent list unblocked work with `bd ready` and claim a task with `bd update <id> --claim`
  • Break an epic into hierarchical tasks such as bd-a3f8, bd-a3f8.1 and bd-a3f8.1.1
  • Store durable project facts with `bd remember` so they are injected by `bd prime` later
  • Link related, duplicate or superseding issues to build a simple knowledge graph

Great for

  • Developers who run coding agents such as Claude Code or Codex on multi-step projects
  • Teams that want agents and humans to share one task list across machines or branches
  • Developers who want agent memory stored in the project rather than in chat history
  • People who work on open-source projects as a contributor or maintainer and want planning kept separate from PRs

Not ideal for

  • People who only want a simple to-do list for themselves; the README describes a graph database with sync, which is more than that needs
  • Teams that cannot run a CLI tool or manage database schema upgrades across clones, since the README stresses careful upgrade steps for shared databases
  • Users of agents not covered by `bd setup` who are unwilling to hand-edit AGENTS.md instructions
Step-by-step guide: how to use BeadsInstall, first run, examples, tips and FAQs

How to get it

  1. 1

    Install with a package manager

    Install the bd CLI with Homebrew (macOS / Linux, recommended)

    brew install beads

    Install with npm (Node.js users)

    npm install -g @beads/bd

    Initialize beads in your project

    cd your-project && bd init
  2. 2

    Run it

    • Install the bd CLI using one of the methods in the README
    • Run `bd init` inside your project directory
    • Optionally run `bd setup claude`, `bd setup codex` or another supported setup command for your agent
    • Try `bd ready` to list tasks, then `bd create "Title" -p 0` to add one
  3. 3

    Get the most out of it

    • Run `bd prime` at the start of an agent session to load workflow context and stored memories
    • Use `bd init --stealth` to keep beads local without committing files to the main repo
    • Use hierarchical IDs such as bd-a3f8.1 to organize epics into tasks and sub-tasks
    • Use `bd dolt push` and `bd dolt pull` to sync between machines through your git remote

Downloads

Source code (.zip)main branch · straight from GitHubRelease v1.3.28 files incl. beads_1.3.2_windows_arm64.zipOfficial website & docsbeads.gascity.com

Strengths

  • Dependency tracking and ready-task detection help agents pick the next valid piece of work
  • Hash-based IDs are designed to avoid merge collisions across branches and agents
  • Local-first embedded mode with an optional stealth mode that avoids committing files to the main repo

Trade-offs

  • Depends on Dolt and a schema that changes between versions, so binaries and databases must be kept in sync
  • The README's upgrade guidance is detailed and multi-step for remote-backed databases
  • Some features, such as compaction and messaging, are described only briefly in the README

How it compares

ProjectStarsTypeLevelUpdatedBest for
beads (this)28.4kDev toolintermediate4 days agoDevelopers who run coding agents such as Claude Code or Codex on multi-step projects
ECC295kDev toolintermediate4 days agoDevelopers who already use Claude Code and want a shared workflow for planning, testing and review
Understand-Anything89.7kDev toolbeginner11 days agoDevelopers joining a new team who need to learn an unfamiliar codebase
ruflo80.6kDev toolintermediate4 days agoDevelopers already using Claude Code or Codex who want multiple agents working together
get-shit-done64.2kDev toolintermediate5 months agoDevelopers who already use Claude Code and want to find the current GSD project
agentic-awesome-skills49kDev toolintermediate4 days agoDevelopers using Codex or Claude who want agent-chosen instructions for a project

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.