- Go 95.2%
- Python 1.6%
- Starlark 1.5%
- Shell 1.3%
- Rust 0.2%
* fix(dolt): retry mutate+commit methods on serialization conflict (1213/1205) ClaimIssue, ClaimReadyIssue, UpdateIssue and CloseIssue each hand-rolled their own tx (BeginTx + DOLT_ADD/DOLT_COMMIT + Commit) outside withRetryTx, so a concurrent writer that lost Dolt's optimistic commit-time merge surfaced MySQL 1213/1205 as a hard failure instead of retrying. Dolt has no real row locking — FOR UPDATE / SKIP LOCKED are parse-only no-ops (https://www.dolthub.com/blog/2023-10-23-hold-my-beer/) — so retry is the only safety net under N concurrent workers. These four are the work-queue hot paths: `bd ready --claim`, claim, update, close. Move each body into a withRetryTx closure (which owns BeginTx and the final Commit and retries serialization failures with backoff), preserving the single-tx CAS/mutation + DOLT_COMMIT atomicity exactly. On retry, ClaimReadyIssue re-scans the ready front from a fresh snapshot and claims the next available issue. Tested: TestEmbeddedReadyClaimConcurrent, TestEmbeddedReadyConcurrent, TestEmbeddedCloseConcurrent, TestEmbeddedUpdateConcurrent and the non-concurrent embedded Update/Close/Ready tests pass; build + vet clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(dolt): add concurrent work-queue drain test (Gas Station claim invariant) N workers concurrently dequeue one shared ready-front via ClaimReadyIssue until empty; asserts every issue claimed exactly once, none stranded, no double-claims, and no serialization error ever surfaces (withRetryTx absorbs the 1213/1205 from the claim-CAS cell collision). This is the regression guard for the multi-agent claim queue that #4491 makes safe. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(lease): claim-TTL + heartbeat + reclaim for dead-worker recovery Gas Station v1.1 (wy-5r9j). A claim was previously permanent: a worker that died mid-task stranded its issue in_progress forever. This adds a lease so a claim can expire and be recovered. Schema (migration 0054): add lease_expires_at, heartbeat_at (DATETIME) and row_lock (BIGINT) to issues (and wisps, for uniform issueops routing), plus idx_issues_lease for the reaper scan. assignee doubles as the lease owner. Lifecycle (shared issueops, so both server-mode DoltStore and EmbeddedDoltStore get it): - Claim stamps lease_expires_at = now + TTL (default 5m, WithLeaseTTL to override), heartbeat_at = now, and a fresh row_lock. - bd heartbeat <id> — owner-only; pushes the lease forward and rewrites row_lock. Fails (ErrNotClaimable/ErrAlreadyClaimed) once the lease is gone. - bd reclaim --older-than <dur> — reverts in_progress issues whose lease expired more than <dur> ago back to ready (clears assignee/started_at, records a lease_reclaimed event). Default grace 2×TTL. The row_lock trick: Dolt has no row locking and merges concurrent commits cell-by-cell, so a heartbeat (writes heartbeat_at) racing a reclaim (writes status) would silently cell-merge into a zombie — an open/unassigned issue that still carries the worker's fresh heartbeat. Every mutating path (claim, close, update, heartbeat, reclaim) now rewrites the shared row_lock cell, forcing the loser to a 1213/1205 serialization conflict that withRetryTx replays. All lease paths are withRetryTx/withConn wrapped. Tests (real Dolt): TestRowLockForcesConflictOnDisjointCellWrites proves the bug without row_lock (silent merge to zombie) and correctness with it (conflict); TestConcurrentHeartbeatReclaimClose is the integration race (live workers heartbeat+close vs a continuous reaper vs dead workers) asserting exactly-once, no lost close, no zombie; plus claim/heartbeat/reclaim unit coverage on both backends. Note: lease columns are second-granular DATETIME (Dolt rounds), so sub-second TTLs are meaningless — production TTL is minutes. Heartbeat writes a Dolt commit, so cadence must stay ≪ claim cadence to avoid history bloat. Fixes the test coupling in TestMigration0053PromotesRigWisps, which assumed the rig-wisp repair was always LatestVersion(). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * ci+docs: allowlist lease stress tests; scope the row_lock invariant comment - Add TestConcurrentWorkQueueDrain and TestConcurrentHeartbeatReclaimClose to the check-testing-short.sh allowlist; both are real-Dolt runtime/stress skips and were failing ci-pr-policy. - freshRowLock doc said "EVERY mutating path" rewrites row_lock, which overstates it. Scope it to status/ownership/lease-mutating paths (the set the reclaim/heartbeat races care about) and document the invariant + why orthogonal-cell writers (is_blocked, compaction, deps, rename, reopen) are intentionally exempt, so a future writer does not silently reintroduce the zombie-merge bug. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(show): surface lease_expires_at/heartbeat_at in bd show (--json + text) (wy-9cdw) Migration 0054 added lease_expires_at/heartbeat_at (and internal row_lock) to the issues/wisps tables for the claim/heartbeat/reclaim leasing feature, but bd show could not observe lease state — you had to drop to raw SQL. - types.Issue: add LeaseExpiresAt/HeartbeatAt (*time.Time, omitempty), matching the StartedAt nullable-timestamp convention. row_lock stays unexported. - sqlbuild.IssueSelectColumns: append lease_expires_at, heartbeat_at to the canonical hydration list (flows to every stack via the shared constant). - issueops.ScanIssueFrom: scan + map the two nullable columns (before the trailing extra dests, keeping positional parity across all scan sites). - bd show text view: emit a muted 'Lease: expires <rel> (heartbeat <rel> ago)' line only for in_progress issues holding an active lease; add formatTimeUntil as the forward-looking mirror of formatTimeAgo. - types_test: assert lease keys appear when set, are omitted when nil, and that row_lock is never surfaced. * fix(lease): settle v54 review blockers Address #4537 review blockers before landing v54: keep heartbeat off wisps in both backends, keep direct status/assignee updates from leaving stale leases, guard the down migration, and emit reclaim JSON as snake_case. Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie * fix(lease): cover lease fields in tests and hooks Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: matt wilkie <maphew@gmail.com> |
||
|---|---|---|
| .agent/workflows | ||
| .beads/formulas | ||
| .claude | ||
| .claude-plugin | ||
| .devcontainer | ||
| .githooks | ||
| .github | ||
| cmd/bd | ||
| docs | ||
| examples | ||
| format | ||
| integrations | ||
| internal | ||
| npm-package | ||
| plugins/beads | ||
| release-gates | ||
| scripts | ||
| tests | ||
| website | ||
| winget | ||
| .buildflags | ||
| .gitattributes | ||
| .gitignore | ||
| .golangci.yml | ||
| .goreleaser.yml | ||
| .pre-commit-config.yaml | ||
| .test-skip | ||
| AGENT_INSTRUCTIONS.md | ||
| AGENTS.md | ||
| ARTICLES.md | ||
| beads.go | ||
| beads_cgo.go | ||
| beads_nocgo.go | ||
| beads_test.go | ||
| BENCHMARKS.md | ||
| build-docs.md | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| codecov.yml | ||
| CONTRIBUTING.md | ||
| default.nix | ||
| FEDERATION-SETUP.md | ||
| flake.lock | ||
| flake.nix | ||
| go.mod | ||
| go.sum | ||
| install.ps1 | ||
| issues.jsonl | ||
| LICENSE | ||
| Makefile | ||
| NEWSLETTER.md | ||
| open_nocgo_test.go | ||
| packages.nix | ||
| PR_MAINTAINER_GUIDELINES.md | ||
| PROPOSAL-pull-config-wedge.md | ||
| README.md | ||
| RELEASING.md | ||
| renovate.json | ||
| SECURITY.md | ||
| THIRD_PARTY_LICENSES | ||
bd - Beads
Distributed graph issue tracker for AI agents, powered by Dolt.
Platforms: macOS, Linux, Windows, FreeBSD
Docs: https://gastownhall.github.io/beads/
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/gastownhall/beads/main/scripts/install.sh | bash
# Initialize in YOUR project
cd your-project
bd init
# Optional: refresh or install richer instructions for your agent
bd setup codex # Codex CLI - installs skill, AGENTS.md guidance, and hooks
bd setup claude # Claude Code - installs hooks/settings
bd setup factory # Factory.ai Droid - creates/updates 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.
bd init creates or updates AGENTS.md by default so agents can discover the beads workflow, and also installs project Claude/Codex integrations unless you pass --skip-agents or --stealth. Use bd setup --list to see supported integrations, including bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor, and more. See Agent and IDE setup.
Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun bd init/bd setup, or custom instruction files. In those cases, run bd onboard and paste the printed snippet into the file your agent reads.
If your agent is not covered by bd setup, add this minimal AGENTS.md section:
This project uses bd (beads) for issue tracking.
- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.
🛠 Features
- Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
- 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, andreplies_tofor 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. |
bd prime |
Print agent workflow context and persistent memories. |
bd remember "insight" |
Store project memory that bd prime injects later. |
🔗 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. See Git-Free Usage below.
Contributor vs Maintainer: When working on open-source projects:
- Contributors (forked repos): Run
bd init --contributorto 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 maintainerif using GitHub HTTPS without credentials but you have write access.
📦 Installation
brew install beads # macOS / Linux (recommended)
npm install -g @beads/bd # Node.js users
Other methods: install script | go install | from source | Windows | Arch AUR
Requirements: macOS, Linux, Windows, or FreeBSD. See docs/INSTALLING.md for complete installation guide.
Upgrading? Replacing the binary is not always the whole story: releases can
carry schema migrations, and a database that syncs to a Dolt remote must be
migrated by exactly one designated clone. Back up first (bd export --all),
then follow the upgrade guide
(also summarized in docs/INSTALLING.md).
Security And Verification
Before trusting any downloaded binary, verify its checksum against the release checksums.txt.
The install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.
On macOS, scripts/install.sh preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via BEADS_INSTALL_RESIGN_MACOS=1.
See docs/ANTIVIRUS.md for Windows AV false-positive guidance and verification workflow.
💾 Storage Modes
Beads uses Dolt as its database. Two modes are available:
Embedded Mode (default)
bd init
Dolt runs in-process — no external server needed. Data lives in
.beads/embeddeddolt/. Single-writer only (file locking enforced).
This is the recommended mode for most users.
When the git repo has an origin remote, bd init configures a Dolt remote
named origin automatically. Cross-machine sync uses bd dolt push and
bd dolt pull against refs/dolt/data; .beads/issues.jsonl is an export
for viewers and interchange, not the source of truth or a full database
backup.
Server Mode
bd init --server
Connects to an external dolt sql-server. Data lives in .beads/dolt/.
Supports multiple concurrent writers. Configure the connection with flags
or environment variables:
| Flag | Env Var | Default |
|---|---|---|
--server-host |
BEADS_DOLT_SERVER_HOST |
127.0.0.1 |
--server-port |
BEADS_DOLT_SERVER_PORT |
3307 |
--server-socket |
BEADS_DOLT_SERVER_SOCKET |
(none; uses TCP) |
--server-user |
BEADS_DOLT_SERVER_USER |
root |
BEADS_DOLT_PASSWORD |
(none) |
Unix domain sockets: Use --server-socket to connect via a Unix socket
instead of TCP. This avoids port conflicts between concurrent projects and
is useful in sandboxed environments (e.g., Claude Code) where file-level
access control is simpler than network allowlists. The Dolt server must be
started with dolt sql-server --socket <path>. Auto-start is not supported
in socket mode.
Backup & Migration
Back up your database and migrate between modes using bd backup:
# Set up a backup destination and push
bd backup init /path/to/backup
bd backup sync
# Restore into a new project (any mode)
bd init # or bd init --server
bd backup restore --force /path/to/backup
See docs/DOLT.md for full migration instructions.
bd export and .beads/issues.jsonl are issue-table exports. They are useful
for review, migration, and interoperability, but they do not capture Dolt
branches, commit history, working-set state, or non-issue tables. Use
bd backup or a manual Dolt backup when you need a restorable database backup.
🌐 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.
🚀 Git-Free Usage
Beads works without git. The Dolt database is the storage backend — git integration (hooks, repo discovery, identity) is optional.
# Initialize without git
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth
# All core commands work with zero git calls
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"
BEADS_DIR tells bd where to put the .beads/ database directory,
bypassing git repo discovery. --stealth sets no-git-ops: true in
config, disabling all git hook installation and git operations.
This is useful for:
- Non-git VCS (Sapling, Jujutsu, Piper) — no
.git/directory needed - Monorepos — point
BEADS_DIRat a specific subdirectory - CI/CD — isolated task tracking without repo-level side effects
- Evaluation/testing — ephemeral databases in
/tmp
For daemon mode without git, use bd daemon start --local
(see PR #433).
📝 Documentation
- Documentation site (versioned) | Installing | Sync Concepts | Agent Workflow | Copilot CLI Setup | Copilot VS Code MCP | Articles | Sync Branch Mode | Troubleshooting | FAQ