- Go 95.2%
- Python 1.6%
- Starlark 1.5%
- Shell 1.3%
- Rust 0.2%
Maintainer fixup for the first three review passes of #7684. A flat dotted key under a flow-style top level skipped the span probe, and the nested walk never sees that spelling, so it reached the line matcher unchecked (finding 1, major). On the opening line (`{sync.remote: a, node_id: b}`) it is never matched: the value stays live and the unset reports success. On a line of its own, commenting it out can take the closing brace with it or leave the rest of a wrapped value behind; the review's seed re-read as `{branch: b}` with node_id gone. Such a key is a key inside a flow-style mapping, so it now gets the flow-style refusal a single-segment key there already had (the review's first option). That includes a one-line value on a line of its own, which the matcher used to comment out cleanly: refusing it is what the CHANGELOG promises for a key inside a flow-style mapping, and a row pins it. A plain scalar that starts on the key's line and continues onto a deeper one parses when cut after the key's line, as a shorter value, so the probe let it through and the continuation stayed behind (finding 2, major): `sync:` / ` remote: file:///a` / ` /b` re-read as `sync: /b`, and a wrapped `notes:` stopped the file from parsing. As both reviewers proposed, the probe now also compares the value in the cut with the whole file's. The cut holds the key's line and nothing after it, so the key's value is its last node, and a value that goes on reads shorter there. Aliases and collections are not compared: a cut that parses has closed them. The probe cut the document at "\n", but yaml.v3 numbers node lines at every YAML line break: LF, CR, CRLF, NEL, LS and PS (finding 3). A line separator or a lone carriage return above the key moved the cut, refusing a one-line value the base unsets and missing a wrapped one. yamlLineEnd counts breaks as yaml.v3 does. TestYamlLineEndCutsWhereYamlV3EndsALine checks the cut against yaml.v3's own line numbers for every break, also with the break as the file's first byte, where the look back for a CR before an LF has nothing to look at. The refusals before the edit judge the first document's parse, so some edits still got past them: a wrapped value in a later document (finding 4), a later duplicate of the key whose value wraps, an anchor on the key's line that an alias further down uses, and, beside the key, a line inside another value that only looks like it. Rather than name each shape, both unset callers now check commentOutYamlKey's result before they write (collateralUnsetRefusal). Read back, every document must hold what it held before, less some of the key's own entries in either spelling; an edit that adds, removes or changes anything else is refused. Documents are compared by position, because bd reads only the first one and an emptied first document would let the second take its place. An alias is compared by where the anchor it resolves to is, and never expanded, so the check stays linear in the file. A file that did not parse before the edit keeps the line matcher's best effort, as before. The second pass found that this check also refused the unset of a key the file does not hold, whenever a line inside another value looked like the key (finding 1, major). Over `notes: "see` / `jira.url: https://x"`, `bd config unset jira.url` failed with "remove the key by hand", and on that key's database-backed route it deleted the row first and then reported jira.url "still set in config.yaml". UnsetYamlConfig and UnsetUserYamlConfig document (false, nil) for an absent key. So commentOutYamlKey now asks the parse first (yamlHoldsKey): when no document holds the key in either spelling, the file is left as it is, and both callers report that nothing changed. A null value holds the key, so does either copy of a section the file writes twice (the matcher comments out both), and a file yaml.v3 cannot parse is taken to hold it, so the matcher's best effort stands there. The review suggested asking only once the collateral check fails. Asking before the matcher also covers a key inside a list item that check never sees: with a mapping beneath it the unset was refused as a value that goes on below, and with no value it was commented out, leaving no leaf to compare. The base did both, and both are now no-ops. The two refusal rows for absent keys moved into TestUnsetOfAnAbsentKeyStillSucceeds, with those two shapes and the flat spelling. A row pins that a line which only looks like the key is still refused when the key is set beside it, and another that the key under the second copy of its section is found. An alias was compared by its anchor's name, which YAML lets a later anchor reuse: with the later anchor's line commented out, the `*r` under backup.remote resolved to an earlier `&r keep`, and the check saw nothing change (finding 2, minor). The leaf now names where the anchor is as well, which commenting a line out never moves for an untouched node, so a key inside a mapping that an alias elsewhere shares still unsets. The third pass found that both checks still failed open when a later document did not parse (finding 1, major). yamlDocuments dropped the documents it had decoded as soon as one did not decode, so yamlHoldsKey took the key to be held and collateralUnsetRefusal left the edit unchecked. Over `notes: "see` / `jira.url: https://x"` / `---` / `other: [unclosed`, an unset of jira.url commented out the second line of notes and reported success, though bd reads that first document and saw notes change. yamlDocuments now returns the documents decoded before the error, and when there are any, they answer: yamlHoldsKey asks only them, and the check compares only them and requires the edit to leave every one of them parsing. So commenting out the only key of a first document cannot let the document that does not parse take its place, where bd could not read the file at all. The document that does not parse, and any after it, has no reading to compare and is read by nobody, so a key only there is not set. A file whose first document does not parse keeps the line matcher's best effort, as before. Listing the leaves copied the whole key path at every level, so its cost grew with the square of the nesting depth, which yaml.v3 lets reach 10000: one unset of a 45 KB config.yaml nested 9000 deep allocated 1.7 GB in 2.8 s (finding 2, minor). The check now refuses a file nested more than 64 keys and list items deep, before the edit or after it, without listing its leaves. That unset is refused in 0.2 s, allocating 24 MB. The CHANGELOG entry names the wrapped plain value, the flat key under a flow-style top level, the general refusal and the refusal of a file nested more than 64 levels deep. It says again that unsetting a key that is not set is a successful no-op in every shape, and that it no longer edits a line inside another value that only looks like the key. The flow-style message is built in one place, which brings unsupportedUnsetShape from cognitive complexity 26 to 13. First pass, validated with bazel-test: //internal/config:config_test 495/495, the cmd/bd unset paths 40/40, and TestEmbeddedConfig* in the embedded lane (24 PASS). On the PR head's code 22 of its new rows failed. Of 15 mutants of its code, 14 were killed; the survivor swaps list indexes for a constant marker, which is equivalent. Unsetting every key of the generated config template, filled in, refuses only the mapping-valued keys it refused before. Second pass, validated with bazel-test: //internal/config:config_test 502/502, the cmd/bd unset paths 28/28 (TestConfigUnset*, TestYamlOnlyConfigWithoutDatabase, TestRemoveStoredSecretRow*, TestCheckConfigUnsetSideEffects_*), and TestEmbeddedConfig* with TestIsDoltLocalOnly_FalseAfterUnset in the embedded lane (23/23). On the first pass's code its rows fail 7 times: the five absent-key rows with a line that looks like the key, the user-global no-op, and the reused anchor name. Of 9 mutants of its code, 8 are killed. The survivor drops the column from the anchor's position, which is equivalent: every anchor on a commented line goes with it. End to end, with bd built by Bazel in a scratch workspace: over that notes value, the database-backed `bd config unset jira.url` prints "Unset jira.url (in database)" and the YAML-only `bd config unset routing.mode` prints "routing.mode was not set in config.yaml", both exiting 0 with config.yaml byte-identical; the first pass's binary failed both with "remove the key by hand". Third pass, validated with bazel-test: //internal/config:config_test 509/509, the cmd/bd unset paths 27/27 (TestConfigUnset*, TestYamlOnlyConfigWithoutDatabase, TestRemoveStoredSecretRow*, TestCheckConfigUnsetSideEffects_*), and TestEmbeddedConfig* with TestIsDoltLocalOnly_FalseAfterUnset in the embedded lane (23/23). On the second pass's code 5 of its 7 rows fail; the other two pin an unset that still succeeds above a document that does not parse and beside a value nested 64 deep. All 10 mutants of its code are killed: dropping the decoded documents, holding the key on any decode error, allowing the edit on any error before it, letting a shorter reading after the edit through, refusing the edit because the document that did not parse still does not, skipping the depth check, not counting lists, an off-by-one in the depth count, and moving the limit either way. End to end, with bd built by Bazel in a scratch workspace, above a document that does not parse: over the review's seed, the database-backed `bd config unset jira.url` prints "Unset jira.url (in database)" and exits 0 with config.yaml byte-identical; the YAML-only unset of routing.mode, set beside a line that looks like it, is refused with nothing written; and sync.remote is commented out. Over the depth-9000 file the unset is refused in 0.2 s at 118 MB peak RSS. Agent-Signature: claude-code-claude-opus-5-5-unknown-reasoning on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.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 | ||
| platforms | ||
| plugins/beads | ||
| release-gates | ||
| schema | ||
| scripts | ||
| test | ||
| tests | ||
| third_party | ||
| 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 | ||
| 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 | ||
| gazelle.go.work | ||
| 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 | ||
| ROADMAP.md | ||
| 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 the project Claude Code, Codex, and Cursor 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 schema 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.
🔌 HTTP Backend (experimental)
A workspace can also talk to a remote bd serve over HTTP instead of opening
a local Dolt database — useful for a thin client against a shared server, or
for embedding beads in another program as a library.
# Point this workspace at a server (verifies the server first; writes nothing on failure)
bd connect https://bd.example.com --expect-project-id my-project
# The everyday commands work the same way: create, show, list, update, close,
# dependencies (including `bd dep tree`), comments, ready/count queries, and
# batch apply all round-trip over the wire with the same semantics as a local
# database. So does `bd ready --claim`, except against an older server or while
# any issue holds an unsatisfied external ref: then it lists and claims in two
# steps rather than one transaction (ledger row L14, linked below).
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd close bd-a1b2 "Fixed"
# Loopback needs no TLS
bd connect http://127.0.0.1:8080
# Forget the server and restore this workspace's previous backend selection
bd connect --clear
HTTP mode is not a byte-for-byte mirror of local mode, though: some
operations are knowingly refused (the wire has no way to express them) or
degrade to a different-but-not-misreadable behavior (for example, a few
unbounded listing shapes lose single-query snapshot isolation and instead
walk the server page by page). Every one of these is a deliberate, tested
row, never a silent gap — see
engdocs/design/http-divergence-ledger.md
for the full, generated list of what differs and why before depending on an
HTTP-backed workspace for a workflow you haven't checked against it. One
refusal to know up front: bd close --claim-next closes nothing over HTTP,
because the wire's batch close cannot carry the claim. Close without it, then
run bd ready --claim.
Cross-repo dependencies
keep their policy over HTTP. The client resolves each external: reference
against its own external_projects configuration. bd dep tree shows the
reference as a leaf, and while it is unsatisfied the issue stays out of
bd ready and bd ready --claim, and bd close refuses it without
--force. A server that advertises enforcing that policy itself is trusted
to do so instead.
Three CLI-level differences are worth knowing up front:
- IDs resolve exactly: an abbreviated id is not expanded (the wire has no substring search), and a missing id is reported as not found after one lookup.
bd update -s closeddoes not recordclosed_by_session(from--sessionorCLAUDE_SESSION_ID), because the wire's update cannot carry it; the close itself happens as usual.bd closedoes record the session.bd reopen's history entry carries the server's own label.- Contributor auto-routing (
routing.*settings) is read from localconfig.yaml/ environment only, never from the server's settings: its targets are local paths.
bd connect writes two things on success: .beads/metadata.json gets
"backend": "http", and a per-user, never-git-tracked sidecar
(.beads/http_target.json) records the server URL and pinned project id. It
never writes a credential to disk. A bearer credential, if the server
requires one, comes from BEADS_HTTP_TOKEN=host[:port]=<token>, then
BEADS_HTTP_TOKEN_COMMAND=host[:port]=<command> (a helper that prints a
token), then the credentials file, then no credential at all. Both variables
must name the server they are for (a pattern without a port matches that
host on any port); a bare value is refused, because it would be sent to
whatever server the workspace's http_target.json names. Connecting to a
non-loopback server over plain http:// is refused by default (a bearer
credential would cross the network unencrypted) — pass --allow-plaintext to
override, or use https://. Switching a workspace that already selects a
different backend needs --force.
Each read (a GET, or the POST batch get) gives its first attempt 15s, from
when the request is sent, to get the server's response headers
(BEADS_HTTP_RESPONSE_HEADER_TIMEOUT: a duration such as 30s, a number of
seconds, or off). A read whose headers do not arrive in time, or whose
connection is reset, is retried once on another connection, and each retry
is logged to stderr with its count. The retry has no header timer, but it
runs on what is left of the 60s bound on the whole request, counted from
when the first attempt was sent: a slow but healthy read still finishes if
the retry's headers and body together fit in that remainder (about 45s after
a header timeout), and one that needs longer now fails at 60s. The header
timer never cuts off a body that is still streaming; the 60s bound still
does. The events:watch stream's connect gets neither the header timer nor
the retry. On Windows a reset connection is retried only when it surfaces as
an early EOF, because the check matches the Unix reset error (ECONNRESET),
which a Windows reset (WSAECONNRESET) is not. A write gets no
header timer (the server answers a write only after it commits, so a large
one can be slow and healthy) and is never retried; if the 60s bound expires
after it was sent but before its headers, it fails with an error naming the
server's host, because it may or may not have been applied. A batch apply of
more than 100 items (a large bd create --graph plan, say) gets 6 minutes
instead of 60s, because bd serve gives such a request its
--large-apply-ceiling (5 minutes by default) and finishes it even after the
client has given up. A server whose ceiling is raised past about 5m15s can
still outlast the client. A dial or TLS timeout stays a plain connection
error, since the server never saw the request, and a connect that fails says
so: it names the address that refused the connection (nothing listening) or
never answered (a filtered port or a down host, after the dialer's 30s), or
the host name that did not resolve. off turns off only the
header timer: a reset read is still retried, and a write's timeout is still
reported as above.
Whether the server applies bd's external-dependency policy itself (the
policy.external_dependencies capability) is remembered for 5 minutes per
server URL and pinned project, in beads/http-policy/ under the user cache
directory, so bd ready does not fetch the server's context before every
listing just to learn it. BEADS_HTTP_POLICY_CACHE_TTL sets that window (a
duration such as 1m, a number of seconds, or off); a server restarted
with a different composition is seen once it passes. Claims and closes never
use the cached answer: they ask the server, since a stale one could skip the
client-side refusal of externally blocked work. A workspace connected without
a project pin is not cached.
bd search, bd show --current and bd recompute-blocked work over HTTP
too, each in its own way. bd search asks the server's listing with its text (q, behind the issues.list.search capability) and
refuses before dialing against a server that does not advertise it. bd list --no-assignee, --title and --id likewise ride the listing's
no_assignee, title and repeatable id, each behind its own capability
(issues.list.noAssignee, issues.list.title, issues.list.ids), and the
rest of bd list's filters (--updated-*, --closed-*, --defer-*,
--due-*, --priority*, the text and external-ref matches, --spec,
--label-pattern/--label-regex, --exclude-type, --no-parent,
--no-labels, --empty-description, --pinned/--no-pinned,
--deferred, --overdue, --mol-type, --wisp-type) ride it behind one
capability, issues.list.filters. Time bounds are resolved on the client as
they are locally; --overdue compares against the server's clock. The
default --parent tree view does not carry those filters yet and refuses one
rather than drop it; --flat or --json applies them to the parent's direct
children (not its whole subtree).
bd show --current finds the actor's in-progress or hooked issue through the
server's boolean query. bd recompute-blocked is a no-op that exits 0: the
server maintains is_blocked on every write, and repairing a stale flag is
done in the server's own workspace (--json reports
{"rows_corrected": 0, "maintained_by": "server"}).
An embedding program that links beads as a library rather than running
cmd/bd registers this backend itself through the public
backend/http package (bdhttp.Register), and can open a
workspace with a credential scoped to one caller via
beads.OpenBestAvailableWith — see that package's doc comment for the
multi-tenant case. This surface is EXPERIMENTAL: pin an exact beads version.
🌐 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
📝 Documentation
- Documentation site | Installing | Sync Concepts | Agent Setup | Copilot CLI Setup | Copilot VS Code MCP | Articles | Sync Branch Mode | Troubleshooting | FAQ
- Contributing: CONTRIBUTING.md (Bazel builds and tests beads: install Bazelisk, then
make test) | Roadmap | Contributor agent instructions