- Go 95.2%
- Python 1.6%
- Starlark 1.5%
- Shell 1.3%
- Rust 0.2%
* fix(notion): make the query page bound configurable and honour Retry-After QueryDataSource paginates up to maxQueryPages (50) x maxPageSize (100), so a data source larger than 5000 rows cannot be synced at all: the call returns an error rather than partial results, and because every CLI narrowing flag is applied after it returns, no flag works around it. Sync dies in both directions at once. Refs #6004. Two changes, and the second is what makes the first safe: - Client.MaxQueryPages / WithMaxQueryPages lets a caller raise the bound for a large data source. Default behaviour is unchanged when unset. The error at the bound now names the ceiling in rows as well as pages, since rows is the number a caller can compare against their own data source. - doRequest now retries 429 and 529 honouring Retry-After, with exponential fallback clamped at 30s. Notion enforces ~3 requests/second per connection, so raising the page bound without this would trade a clear failure for an intermittent one. Other 5xx retry only for GET/DELETE — replaying a POST that may already have been applied server-side is how duplicates get made. The request body is now marshalled once and the reader rebuilt per attempt; a retry cannot reuse a drained body. Tests cover the configured bound, the unchanged default, Retry-After being obeyed exactly, GET retrying on 5xx, and POST not retrying. Verified they bite: forcing maxRequestAttempts to 1 fails exactly the two retry tests, and ignoring the configured bound fails exactly the bound test. make build and make fmt-check pass; internal/notion and internal/tracker pass with -tags gms_pure_go. golangci-lint was not run locally (not installed on this machine); CI will cover it. * fix(notion): use US spelling so misspell passes The repo pins misspell to locale: US, and CI flagged "honouring" in internal/notion/client.go. Corrected there, and in the two occurrences in client_test.go - those are not linted today (run: tests: false) but leaving British spellings in place only plants a failure for whenever that changes. Verified with misspell v0.8.0 -locale US: the pre-fix content reports both occurrences, the fixed content reports none. internal/notion tests pass with -tags gms_pure_go, including the renamed test. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N4YFBBWN33GZZ2BDxWRvjT * fix(notion): address review — 529 verb gate, ctx-aware retry wait, CLI wiring MAJOR 1. retryableStatus returned early on 429 *or* 529 before the verb gate, so 529 was retryable for every verb — including CreatePage and CreateDatabase. A 529 can come back after Notion's edge already handed the write to the origin, so a replay creates a second row for one bd issue, and ensureRemoteIndex is last-write-wins on the bd ID, so nothing surfaces it. 429 stays verb-agnostic (Notion rejects rate-limited requests before processing them); 529 now sits under the GET/DELETE gate with the other 5xx. Three tests pin the boundary: a creating POST makes one attempt on 529, a GET retries on 529, and a creating POST still retries on 429. MAJOR 2. The retry wait polled ctx.Done() with a default: and then slept, so cancellation was ignored for up to maxRetryDelay per attempt — and QueryDataSource pays that per page, scaling with the very bound this change lets callers raise. Replaced with wait(ctx, d): a blocking select over ctx.Done() and a channel from a c.after hook, time.After by default. MAJOR 3. The bound is now reachable from the CLI. Tracker.Init reads notion.max_query_pages / NOTION_MAX_QUERY_PAGES and threads it into the client; unset keeps the client's own default, and a value that is set but unusable is an error rather than a silent fallback — the operator sets that key precisely because sync is already failing on the bound. The pagination error names those levers instead of a Go method a CLI user cannot call. Also: assert every attempt carries a non-empty body (a drained reader would send an empty second one, and nothing noticed); drop the unreachable lastErr branch by breaking out of the loop; pin retry exhaustion at exactly maxRequestAttempts with the last attempt's error; table-test parseRetryAfter across the nine interesting inputs; name the 529 literal; hardcode 50 in the default-bound test so lowering the default fails it; atomic counters in tests. Every new test verified to bite by reverting each fix in turn: each mutation fails exactly the tests naming it, against a clean baseline. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(notion): refuse a Retry-After longer than the client will wait Separate commit because this one is a judgement call, not a defect fix — drop it on its own if you would rather keep clamp-and-retry. With Retry-After: 3600 the old path clamped to 30s and retried four times, so a server asking for an hour got four more requests inside two minutes — the window it told us to stay out of, and the way that window gets extended. Now the call returns immediately, naming the delay the server asked for, and the caller decides. A Retry-After equal to maxRetryDelay is still honoured and waited out; only a longer one is refused. The underlying API error is wrapped, so nothing is lost to a caller inspecting it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(notion): key retry on side-effect safety, jitter own backoff, honour both Retry-After forms Maintainer review fixes for PR #6006 (review iterations 1 and 2). All changes are inside internal/notion; no new files. F1 (major) — the 5xx/529 retry arm could never fire on POST /data_sources/{id}/query, the paginating endpoint this PR exists to protect, while the MethodDelete half of the allowlist had no call site at all (a census of the client's verbs returns 3 GET / 3 POST / 2 PATCH, zero DELETE). Replaced the verb gate with a retrySafety value each call site declares, so the property being tested is side-effect safety rather than a proxy for it, and dropped the dead MethodDelete arm. Only the read-only query POST changes behaviour: the creating POSTs and both PATCHes stay non-replayable on every status except 429, exactly as before. TestClientDoesNotRetryServerErrorOnPost exercised the query endpoint while its "may already have been applied server-side" rationale could not be true there, so it is retargeted at CreatePage and renamed ...OnCreatingPost, pairing with the existing 529 twin; TestClientRetriesServerErrorOnQueryPost pins the new behaviour. F2 (minor) — the exponential fallback had no jitter, unlike both sibling tracker clients, so N processes tripping the same ~3 req/s limit retried in lockstep. Jitter is applied to the self-chosen ladder only, never to a server-mandated Retry-After, mirroring the split in internal/jira/client.go:419-424. F3 (minor) — parseRetryAfter collapsed absent, HTTP-date and a legal "Retry-After: 0" into one sentinel, so a date-form wait routed around the maxRetryDelay refusal its delta-seconds twin is subject to. It now parses both RFC 9110 forms and returns a presence flag; the doc comment's old justification went with the behaviour it described. F4 (nit) — maxRequestAttempts' comment claimed coverage of "transiently failing" requests, which the transport arm does not have. F5 (nit) — the invalid-value error names NOTION_MAX_QUERY_PAGES as well as the config key, an abandoned wait now carries the API failure that caused it alongside ctx's error, and the long-Retry-After refusal is evaluated before the exhaustion break so the operator still gets it on the final attempt. That last pin is a sibling test rather than a case inside TestClientExhaustsRetriesAndReturnsTheLastError as the review suggested, to keep that test a single-purpose pin on the loop's exit arithmetic. Iteration 2 (non-gating, both in parseRetryAfter, which F3 already reworks) — a delta-seconds value too large for a Duration now saturates instead of letting the multiply wrap: "9223372037" wrapped to -2562047h47m16.7s, which is under maxRetryDelay, so the refusal let it through to immediate retries. The date form already saturated via time.Until. The unchecked multiply predates this fixup (it is at the contributor's head) and is shared by linear/jira/gitlab, which are left to a follow-up. TestClientRefusesLongRetryAfterInHTTPDateForm drives a date-form header through the client, so the date form reaching the refusal is pinned by the loop rather than only by TestParseRetryAfterHTTPDate's arithmetic. Validation: internal/notion 85 PASS / 0 FAIL / 0 SKIP; go build ./... and go vet ./cmd/bd (the sole importer) clean; CGO_ENABLED=0 builds; gofmt clean; golangci-lint 0 issues both unscoped and --new-from-rev at the upstream base, and the added //nolint:gosec is load-bearing (removing it reproduces exactly the G404 it names). Each fix is mutation-proved: reverting it reds its own pin while the neighbouring pins stay green, including the two creating-POST controls under F1, both directions of F2's jitter split, and both sides of the saturation bound. Keying the refusal to delta-seconds only reds the new date-form test alone, while TestParseRetryAfterHTTPDate stays green. Moving the new delay logic into retryDelay rather than nesting it in the loop took doRequest — the run's worst_changed function — from cyclomatic 21 / cognitive 32 to 19 / 28 (gocyclo, gocognit), out of the major cyclomatic band instead of further into it. No BUILD.bazel change is owed: no file was added and both added imports (math, math/rand/v2) are stdlib. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local> |
||
|---|---|---|
| .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