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
beads/crew/lydia 7cc793f919 build: add //go:build cgo tags to all test files and extract migrate helpers
All cmd/bd tests depend on the Dolt storage backend which requires CGO
(for ICU). Gate tests behind cgo build tag so they cleanly skip when
CGO is unavailable rather than failing at link time.

Extract listDoltMigrations() into build-tag-conditional helpers
(migrate_helpers_cgo.go / migrate_helpers_nocgo.go) so migrate.go
compiles without CGO.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-10 13:19:22 -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 release: v0.49.6 2026-02-07 22:01:18 -08:00
.devcontainer Fix devcontainer init check - look for DB file not directory 2025-11-05 17:31:30 -08:00
.github Merge pull request #1622 from PabloLION/fix/brew-naming-docs-ci 2026-02-09 11:28:47 -08:00
claude-plugin fix: correct brew commands and remove dead homebrew CI job 2026-02-09 08:02:42 +01:00
cmd/bd build: add //go:build cgo tags to all test files and extract migrate helpers 2026-02-10 13:19:22 -08:00
docs Merge pull request #1660 from davidahmann/codex/issue-1466-detect-stale-hooks 2026-02-10 12:24:38 -08:00
examples docs: update daemon CLI syntax from flags to subcommands 2026-01-14 21:47:15 -08:00
integrations chore(deps): bump fastmcp in /integrations/beads-mcp 2026-02-09 23:40:25 +00:00
internal build: add //go:build cgo tags to all test files and extract migrate helpers 2026-02-10 13:19:22 -08:00
npm-package release: v0.49.6 2026-02-07 22:01:18 -08:00
scripts docs+tooling: standardize CGO test workflow and ICU setup 2026-02-10 10:56:12 -05:00
tests/integration refactor: Remove legacy MCP Agent Mail integration (bd-6gd) 2025-12-17 23:14:23 -08:00
website Merge pull request #1622 from PabloLION/fix/brew-naming-docs-ci 2026-02-09 11:28:47 -08: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 fix(release): bump missed version files, fix lint and formatting 2026-02-07 20:37:26 -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 chore: code health review - test fix and error comments (bd-9g1z, bd-ork0) 2025-12-22 21:30:57 -08:00
AGENT_INSTRUCTIONS.md Merge pull request #1660 from davidahmann/codex/issue-1466-detect-stale-hooks 2026-02-10 12:24:38 -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 feat: delete SQLite storage backend (Phase 2 of Dolt transition) 2026-02-10 12:23:15 -08:00
beads_test.go bd-6xd: Standardize on issues.jsonl as canonical filename 2025-11-26 22:02:59 -08:00
BENCHMARKS.md feat(cli): add 'bd thanks' command to thank contributors 2025-12-14 12:40:32 -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 release: v0.49.6 2026-02-07 22:01:18 -08:00
CONTRIBUTING.md docs: add Docker trick for updating flake.lock without nix 2026-02-07 21:54:03 -05:00
default.nix revert: restore original Nix vendorHash (Go version too old in nixpkgs) 2026-02-07 23:23:08 -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 Merge pull request #1660 from davidahmann/codex/issue-1466-detect-stale-hooks 2026-02-10 12:24:38 -08:00
NEWSLETTER.md docs: add v0.49.6 release newsletter 2026-02-07 22:03:23 -08:00
README.md docs: update documentation for Dolt transition, remove SQLite/daemon references 2026-02-10 11:56:16 -08:00
RELEASING.md fix: correct brew commands and remove dead homebrew CI job 2026-02-09 08:02:42 +01:00
SECURITY.md Prepare for public launch: comprehensive examples, docs, and tooling 2025-10-12 11:25:29 -07: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