Beads - A memory upgrade for your coding agent https://beads.gascity.com
  • Go 95.2%
  • Python 1.6%
  • Starlark 1.5%
  • Shell 1.3%
  • Rust 0.2%
Find a file
human fca3d3cd47 fix: complete UUID primary keys cleanup across codebase
Follow-up to 1ce765ee (UUID primary keys for federation-safe events).
The core migration changed types and schema, but many files still
referenced the old AUTO_INCREMENT design. This commit makes the
codebase internally consistent:

- Update embedded Dolt schema SQL files to use CHAR(36) UUID PKs
- Fix backup restore: json.Number -> string for UUID event/comment IDs
  (fixes TestBackupRestoreRoundTrip)
- Remove dead LastEventID field from backup state (never set)
- Update comments in issueops/create.go, import test, git_remote_test
- Update docs/audit-sync-mode-complexity.md (mark auto-increment resolved)
- Update version history in info.go

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-14 10:12:04 -07:00
.agent/workflows docs: replace bd sync with bd dolt push/pull in agent instructions (GH#2563) 2026-03-13 11:01:06 -07:00
.claude feat: add PreToolUse hook to block interactive cp/mv/rm prompts (bd-tm2p) 2026-02-27 16:16:24 -08:00
.claude-plugin chore: bump version to 0.60.0 2026-03-11 20:53:41 -07:00
.devcontainer chore(deps): update mcr.microsoft.com/devcontainers/go docker tag to v2 (#1990) 2026-02-22 15:23:54 -08:00
.githooks fix: detect Go version mismatch in pre-commit hook before golangci-lint panics (bd-66nc) 2026-03-02 18:50:29 -08:00
.github Merge PR #2567: fix(embeddeddolt): implement more storage methods 2026-03-13 17:28:30 -07:00
claude-plugin docs: replace "git-backed" with "Dolt-powered", add git-free usage guide 2026-03-13 11:44:50 -07:00
cmd/bd fix: complete UUID primary keys cleanup across codebase 2026-03-14 10:12:04 -07:00
docs fix: complete UUID primary keys cleanup across codebase 2026-03-14 10:12:04 -07:00
examples fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522) 2026-03-11 13:25:40 -07:00
integrations chore: bump version to 0.60.0 2026-03-11 20:53:41 -07:00
internal fix: complete UUID primary keys cleanup across codebase 2026-03-14 10:12:04 -07:00
npm-package docs: replace "git-backed" with "Dolt-powered", add git-free usage guide 2026-03-13 11:44:50 -07:00
scripts docs: replace "git-backed" with "Dolt-powered", add git-free usage guide 2026-03-13 11:44:50 -07:00
tests cleanup: remove daemon infrastructure remnants (GH#2431) 2026-03-10 15:24:27 -07:00
website docs: replace "git-backed" with "Dolt-powered", add git-free usage guide 2026-03-13 11:44:50 -07:00
winget docs: replace "git-backed" with "Dolt-powered", add git-free usage guide 2026-03-13 11:44:50 -07:00
.gitattributes fix: remove JSONL gitignore rules, merge driver, and issues tracking check (bd-9ni.6) 2026-02-22 21:50:17 -08:00
.gitignore cleanup: remove remaining daemon references missed by GH#2431 2026-03-10 15:34:20 -07:00
.golangci.yml fix(ci): resolve remaining CI test and lint failures 2026-02-17 22:55:54 +00:00
.goreleaser.yml fix(release): use brews instead of homebrew_casks for formula publishing 2026-02-28 23:50:20 -08:00
.pre-commit-config.yaml fix: detect Go version mismatch in pre-commit hook before golangci-lint panics (bd-66nc) 2026-03-02 18:50:29 -08:00
.test-skip fix: rewrite TestRepairMultiplePrefixes for Dolt rename semantics (bd-alk64) 2026-02-14 11:05:39 -08:00
AGENT_INSTRUCTIONS.md fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522) 2026-03-11 13:25:40 -07:00
AGENTS.md docs: teach agents to use stdin for descriptions (GH#1376) 2026-02-28 21:34:14 -07:00
ARTICLES.md fix(docs): remove stale --branch flag and SQLite refs from QUICKSTART (GH#2522) (#2525) 2026-03-11 12:54:30 -07:00
beads.go fix: guard CREATE DATABASE to prevent shadow databases on wrong server 2026-02-28 13:29:51 -05:00
beads_test.go feat: add --list and --doc flags to bd help for CLI doc generation (GH#2527) 2026-03-11 18:25:40 -07:00
BENCHMARKS.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
build-docs.md fix: correct brew commands and remove dead homebrew CI job 2026-02-09 08:02:42 +01:00
CHANGELOG.md chore: bump version to 0.60.0 2026-03-11 20:53:41 -07:00
CLAUDE.md chore: Bump version to 0.55.2 2026-02-20 09:00:55 -08:00
codecov.yml ci: add Codecov integration with component-based coverage tracking 2026-02-18 20:00:01 -08:00
CONTRIBUTING.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
default.nix fix(flake): override go_1_25 and fix vendorHash 2026-03-13 19:24:43 +00:00
FEDERATION-SETUP.md Remove stale sync mode documentation 2026-03-04 12:52:24 -05:00
flake.lock feat(nix): modernize flake for nixpkgs-25.11, fix-merge PR #2314 2026-03-03 17:24:10 -08:00
flake.nix fix(flake): override go_1_25 and fix vendorHash 2026-03-13 19:24:43 +00:00
go.mod feat: UUID primary keys for federation-safe events 2026-03-13 19:02:50 -07:00
go.sum fix(deps): update github.com/dolthub/driver digest to 669bd7f 2026-03-12 00:46:50 +00:00
install.ps1 fix: qualify Expand-Archive to avoid Pscx module conflict on Windows (#1826) 2026-02-17 21:16:05 -08:00
LICENSE Initial commit: Beads issue tracker with security fixes 2025-10-11 20:07:36 -07:00
Makefile fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522) 2026-03-11 13:25:40 -07:00
NEWSLETTER.md chore: bump version to 0.60.0 2026-03-11 20:53:41 -07:00
packages.nix feat(nix): modernize flake for nixpkgs-25.11, fix-merge PR #2314 2026-03-03 17:24:10 -08:00
README.md docs: replace "git-backed" with "Dolt-powered", add git-free usage guide 2026-03-13 11:44:50 -07:00
RELEASING.md docs: remove stale daemon references from all documentation (GH#1982) 2026-02-22 17:57:53 -08:00
renovate.json Add renovate.json 2026-02-19 04:00:32 +00:00
SECURITY.md docs: add network/privacy section to SECURITY.md 2026-03-04 11:21:29 +01:00
THIRD_PARTY_LICENSES revert: restore embedded Dolt mode (was only supposed to be removed from Gas Town) 2026-02-07 21:21:24 -08:00

bd - Beads

Distributed graph issue tracker for AI agents, powered by Dolt.

Platforms: macOS, Linux, Windows, FreeBSD

License Go Report Card Release npm version PyPI

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

⚡ Quick Start

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Tell your agent
echo "Use 'bd' for task tracking" >> AGENTS.md

Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

🛠 Features

  • Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
  • Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
  • Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
  • Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
  • Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.
  • Graph Links: relates_to, duplicates, supersedes, and replies_to for knowledge graphs.

📖 Essential Commands

Command Action
bd ready List tasks with no open blockers.
bd create "Title" -p 0 Create a P0 task.
bd update <id> --claim Atomically claim a task (sets assignee + in_progress).
bd dep add <child> <parent> Link tasks (blocks, related, parent-child).
bd show <id> View task details and audit trail.

🔗 Hierarchy & Workflow

Beads supports hierarchical IDs for epics:

  • bd-a3f8 (Epic)
  • bd-a3f8.1 (Task)
  • bd-a3f8.1.1 (Sub-task)

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects. See Git-Free Usage below.

Contributor vs Maintainer: When working on open-source projects:

  • Contributors (forked repos): Run bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.
  • Maintainers (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.

📦 Installation

  • npm: npm install -g @beads/bd
  • Homebrew: brew install beads
  • Go: go install github.com/steveyegge/beads/cmd/bd@latest

Requirements: Linux, FreeBSD, macOS, or Windows.

🌐 Community Tools

See docs/COMMUNITY_TOOLS.md for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

🚀 Git-Free Usage

Beads works without git. The Dolt database is the storage backend — git integration (hooks, repo discovery, identity) is optional.

# Initialize without git
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# All core commands work with zero git calls
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"

BEADS_DIR tells bd where to put the .beads/ database directory, bypassing git repo discovery. --stealth sets no-git-ops: true in config, disabling all git hook installation and git operations.

This is useful for:

  • Non-git VCS (Sapling, Jujutsu, Piper) — no .git/ directory needed
  • Monorepos — point BEADS_DIR at a specific subdirectory
  • CI/CD — isolated task tracking without repo-level side effects
  • Evaluation/testing — ephemeral databases in /tmp

For daemon mode without git, use bd daemon start --local (see PR #433).

📝 Documentation