Beads
The bd issue tracker with a dependency graph on Dolt: long-term memory and a work plan for agents instead of Markdown lists
Install
brew install beads
cd your-project
bd initAlternative: npm install -g @beads/bd.
This is third-party code. Review the repository files before installing.
What it does
Beads stores project tasks in a versioned Dolt SQL database and links them with dependencies, so the agent can see what is ready to pick up. bd ready lists work with no open blockers, bd update --claim assigns a task to the agent, and bd close finishes it and unblocks dependents. Hash-based IDs avoid collisions when several agents and branches work in parallel. Old closed tasks are compacted into short summaries, and bd remember saves project knowledge that bd prime feeds to the agent at session start.
Who it is for. For developers who run long multi-session tasks with agents or several agents in parallel.
Good fit when
- The agent loses the plan between sessions
- Several agents work on one project and need to share tasks
- You want task history and project knowledge next to the code
Not a fit when
- The team already tracks work in Jira, Linear or another tracker and does not want a second system
- Short one-off tasks where the plan fits in one session
Example request
Break the migration into beads tasks with dependencies and claim the first ready oneLimitations
Storage is Dolt: the default mode has a single writer, concurrent writers need a separate dolt sql-server. Upgrades across schema versions on a shared database require the steps from the upgrade guide. bd init edits AGENTS.md and installs Claude and Codex integrations by default, which --skip-agents or --stealth turn off.
How to disable. Remove the beads section from AGENTS.md and the hooks added by bd setup, then uninstall with brew uninstall beads or npm uninstall -g @beads/bd. Data lives in the project's .beads folder.
Security check
- Edits AGENTS.md and installs agent hooks in the project
- Syncs the task database with a git remote
README in short
The README describes beads as a distributed issue tracker for agents built on Dolt. Install via Homebrew, npm, a script or go install, then run bd init in the project and bd setup for your agent. It lists core commands, hierarchical IDs for epics, storage modes, sync and git-free usage. It also covers binary checksum verification and the schema version guard. MIT licensed.
FAQ
Is git required?
No. With BEADS_DIR and --stealth beads runs without git, keeping the Dolt database separate.
How do I sync tasks across machines?
With bd dolt push and bd dolt pull against the same git remote. issues.jsonl is an export, not a backup.
Related
Open-source personal AI assistant on your own machine: answers in Telegram, Slack, Discord and WhatsApp, extended with skills and plugins
A self-improving agent from Nous Research with a TUI, messaging gateway, cron jobs and skills it writes itself
Anthropic's coding agent for the terminal, IDE and GitHub: understands your codebase, runs tasks and handles git
OpenAI's coding agent that runs locally in your terminal, with IDE and desktop versions