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
Joseph Turian ba29fdc1f7
fix(test): resolve cobra OutOrStdout data race in CI (#1916)
* fix(test): remove t.Parallel() from cobra Help tests to fix data race

cobra's OutOrStdout() eagerly evaluates os.Stdout as the default
argument even when cmd.SetOut() has been called, so any parallel test
calling cmd.Help() or cmd.Execute() races with captureStdout() which
redirects os.Stdout behind stdioMutex. Remove t.Parallel() from the
three TestSearchCommand_* tests that exercise this path.

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

* test: add cobra-parallel policy guard and stdio mutex contract test

- TestCobraParallelPolicyGuard: scans test files and fails if any
  parallel test calls cobra Help()/Execute() without SetOut/SetErr.
  Strips comments to avoid false positives.
- TestStdioMutexContract: deterministic reentrancy check proving
  stdioMutex serializes captureStdout calls (fails without -race).
- Update stdioMutex documentation to explain that SetOut is NOT
  sufficient to prevent the race (cobra eagerly reads os.Stdout).

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

* refactor(test): strengthen cobra-parallel policy guard

Remove the SetOut/SetErr escape hatch since cobra's OutOrStdout()
eagerly evaluates os.Stdout even when outWriter is set. The guard
now forbids ALL cobra output methods in parallel tests. Also adds
stripStringLiterals() to prevent self-matching false positives.

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-20 09:22:25 -08:00
.agent/workflows fix: improve JSONL-only mode detection and error messages (GH #534) 2025-12-13 12:50:33 -08:00
.beads chore: Bump version to 0.55.2 2026-02-20 09:00:55 -08: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.55.2 2026-02-20 09:00:55 -08:00
.devcontainer Fix devcontainer init check - look for DB file not directory 2025-11-05 17:31:30 -08:00
.github docs: use --claim when starting work (#1920) 2026-02-20 09:22:13 -08:00
claude-plugin docs: use --claim when starting work (#1920) 2026-02-20 09:22:13 -08:00
cmd/bd fix(test): resolve cobra OutOrStdout data race in CI (#1916) 2026-02-20 09:22:25 -08:00
docs chore: audit sync mode complexity — remove stale refs and dead code (bd-shleu) 2026-02-19 21:33:22 -08:00
examples chore: remove ~5K lines of dead code from classic cleanup 2026-02-18 22:46:28 -08:00
integrations chore: Bump version to 0.55.2 2026-02-20 09:00:55 -08:00
internal feat: add orphan detection migration (bd-3852) 2026-02-20 09:16:52 -08:00
npm-package fix: resolve Windows file locking race condition during npm install (#1923) 2026-02-20 09:22:10 -08:00
scripts chore: Bump version to 0.55.2 2026-02-20 09:00:55 -08:00
tests/integration refactor: Remove legacy MCP Agent Mail integration (bd-6gd) 2025-12-17 23:14:23 -08:00
website docs: Remove stale daemon/SQLite/JSONL/tombstone documentation for Dolt-native 2026-02-16 19:19:00 -08:00
winget Add Windows ARM64 build support (#834) 2026-01-01 19:46:02 -08:00
.gitattributes fix: normalize CRLF line endings in git hook files (#1917) 2026-02-20 09:22:21 -08:00
.gitignore fix(ci): add .zig-cache/ to .gitignore for goreleaser 2026-02-18 20:43:39 -08:00
.golangci.yml fix(ci): resolve remaining CI test and lint failures 2026-02-17 22:55:54 +00:00
.goreleaser.yml fix(ci): add netgo tag for macOS cross-builds with zig 0.14.0 2026-02-19 08:33: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 chore: Bump version to 0.55.1 2026-02-19 21:30:49 -08:00
beads_test.go feat: export OpenFromConfig for server-mode aware store opening 2026-02-17 23:52:16 -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.55.2 2026-02-20 09:00:55 -08: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: 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.55.2 2026-02-20 09:00:55 -08:00
FEDERATION-SETUP.md chore: audit sync mode complexity — remove stale refs and dead code (bd-shleu) 2026-02-19 21:33:22 -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 feat: remove JSONL sync-branch pipeline, replace with Dolt-in-Git 2026-02-18 20:13:55 -08:00
go.sum feat: remove JSONL sync-branch pipeline, replace with Dolt-in-Git 2026-02-18 20:13:55 -08: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 cleanup: remove stale sqlite refs, fix lint warnings, update Makefile benchmarks 2026-02-16 00:49:18 -08:00
NEWSLETTER.md fix(ci): disable CGO for Android ARM64 build 2026-02-18 20:37:40 -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