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
Peter Chanthamynavong bec44d85a1
fix(install): stop existing daemons before binary replacement (#945)
Stop existing daemons before binary replacement during install

Prevents file lock race condition by gracefully stopping bd daemons
before replacing the binary. Safe for fresh installs (skips if bd not found).
2026-01-07 20:45:37 -08:00
.agent/workflows fix: improve JSONL-only mode detection and error messages (GH #534) 2025-12-13 12:50:33 -08:00
.beads Revert "fix(formula): add dev path to local-install and clarify bump-version.sh (bd-z8xz)" 2026-01-07 00:46:48 -08:00
.beads-hooks Fix shebang env (#817) 2026-01-01 10:54:22 -08:00
.claude feat: add /handoff slash command for user invocation (bd-xwvo) 2026-01-02 17:32:23 -08:00
.claude-plugin chore: Bump version to 0.46.0 2026-01-06 23:51:29 -08:00
.devcontainer Fix devcontainer init check - look for DB file not directory 2025-11-05 17:31:30 -08:00
.github fix(ci): restore Windows smoke tests instead of full test suite 2026-01-06 19:34:34 -08:00
cmd/bd fix(hooks): add --no-daemon to git hook sync commands (bd-tyyn) (#948) 2026-01-07 20:45:33 -08:00
commands Update link to install script (#867) 2026-01-03 12:53:58 -08:00
docs docs: add lazybeads to community tools (#951) 2026-01-07 20:44:34 -08:00
examples Update link to install script (#867) 2026-01-03 12:53:58 -08:00
integrations chore: Bump version to 0.46.0 2026-01-06 23:51:29 -08:00
internal feat(linear): add project_id filter for sync (#938) 2026-01-07 20:45:00 -08:00
npm-package chore: Bump version to 0.46.0 2026-01-06 23:51:29 -08:00
scripts fix(install): stop existing daemons before binary replacement (#945) 2026-01-07 20:45:37 -08:00
skills/beads docs(skill): restructure for progressive disclosure pattern (#857) 2026-01-02 12:39:45 -08:00
tests/integration refactor: Remove legacy MCP Agent Mail integration (bd-6gd) 2025-12-17 23:14:23 -08:00
website docs: update skill names from /bd-* to /beads:* (#862) 2026-01-02 17:07:49 -08:00
winget Add Windows ARM64 build support (#834) 2026-01-01 19:46:02 -08:00
.gitattributes bd-6xd: Standardize on issues.jsonl as canonical filename 2025-11-26 22:02:59 -08:00
.gitignore feat: add --notes flag to bd create command (GH#830) 2026-01-01 10:53:59 -08:00
.golangci.yml fix(lint): add rename_prefix.go to G304 exclusions 2026-01-06 19:15:27 -08:00
.goreleaser.yml feat: add native Android/Termux binary support (#887) 2026-01-05 20:06:25 -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 refactor: remove unused bd pin/unpin/hook commands (bd-x0zl) 2025-12-27 16:02:15 -08:00
AGENTS.md feat(mol): add distill command to extract protos from epics 2025-12-21 10:32:23 -08:00
beads.go feat: show redirect info in bd prime output (bd-kblo) 2025-12-27 21:33:01 -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 docs: Add comprehensive documentation for version reporting changes 2025-12-13 10:04:01 +11:00
CHANGELOG.md chore: Bump version to 0.46.0 2026-01-06 23:51:29 -08:00
CLAUDE.md feat(dates): add --due and --defer timestamp options with natural language parsing (#847) 2026-01-01 20:06:13 -08:00
CONTRIBUTING.md feat(daemon): unify auto-sync config for simpler agent workflows (#904) 2026-01-06 12:52:19 -08:00
default.nix feat(dates): add --due and --defer timestamp options with natural language parsing (#847) 2026-01-01 20:06:13 -08:00
flake.lock feat: Add Nix flake for declarative builds 2025-10-15 13:45:05 +02:00
flake.nix fix: NixOS symlink compatibility for mtime and permission checks (#459) 2025-12-05 13:22:09 -08:00
go.mod refactor(test): replace testify with stdlib in daemon tests (#936) 2026-01-06 19:29:57 -08:00
go.sum feat(dates): add --due and --defer timestamp options with natural language parsing (#847) 2026-01-01 20:06:13 -08:00
install.ps1 docs: don't auto-install Go in Windows installer; instruct user instead (fixes #292) (#302) 2025-11-12 14:15:46 -08:00
LICENSE Initial commit: Beads issue tracker with security fixes 2025-10-11 20:07:36 -07:00
Makefile refactor: remove unused bd pin/unpin/hook commands (bd-x0zl) 2025-12-27 16:02:15 -08:00
README.md consolidate community tools into dedicated docs page 2025-12-28 08:05:32 -07:00
RELEASING.md feat(scripts): add --all, --mcp-local, --restart-daemons flags to bump-version.sh 2025-12-22 16:02:29 -08:00
SECURITY.md Prepare for public launch: comprehensive examples, docs, and tooling 2025-10-12 11:25:29 -07:00

bd - Beads

Distributed, git-backed graph issue tracker for AI agents.

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 (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Initialize (Humans run this once)
bd init

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

🛠 Features

  • Git as Database: Issues stored as JSONL in .beads/. Versioned, branched, and merged like code.
  • 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.
  • Invisible Infrastructure: SQLite local cache for speed; background daemon for auto-sync.
  • Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.

📖 Essential Commands

Command Action
bd ready List tasks with no open blockers.
bd create "Title" -p 0 Create a P0 task.
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.

📦 Installation

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

Requirements: Linux (glibc 2.32+), 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