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/dave 2ee0995f51 feat(rpc): add AllowStale option to List API (bd-dpkdm)
Add AllowStale field to ListArgs struct to support resilient hook detection.
When set, callers signal they accept potentially stale data rather than
failing on staleness check errors.

This enables gastown checkSlungWork() to fall back gracefully when the
beads database is out of sync with JSONL (common after concurrent agent syncs).

- Add AllowStale bool to ListArgs in internal/rpc/protocol.go
- Pass --allow-stale flag through to RPC in cmd/bd/list.go

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

Executed-By: beads/crew/dave
Rig: beads
Role: crew
2026-01-09 00:42:13 -08:00
.agent/workflows fix: improve JSONL-only mode detection and error messages (GH #534) 2025-12-13 12:50:33 -08:00
.beads refactor(formula): break run-bump-script into individual version-update steps (bd-a854) 2026-01-07 21:37:19 -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 feat(rpc): add AllowStale option to List API (bd-dpkdm) 2026-01-09 00:42:13 -08:00
commands Update link to install script (#867) 2026-01-03 12:53:58 -08:00
docs feat(sync): pull-first sync with 3-way merge (#918) 2026-01-07 21:27:20 -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(rpc): add AllowStale option to List API (bd-dpkdm) 2026-01-09 00:42:13 -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): resolve CI lint failures for v0.47.0 release 2026-01-08 20:21:02 -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(sync): pull-first sync with 3-way merge (#918) 2026-01-07 21:27:20 -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 feat(sync): pull-first sync with 3-way merge (#918) 2026-01-07 21:27:20 -08:00
go.sum feat(sync): pull-first sync with 3-way merge (#918) 2026-01-07 21:27:20 -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