How to use beads: install bd, set up agents and track work

What beads is and who it is for

Beads provides persistent memory for coding agents. It replaces messy markdown plans with a dependency-aware graph so an agent can work through long, multi-step tasks without losing context.

It fits developers who run agents such as Claude Code or Codex on multi-step projects, and teams that want agents and humans to share one task list across machines or branches. It is more than most people need for a simple personal to-do list.

• Good fit: multi-step agent work, shared task lists across machines, planning kept out of pull requests.
• Poor fit: a simple personal to-do list, or teams that cannot run a CLI tool or manage schema upgrades across clones.

Install the bd CLI

Beads is a CLI tool you install once and use everywhere. The README recommends Homebrew on macOS and Linux, and offers npm for Node.js users. You do not need to clone the repository into your project.

The README lists platforms as macOS, Linux, Windows and FreeBSD. It also lists other methods, including an install script, go install, building from source, and an Arch AUR package, all documented in the installation guide.

Initialize beads in your project

Change into your project directory and run bd init. By default this creates or updates AGENTS.md so agents can discover the beads workflow, and it installs the project Claude Code, Codex and Cursor integrations unless you pass --skip-agents or --stealth.

Data is stored in .beads/. With the default embedded mode, Dolt runs in-process and data lives in .beads/embeddeddolt/.

• Use bd init --stealth to use beads locally without committing files to the main repo.
• Use bd init --contributor on a fork to route planning issues to a separate repo, such as ~/.beads-planning, so experimental work stays out of PRs.
• Use bd init --server to connect to an external dolt sql-server for multiple concurrent writers.

Connect your coding agent

For supported agents, you can run bd setup with the matching name. Run bd setup --list to see all supported integrations.

If your agent is not covered, the README suggests adding a short AGENTS.md section that points the agent at bd prime, bd ready, bd show, bd update --claim and bd close, and tells it not to use markdown TODO lists for task tracking.

• bd setup codex installs a skill, AGENTS.md guidance and hooks.
• bd setup claude installs hooks and settings.
• bd setup factory creates or updates AGENTS.md.
• Run bd onboard to print a snippet for agents that are not supported.

Use the core commands: create, ready, claim, close

Tasks are called issues or beads. bd ready lists tasks with no open blockers. An agent claims work with bd update --claim, which sets the assignee and marks the task in progress. When the work is done, bd close releases any blockers that depended on it.

Priority is set with -p, where 0 is the highest. You can link tasks with bd dep add, and bd show displays details and the audit trail. Use bd remember to store durable project facts that bd prime injects later.

• bd create "Title" -p 0 creates a P0 task.
• bd dep add <child> <parent> links tasks as blocks, related or parent-child.
• bd prime prints agent workflow context and persistent memories.

Sync across machines and understand the storage

Cross-machine sync uses bd dolt push and bd dolt pull against refs/dolt/data on your git remote. The README notes that .beads/issues.jsonl is an export for viewers and interchange, not the source of truth or a backup.

Before upgrading, the README advises syncing remote-backed databases with your current bd, backing up with bd export --all, upgrading the binary, then running bd info --whats-new, bd hooks install and bd version. Back up and migrate between storage modes with bd backup.

• Hierarchical IDs such as bd-a3f8, bd-a3f8.1 and bd-a3f8.1.1 model epics, tasks and sub-tasks.
• Hash-based IDs are meant to prevent merge collisions across branches and agents.
• Verify downloaded binaries against the release checksums.txt before first run.