- Go 95.2%
- Python 1.6%
- Starlark 1.5%
- Shell 1.3%
- Rust 0.2%
* fix(winget): require PortableCommandAlias for GasTownHall.Beads GasTownHall.Beads 1.1.0 on winget-pkgs only sets Commands: (search metadata) and never creates WinGet\Links\bd.exe, so already-running shells never see bd after install (GH#4908). - Add canonical GasTownHall.Beads.installer.yaml with PortableCommandAlias - update-winget.sh regenerates that package id for new releases - Document both package ids and the Links requirement in winget/README - Add check-winget-portable-alias.sh guard Fixes #4908 * fix(winget): address maphew's PR #5134 review (grep bug, guard, CI wiring) Maintainer commits requested by the PR author on the reviewer's behalf, addressing maphew's 2026-07-29 review of PR #5134: - scripts/update-winget.sh: `grep windows` matched both amd64 and arm64 checksum lines, corrupting InstallerSha256 into an unparseable two-line value. Narrow to `grep windows_amd64` (mirrors the existing arm64 grep on the next block). - scripts/update-winget.sh: quote the arm64 InstallerSha256 placeholder so 64 bare zero digits don't parse as a YAML integer, matching the quoting already used in the checked-in SteveYegge.beads.installer.yaml. - scripts/check-winget-portable-alias.sh: replace the bare `grep -q PortableCommandAlias:` substring check with a yq-based parse, so a corrupted manifest (like the one above) fails the guard instead of reporting OK; also fail closed on an empty winget/ glob instead of silently exiting 0. - .github/workflows/pr.yml, main.yml: run the guard in the existing check-build-tags job so it executes on every PR instead of only when someone remembers to invoke it by hand. Locally verified: guard passes against the current checked-in manifests, fails against a reproduction of the exact grep-bug corruption, fails on an empty winget/ dir, and the generator produces a yq-parseable manifest against a synthetic checksums.txt. shellcheck clean; both workflow files parse as valid YAML. * fix(winget): harden the PortableCommandAlias guard and its release docs Maintainer review fixups for the adopt-pr review of PR #5134 (iteration 1, synthesis approve / 0 blockers and 0 majors; all seven items were non-gating). Scorecard 961/1000, Required Changes: None. Every edit site below is a line this PR itself added. Finding 1 (minor, Error Handling) — `yq -e ... >/dev/null 2>&1` collapsed three distinct failures (yq absent at exit 127, unparseable manifest, alias genuinely missing) into "missing valid PortableCommandAlias", defeating the script's own stated rationale and pointing a debugger at manifests that are already correct. The guard now names a missing yq up front and no longer discards stderr, so yq's own diagnostic reaches the log of a required-gate job. yq is CI's first and only yq consumer, running in a bare actions/checkout job, and sits outside the host-tools inventory declared in scripts/BUILD.bazel; that is now stated where the dependency lives. Finding 4 (minor, Change Impact) — the glob is winget/*.installer.yaml but the assertion was unconditional on installer type, so a future msi/exe/msix manifest (no NestedInstallerFiles at all) would hard-fail a gate-feeding job with no opt-out. Non-portable manifests are now classified out with a SKIP line. The parse check deliberately precedes the class check: without that ordering an unparseable manifest fails the NestedInstallerType test and is silently skipped as "not portable", which is strictly worse than the behaviour being fixed. Finding 2 (minor, Error Handling) — amd64 and arm64 had opposite failure policies in one script: a missing amd64 checksum hard-fails, while a missing arm64 checksum substituted 64 zeros and continued to success, disclosed only in a source comment. The echoed "Next steps" block now ends in a loud "DO NOT PUBLISH" warning naming the placeholder, emitted only when the fallback actually fires. The finding's second arm — "teach the guard to reject an all-zero InstallerSha256" — is implemented as a WARNING rather than a failure, and that is a deliberate downgrade. winget/SteveYegge.beads.installer.yaml:15 already carries exactly that placeholder for its arm64 entry; that file is base-owned and is not in this PR's six-file diff, so a fatal tripwire would turn a required check red over pre-existing content the PR never touched. The legacy heredoc in update-winget.sh emits no arm64 entry at all, so the placeholder is stale hand-authored state that the next generator run removes. Verified: the guard still exits 0 on the real tree and reports the warning. Finding 3 (minor, Contract & Interface Fidelity) — a winget-pkgs version directory needs a version + defaultLocale + installer set, but the repo carries only GasTownHall.Beads.installer.yaml, so README step 2 as written produced a set winget-pkgs validation rejects. Took the documentation arm: GasTownHall is now steered to `wingetcreate update` (which supplies the other two manifests from the published set) and the hand-copy path is marked as applying only to the legacy id, which does have a complete three-file set. Generating two more manifests would have changed the contribution's deliverable scope. Finding 5 (nit, Architectural Consistency) — the first update-winget.sh run overwrote the checked-in manifest with a three-line header, deleting this PR's own GH#4908 rationale from the artifact whose purpose is to carry it. The heredoc now emits the same header, plus a fresh ReleaseDate. Verified by generating into a temp tree: the generated header is byte-identical to the checked-in file's first ten lines. Finding 6 (nit, Documentation Accuracy) — the README froze SteveYegge.beads at the "0.30.x era" while the script rewrites all three of its manifests to the new version. Note that the section already disclosed that both ids are refreshed, so the residual gap was narrower than the finding stated: what was missing is that the legacy id's version is bumped out of the era the table advertises. That clause is now explicit. Finding 7 (nit, Test Evidence Quality) — the guard's fail-closed behaviour was pinned by nothing in-repo. Adds scripts/check_winget_portable_alias_test.go with ten cases: alias present, alias missing, wrong alias, empty winget dir, unparseable manifest (asserting it is neither skipped nor misreported and that yq's stderr survives), missing yq, a skipped non-portable manifest, a violating portable sibling of a skipped manifest, and the advisory placeholder warning. Deviates from the prescribed `requireHostTool(t, "yq")` on purpose. requireHostTool fails rather than skips under Bazel because //scripts:scripts_test is tagged host-tools, and that tag's declared inventory is "git, python3, awk, sed, find, grep and timeout" — yq is not in it, so the prescription would red the shared target on hosts that keep the promise the tag actually makes. A skip-only gate is used and the reason is recorded at the helper. Fixtures are synthetic so the target needs no new data dependency; the real manifests are covered by the check-build-tags job, which runs this script against the actual checkout. Also fixed, found while editing and not raised by either lane: winget/README.md told readers to run `grep windows` over checksums.txt, which is the exact two-line ambiguity this PR fixed in the script (`grep windows` -> `grep windows_amd64`). Before this PR the script and doc agreed; after it they diverged, so the PR created the inconsistency. The doc now uses `grep windows_` and says which line feeds which architecture. Validation. `git diff --check` clean. The guard runs green on the real tree (both manifests OK, rc=0) and on a freshly generated tree. go test ./scripts/ ok 21.7s (the package whose tests pin workflow content). Each new pin was proven non-vacuous by reverting the corresponding fix and confirming the test reds: dropping the class check reds the non-portable case; dropping the placeholder tripwire reds the warning case; dropping the parse-before-classify check reds the unparseable case; dropping the yq preflight reds the missing-yq case; restoring `2>&1` reds the stderr assertion. All five arms red, and the guard was restored byte-identical (md5 verified) after each. The arm64 warning was exercised both ways against a stubbed curl: present arm64 checksum emits no warning, absent one emits DO NOT PUBLISH. New yq expressions stay inside the vocabulary shared by mikefarah yq v4 (what ubuntu-latest ships) and python-yq/jq — identity, `==`, `[]`, `select` and `-e`'s exit status — because only the pre-existing expression had been proven green on mikefarah in CI, and this host has python-yq. Builtins the two flavours spell differently (jq's `any(cond)` vs mikefarah's `any_c`) are avoided, and the placeholder tripwire uses grep precisely because it looks for a known-bad literal and so can only miss a bad value, never report OK on a manifest it failed to parse. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Bee <bee@ghosttrack.com> Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com> |
||
|---|---|---|
| .agent/workflows | ||
| .beads/formulas | ||
| .claude | ||
| .claude-plugin | ||
| .devcontainer | ||
| .githooks | ||
| .github | ||
| backend | ||
| beadserrors | ||
| cmd/bd | ||
| docs | ||
| engdocs | ||
| examples | ||
| format | ||
| integrations | ||
| internal | ||
| issueops | ||
| journalops | ||
| memoryops | ||
| npm-package | ||
| plugins/beads | ||
| release-gates | ||
| schema | ||
| scripts | ||
| test | ||
| tests | ||
| third_party/patches | ||
| tools | ||
| winget | ||
| .bazelignore | ||
| .bazelrc | ||
| .bazelversion | ||
| .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_gated_test.go | ||
| beads_nocgo.go | ||
| beads_test.go | ||
| BENCHMARKS.md | ||
| build-docs.md | ||
| BUILD.bazel | ||
| CHANGELOG.md | ||
| checks.nix | ||
| claim.go | ||
| claim_roundtrip_test.go | ||
| claim_test.go | ||
| CLAUDE.md | ||
| codecov.yml | ||
| CONTRIBUTING.md | ||
| CONTRIBUTING_PR_GUIDELINES.md | ||
| default.nix | ||
| errors_test.go | ||
| export_dependency_add_options_test.go | ||
| FEDERATION-SETUP.md | ||
| flake.lock | ||
| flake.nix | ||
| go.mod | ||
| go.sum | ||
| install.ps1 | ||
| issue_lifecycle_external_test.go | ||
| issue_roles_external_test.go | ||
| issues.jsonl | ||
| LICENSE | ||
| Makefile | ||
| mint.sh | ||
| MODULE.bazel | ||
| MODULE.bazel.lock | ||
| NEWSLETTER.md | ||
| open_backend_selection_test.go | ||
| open_nocgo_test.go | ||
| overlay.nix | ||
| packages.nix | ||
| PR_MAINTAINER_GUIDELINES.md | ||
| PROPOSAL-cas-conditional-update.md | ||
| PROPOSAL-pluggable-storage-backends.md | ||
| PROPOSAL-pull-config-wedge.md | ||
| query_interfaces_cgo_test.go | ||
| query_interfaces_test.go | ||
| README.md | ||
| RELEASING.md | ||
| renovate.json | ||
| SECURITY.md | ||
| THIRD_PARTY_LICENSES | ||
| VERSIONED-BEADS-WRITE-PATHS.md | ||
bd - Beads
Distributed graph issue tracker for AI agents, powered by Dolt.
Platforms: macOS, Linux, Windows, FreeBSD
Docs: https://beads.gascity.com/
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.
flowchart LR
create["bd create<br/>new bead"] --> depgraph["dependency<br/>graph"]
depgraph --> ready["bd ready<br/>claimable work"]
ready --> claim["bd update --claim<br/>agent takes it"]
claim --> close["bd close<br/>work done"]
close -->|blockers released| ready
depgraph <-->|"bd dolt push / pull"| remote[("other machines<br/>and agents")]
⚡ 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 durable project facts; keep per-operator preferences in your harness's own memory.
- 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/getting-started/installation.md for complete installation guide.
Upgrading? Replacing the binary is not always the whole story. Short
version: sync remote-backed databases with your current bd, back up with
bd export --all, upgrade the binary, then run bd info --whats-new,
bd hooks install, and bd version. If the upgrade crosses a schema
migration on a remote-backed database, exactly one designated clone runs
bd migrate and bd dolt push; other clones install the new binary
and run bd bootstrap. See the full
upgrade guide
or docs/getting-started/installation.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/reference/antivirus.md for Windows AV false-positive guidance and verification workflow.
💾 Storage Modes
Beads uses Dolt as its database. Two modes:
- Embedded (default) —
bd init. Dolt runs in-process, data lives in.beads/embeddeddolt/, single writer. Recommended for most users. - Server —
bd init --server. Connects to an externaldolt sql-serverfor multiple concurrent writers; data lives in.beads/dolt/.
Cross-machine sync uses bd dolt push / bd dolt pull against
refs/dolt/data on your git remote; .beads/issues.jsonl is an export for
viewers and interchange, not the source of truth or a backup. Back up and
migrate between modes with bd backup; reclaim space with bd prune /
bd purge.
Full detail — connection flags, sockets, maintenance, backup, and migration — in the Dolt backend guide.
Schema Version Guard
bd checks the database schema version at open time. If the database has been
migrated by a newer binary and an older binary tries to open it, bd exits
with an actionable error rather than issuing queries that fail with cryptic SQL
errors:
schema version mismatch: database is at v45, binary knows up to v42 (3 migrations ahead)
Your bd binary is stale. Queries for dropped or renamed columns will fail
with cryptic SQL errors (e.g. "column X could not be found in any table in scope").
Rebuild from main:
CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd
Or install the latest release:
CGO_ENABLED=0 go install -tags gms_pure_go github.com/steveyegge/beads/cmd/bd@latest
To proceed despite the risk (some read commands may still work):
BD_IGNORE_SCHEMA_SKEW=1 bd <command>
bd --ignore-schema-skew <command>
When this fires: only when the database schema is ahead of the binary (a newer binary migrated the database; this binary doesn't know those migrations). Normal upgrades, where the binary migrates the database forward, are unaffected.
Escape hatch: BD_IGNORE_SCHEMA_SKEW=1 (or --ignore-schema-skew) bypasses
the guard with a warning on stderr. Use this only if you know the forward
migrations are additive and safe for your specific workload.
🌐 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.
See docs/related-projects.md for adjacent or complementary projects that solve different problems in the same neighborhood.
🚀 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