Beads
Git-friendly graph issue tracker for AI coding agents, built to keep long-horizon Codex, Claude Code, and Cursor work from losing context
What is Beads
Beads, usually invoked as bd, is a distributed graph issue tracker built for AI coding agents. It is not just another TODO app. It stores tasks, dependencies, blockers, and decision context as structured issues so agents can resume long-horizon development without rebuilding the plan from scratch.
The strongest use case is multi-day coding work: several files, several dependent subtasks, multiple agents, or frequent context switches. Markdown plans drift. Beads turns the work into a task graph that a future agent can inspect before continuing.
The strongest use case is multi-day coding work: several files, several dependent subtasks, multiple agents, or frequent context switches. Markdown plans drift. Beads turns the work into a task graph that a future agent can inspect before continuing.
Why it fits AI coding agents
The main failure mode of AI coding agents is not syntax. It is losing the project state: what has already been done, what is blocked, and why one task must happen before another. Beads moves that state out of the chat transcript and into a repo-local structured task system.
For Codex CLI, Claude Code, Cursor, and OpenClaw-style workflows, Beads can act as a task memory layer. The agent still writes the code; bd records the plan, dependencies, and handoff state.
For Codex CLI, Claude Code, Cursor, and OpenClaw-style workflows, Beads can act as a task memory layer. The agent still writes the code; bd records the plan, dependencies, and handoff state.
Quick start
The basic flow is: install the bd CLI once, then run bd init inside your own project. You can then run setup commands such as bd setup codex or bd setup claude to install agent-facing workflow instructions.
Typical flow: install script → cd your-project → bd init → bd setup codex. Do not clone the Beads repository into your app. It is a system-level CLI that initializes task tracking inside your project.
Typical flow: install script → cd your-project → bd init → bd setup codex. Do not clone the Beads repository into your app. It is a system-level CLI that initializes task tracking inside your project.
Who should use Beads
Use Beads if you frequently code with agents, run multi-day projects, collaborate across agents or humans, or want task state to live in the repository instead of AGENTS.md, TODO.md, or chat history.
Skip it for tiny one-off edits, teams that do not use coding agents, or organizations that already require Linear/Jira as the single source of truth and do not want repo-local task state.
Skip it for tiny one-off edits, teams that do not use coding agents, or organizations that already require Linear/Jira as the single source of truth and do not want repo-local task state.
Alternatives and when to choose them
GitHub Issues is better for public projects and human collaboration. Linear is better for product planning. Task Master AI is closer to AI-generated task breakdowns. Markdown TODOs are the lightest option, but they become messy quickly.
Beads wins when the main operator is an AI coding agent. It prioritizes dependency graphs, ready/blocking state, and repo-local sync. Our recommendation: use Beads for personal or small-team AI development projects; keep GitHub Issues or Linear for external roadmaps.
Beads wins when the main operator is an AI coding agent. It prioritizes dependency graphs, ready/blocking state, and repo-local sync. Our recommendation: use Beads for personal or small-team AI development projects; keep GitHub Issues or Linear for external roadmaps.