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
emma 4103785ef3 docs: update stale SQLite references to Dolt across 10 documentation files
Major updates:
- ARCHITECTURE.md: Rewrote three-layer model to two-layer (Dolt + JSONL),
  updated all diagrams, directory structure, and code paths
- FAQ.md: Updated database references, dependencies, corruption FAQ
- TROUBLESHOOTING.md: Updated database corruption recovery, locking advice
- WORKTREES.md: Updated directory structure and concurrency references
- MULTI_REPO_HYDRATION.md: Added deprecation notice (SQLite-era feature)
- daemon-summary.md: Added migration note

Path updates:
- PERFORMANCE_TESTING.md: sqlite → dolt benchmark paths
- ADAPTIVE_IDS.md: sqlite → dolt implementation paths
- INTERNALS.md: sqlite → dolt implementation paths
- SECURITY.md: SQLite → Dolt in dependency and storage references

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Executed-By: beads/crew/emma
Rig: beads
Role: crew
2026-02-16 01:22:58 -08:00
.agent/workflows fix: improve JSONL-only mode detection and error messages (GH #534) 2025-12-13 12:50:33 -08:00
.beads Initialize bd after merge 2026-02-06 15:31:55 -07:00
.beads-hooks Fix shebang env (#817) 2026-01-01 10:54:22 -08:00
.claude docs: update daemon CLI syntax from flags to subcommands 2026-01-14 21:47:15 -08:00
.claude-plugin chore: Bump version to 0.50.3 2026-02-14 18:30:09 -08:00
.devcontainer Fix devcontainer init check - look for DB file not directory 2025-11-05 17:31:30 -08:00
.github cleanup: remove stale sqlite refs, fix lint warnings, update Makefile benchmarks 2026-02-16 00:49:18 -08:00
claude-plugin chore: Bump version to 0.50.3 2026-02-14 18:30:09 -08:00
cmd/bd fix: dolt config tests corrupt rig metadata.json in worktree environments 2026-02-16 01:22:57 -08:00
docs docs: update stale SQLite references to Dolt across 10 documentation files 2026-02-16 01:22:58 -08:00
examples Dolt-native cleanup: remove legacy code, rename API, add server watchdog 2026-02-15 23:43:20 -08:00
integrations chore: Bump version to 0.50.3 2026-02-14 18:30:09 -08:00
internal fix: read Dolt database name from metadata.json in embedded mode (bd-pqn2e) 2026-02-16 01:18:40 -08:00
npm-package chore: Bump version to 0.50.3 2026-02-14 18:30:09 -08:00
scripts feat: add E2E test script for dolt git remote workflow (bd-v7ydv.2) 2026-02-12 10:20:08 -08:00
tests/integration refactor: Remove legacy MCP Agent Mail integration (bd-6gd) 2025-12-17 23:14:23 -08:00
website fix(docs): correct Homebrew upgrade command in upgrading docs 2026-02-14 18:14:33 +01:00
winget Add Windows ARM64 build support (#834) 2026-01-01 19:46:02 -08:00
.gitattributes fix(autoimport): auto-correct deleted status to tombstone for JSONL compatibility (#1231) 2026-01-21 21:50:38 -08:00
.gitignore feat: embed Windows PE version info to reduce antivirus false positives (bd-t4u1) 2026-02-06 17:51:11 -08:00
.golangci.yml cleanup: remove stale golangci suppressions and dead compact methods 2026-02-16 00:53:15 -08:00
.goreleaser.yml feat: embed Windows PE version info to reduce antivirus false positives (bd-t4u1) 2026-02-06 17:51:11 -08:00
.pre-commit-config.yaml refactor: remove unused bd pin/unpin/hook commands (bd-x0zl) 2025-12-27 16:02:15 -08:00
.test-skip fix: rewrite TestRepairMultiplePrefixes for Dolt rename semantics (bd-alk64) 2026-02-14 11:05:39 -08:00
AGENT_INSTRUCTIONS.md cleanup: remove stale sqlite refs, fix lint warnings, update Makefile benchmarks 2026-02-16 00:49:18 -08:00
AGENTS.md docs+tooling: standardize CGO test workflow and ICU setup 2026-02-10 10:56:12 -05:00
ARTICLES.md doc: create an ARTICLES.md for Articles & Tutorials about Beads (#1306) 2026-01-24 17:10:54 -08:00
beads.go Dolt-native cleanup: remove legacy code, rename API, add server watchdog 2026-02-15 23:43:20 -08:00
beads_test.go Dolt-native cleanup: remove legacy code, rename API, add server watchdog 2026-02-15 23:43:20 -08:00
BENCHMARKS.md docs: update stale sqlite references to dolt in key contributor docs 2026-02-16 00:56:29 -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.50.3 2026-02-14 18:30:09 -08:00
CONTRIBUTING.md docs: update stale sqlite references to dolt in key contributor docs 2026-02-16 00:56:29 -08:00
default.nix chore: Bump version to 0.50.3 2026-02-14 18:30:09 -08:00
FEDERATION-SETUP.md docs: add federation setup guide (bd-wkumz.7) 2026-01-20 23:13:31 -08:00
flake.lock fix(nix): update flake.lock, remove CI workaround 2026-02-07 21:52:33 -05:00
flake.nix feat: add 'beads' alias for bd command during installation 2026-02-04 15:19:00 +00:00
go.mod refactor: delete daemon/RPC layer and internal/rpc/ package (-19,663 lines) 2026-02-10 12:10:24 -08:00
go.sum refactor: delete daemon/RPC layer and internal/rpc/ package (-19,663 lines) 2026-02-10 12:10:24 -08:00
install.ps1 Merge pull request #1496 from maphew/fix/1409-build-deps-docs 2026-02-05 08:44:05 -08:00
LICENSE Initial commit: Beads issue tracker with security fixes 2025-10-11 20:07:36 -07:00
Makefile cleanup: remove stale sqlite refs, fix lint warnings, update Makefile benchmarks 2026-02-16 00:49:18 -08:00
NEWSLETTER.md docs: add v0.49.6 release newsletter 2026-02-07 22:03:23 -08:00
README.md Add Dolt GitHub link to README 2026-02-13 15:02:18 -08:00
RELEASING.md fix: correct brew commands and remove dead homebrew CI job 2026-02-09 08:02:42 +01:00
SECURITY.md docs: update stale SQLite references to Dolt across 10 documentation files 2026-02-16 01:22:58 -08: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, git-backed graph issue tracker for AI agents.

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 and native branching. JSONL maintained for git portability.
  • 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.

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.

📝 Documentation