A version-controlled brain for coding agents

What it does

Beads is a CLI issue tracker that stores tasks in a Dolt SQL database instead of markdown files. It gives coding agents like Claude Code and Codex a persistent, structured memory layer with dependency tracking, hierarchical epics, and atomic task claiming. The tool installs once system-wide and hooks into agents via auto-generated instruction files and shell integration.

The interesting bit

The backend is Dolt—essentially Git for data—so you get cell-level merges, native branching, and remote sync without building it yourself. Hash-based IDs are designed specifically to prevent merge collisions when multiple agents or branches touch the same task graph, and an old-task compaction feature semantically summarizes closed work to keep the agent’s context window from bloating.

Key highlights

• Runs fully offline in embedded mode or connects to an external Dolt server for multi-agent concurrency
• Works without Git for non-Git VCSs, monorepo subdirectories, or CI pipelines via environment-directed storage
• Stealth mode keeps local planning files out of the upstream repository
• Graph relationships include blocking, duplication, supersession, and threaded replies
• Built-in onboarding for Claude, Codex, Cursor, Factory.ai, and others

Caveats

• Embedded mode enforces single-writer file locking, so concurrent local agents will bottleneck
• JSONL exports are not restorable database backups; full restoration requires the native backup facility or manual Dolt intervention
• Unix socket server mode requires manually starting the Dolt server first; auto-start is not supported

Verdict

Try it if your AI assistant keeps losing track of multi-step refactors or polluting repos with stale TODO markdown. Pass if your workflow is already simple enough that a plain text checklist never lies to you.