Skip to content
Back to search

beads-marketplace

MarketplaceWorks with Claude CodeGitHub

Local marketplace for beads plugin development

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/gastownhall/beads with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/gastownhall/beads'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gastownhall-beads/badge.svg)](/listings/gastownhall-beads)

HTML

<a href="/listings/gastownhall-beads"><img src="/api/listings/gastownhall-beads/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

# 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](docs/getting-started/ide-setup.md).

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "beads-marketplace",
  3. "description": "Local marketplace for beads plugin development",
  4. "owner": {
  5. "name": "Steve Yegge"
  6. },
  7. "plugins": [
  8. {
  9. "name": "beads",
  10. "source": "./plugins/beads",
  11. "description": "AI-supervised issue tracker for coding workflows",
  12. "version": "1.3.4"
  13. }
  14. ]
  15. }
README.md · README · 438 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # bd - Beads
  2. **Distributed graph issue tracker for AI agents, powered by [Dolt](https://github.com/dolthub/dolt).**
  3. **Platforms:** macOS, Linux, Windows, FreeBSD
  4. [![License](https://img.shields.io/github/license/gastownhall/beads)](LICENSE)
  5. [![Go Report Card](https://goreportcard.com/badge/github.com/steveyegge/beads)](https://goreportcard.com/report/github.com/steveyegge/beads)
  6. [![Release](https://img.shields.io/github/v/release/gastownhall/beads)](https://github.com/gastownhall/beads/releases)
  7. [![npm version](https://img.shields.io/npm/v/@beads/bd)](https://www.npmjs.com/package/@beads/bd)
  8. [![PyPI](https://img.shields.io/pypi/v/beads-mcp)](https://pypi.org/project/beads-mcp/)
  9. **Docs:** https://beads.gascity.com/
  10. 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.
  11. ```mermaid
  12. flowchart LR
  13. create["bd create<br/>new bead"] --> depgraph["dependency<br/>graph"]
  14. depgraph --> ready["bd ready<br/>claimable work"]
  15. ready --> claim["bd update --claim<br/>agent takes it"]
  16. claim --> close["bd close<br/>work done"]
  17. close -->|blockers released| ready
  18. depgraph <-->|"bd dolt push / pull"| remote[("other machines<br/>and agents")]
  19. ```
  20. ## ⚡ Quick Start
  21. ```bash
  22. # Install beads CLI (system-wide - don't clone this repo into your project)
  23. curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
  24. # Initialize in YOUR project
  25. cd your-project
  26. bd init
  27. # Optional: refresh or install richer instructions for your agent
  28. bd setup codex # Codex CLI - installs skill, AGENTS.md guidance, and hooks
  29. bd setup claude # Claude Code - installs hooks/settings
  30. bd setup factory # Factory.ai Droid - creates/updates AGENTS.md
  31. ```
  32. **Note:** Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.
  33. `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](docs/getting-started/ide-setup.md).
  34. 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.
  35. If your agent is not covered by `bd setup`, add this minimal `AGENTS.md` section:
  36. ```markdown
  37. This project uses bd (beads) for issue tracking.
  38. - Run `bd prime` for workflow context and command guidance.
  39. - Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
  40. - Use `bd remember "a project insight"` for durable project facts; keep per-operator preferences in your harness's own memory.
  41. - Do not use markdown TODO lists for task tracking.
  42. ```
  43. ## 🛠 Features
  44. * **[Dolt](https://github.com/dolthub/dolt)-Powered:** Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
  45. * **Agent-Optimized:** JSON output, dependency tracking, and auto-ready task detection.
  46. * **Zero Conflict:** Hash-based IDs (`bd-a1b2`) prevent merge collisions in multi-agent/multi-branch workflows.
  47. * **Compaction:** Semantic "memory decay" summarizes old closed tasks to save context window.
  48. * **Messaging:** Message issue type with threading (`--thread`), ephemeral lifecycle, and mail delegation.
  49. * **Graph Links:** `relates-to`, `duplicates`, `supersedes`, and `replies-to` for knowledge graphs.
  50. ## 📖 Essential Commands
  51. | Command | Action |
  52. | --- | --- |
  53. | `bd ready` | List tasks with no open blockers. |
  54. | `bd create "Title" -p 0` | Create a P0 task. |
  55. | `bd update <id> --claim` | Atomically claim a task (sets assignee + in_progress). |
  56. | `bd dep add <child> <parent>` | Link tasks (blocks, related, parent-child). |
  57. | `bd show <id>` | View task details and audit trail. |
  58. | `bd prime` | Print agent workflow context and persistent memories. |
  59. | `bd remember "a project insight"` | Store project memory that `bd prime` injects later. |
  60. | `bd remember some-key` | Recall an exact key, including long and dotted ones like `api.v2`; a missing key fails without storing anything. Use `--key some-key` to write single-word content, and `bd recall` for keys with other characters. |
  61. ## 🔗 Hierarchy & Workflow
  62. Beads supports hierarchical IDs for epics:
  63. * `bd-a3f8` (Epic)
  64. * `bd-a3f8.1` (Task)
  65. * `bd-a3f8.1.1` (Sub-task)
  66. **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](#-git-free-usage) below.
  67. **Contributor vs Maintainer:** When working on open-source projects:
  68. * **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.
  69. * **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.
  70. ## 📦 Installation
  71. ```bash
  72. brew install beads # macOS / Linux (recommended)
  73. npm install -g @beads/bd # Node.js users
  74. ```
  75. **Other methods:** [install script](docs/getting-started/installation.md#quick-install-script-all-platforms) | [go install](docs/getting-started/installation.md#a-note-on-go-install-capability) | [from source](docs/getting-started/installation.md#build-dependencies-contributors-only) | [Windows](docs/getting-started/installation.md#windows-11) | [Arch AUR](docs/getting-started/installation.md#linux)
  76. **Requirements:** macOS, Linux, Windows, or FreeBSD. See [docs/getting-started/installation.md](docs/getting-started/installation.md) for complete installation guide.
  77. **Upgrading?** Replacing the binary is not always the whole story. Short
  78. version: sync remote-backed databases with your current `bd`, back up with
  79. `bd export --all`, upgrade the binary, then run `bd info --whats-new`,
  80. `bd hooks install`, and `bd version`. If the upgrade crosses a schema
  81. migration on a remote-backed database, exactly one designated clone runs
  82. `bd migrate schema` and `bd dolt push`; other clones install the new
  83. binary and run `bd bootstrap`. See the full
  84. [upgrade guide](https://beads.gascity.com/getting-started/upgrading)
  85. or [docs/getting-started/installation.md](docs/getting-started/installation.md#updating-bd).
  86. ### Security And Verification
  87. Command and credential-target settings must come from your shell environment or
  88. user configuration, not `.beads/.env`. `.beads/.env` only admits non-command
  89. `BEADS_*` and `BD_*` variables plus the two Dolt remote credential variables
  90. (`DOLT_REMOTE_USER`, `DOLT_REMOTE_PASSWORD`); Beads ignores credential commands,
  91. mail delegates, editor, pager, Dolt executable/host/credential-file/root-path
  92. overrides, the rest of the dolt-owned `DOLT_*` namespace (such as
  93. `DOLT_SSH_COMMAND` and `DOLT_PAGER`), and non-Beads process variables (such as
  94. `GIT_*`, `SSH_*`, `LD_*`, and `DYLD_*`) in that file and prints a warning for
  95. each. Any `BEADS_*` or `BD_*` key named as a command or executable (ending in
  96. `_COMMAND`, `_BIN` or `_BINARY`) is ignored the same way, as are the http
  97. backend's bearer token `BEADS_HTTP_TOKEN` and plaintext grant
  98. `BEADS_HTTP_ALLOW_INSECURE`, the token file `bd serve` accepts bearers from
  99. (`BEADS_SERVE_TOKEN_FILE`), and the files bd writes to: the heap profile and
  100. MemStats summary (`BEADS_MEM_PROFILE`, `BEADS_MEM_STATS`) and the proxied Dolt
  101. server's log (`BEADS_PROXIED_SERVER_LOG`). Values in `.beads/.env` are taken
  102. literally: a value that uses `$VAR` or `${VAR}` is ignored with a warning
  103. instead of being filled in from your environment, so a committed file cannot
  104. copy a secret out of your environment into a setting the workspace sends
  105. elsewhere. Write the value out, or set it in your shell.
  106. `bd config set mail.delegate "gt mail"` writes to user-global YAML rather than
  107. the replicated database; the workspace settings API rejects `mail.delegate`.
  108. Mail delegation also ignores project `.beads/config.yaml`; only shell environment
  109. variables and user-global YAML can select the delegate.
  110. Before trusting any downloaded binary, verify its checksum against the release `checksums.txt`.
  111. The install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.
  112. 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`.
  113. See [docs/reference/antivirus.md](docs/reference/antivirus.md) for Windows AV false-positive guidance and verification workflow.
  114. ## 💾 Storage Modes
  115. Beads uses [Dolt](https://github.com/dolthub/dolt) as its database. Two modes:
  116. - **Embedded (default)** — `bd init`. Dolt runs in-process, data lives in
  117. `.beads/embeddeddolt/`, single writer. Recommended for most users.
  118. - **Server** — `bd init --server`. Connects to an external `dolt sql-server`
  119. for multiple concurrent writers; data lives in `.beads/dolt/`.
  120. Cross-machine sync uses `bd dolt push` / `bd dolt pull` against
  121. `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is an export for
  122. viewers and interchange, not the source of truth or a backup. Back up and
  123. migrate between modes with `bd backup`; reclaim space with `bd prune` /
  124. `bd purge`.
  125. Full detail — connection flags, sockets, maintenance, backup, and migration —
  126. in the [Dolt backend guide](docs/architecture/dolt.md).
  127. ### Schema Version Guard
  128. `bd` checks the database schema version at open time. If the database has been
  129. migrated by a newer binary and an older binary tries to open it, `bd` exits
  130. with an actionable error rather than issuing queries that fail with cryptic SQL
  131. errors:
  132. ````
  133. schema version mismatch: database is at v45, binary knows up to v42 (3 migrations ahead)
  134. Your bd binary is stale. Queries for dropped or renamed columns will fail
  135. with cryptic SQL errors (e.g. "column X could not be found in any table in scope").
  136. Rebuild from main:
  137. CGO_ENABLED=0 go build -tags gms_pure_go ./cmd/bd
  138. Or install the latest release:
  139. CGO_ENABLED=0 go install -tags gms_pure_go github.com/steveyegge/beads/cmd/bd@latest
  140. To proceed despite the risk (some read commands may still work):
  141. BD_IGNORE_SCHEMA_SKEW=1 bd <command>
  142. bd --ignore-schema-skew <command>
  143. ````
  144. **When this fires:** only when the database schema is *ahead* of the binary
  145. (a newer binary migrated the database; this binary doesn't know those
  146. migrations). Normal upgrades, where the binary migrates the database forward,
  147. are unaffected. The check runs whenever a store opens: embedded, server mode,
  148. a proxied-server workspace, and `bd serve` at startup. A `bd serve` that was
  149. already running when a newer `bd` migrated the database keeps serving until it
  150. is restarted, and proxied `--dry-run`/`--inspect` previews don't check, so
  151. restart long-running servers after migrating with a newer `bd`.
  152. **Escape hatch:** `BD_IGNORE_SCHEMA_SKEW=1` (or `--ignore-schema-skew`) bypasses
  153. the guard with a warning on stderr. Use this only if you know the forward
  154. migrations are additive and safe for your specific workload.
  155. ## 🔌 HTTP Backend (experimental)
  156. A workspace can also talk to a remote `bd serve` over HTTP instead of opening
  157. a local Dolt database — useful for a thin client against a shared server, or
  158. for embedding beads in another program as a library.
  159. ```bash
  160. # Point this workspace at a server (verifies the server first; writes nothing on failure)
  161. bd connect https://bd.example.com --expect-project-id my-project
  162. # The everyday commands work the same way: create, show, list, update, close,
  163. # dependencies (including `bd dep tree`), comments, ready/count queries, and
  164. # batch apply all round-trip over the wire with the same semantics as a local
  165. # database. So does `bd ready --claim`, except against an older server or while
  166. # any issue holds an unsatisfied external ref: then it lists and claims in two
  167. # steps rather than one transaction (ledger row L14, linked below).
  168. bd create "Fix auth bug" -p 1 -t bug
  169. bd ready --json
  170. bd close bd-a1b2 "Fixed"
  171. # Loopback needs no TLS
  172. bd connect http://127.0.0.1:8080
  173. # Forget the server and restore this workspace's previous backend selection
  174. bd connect --clear
  175. ```
  176. HTTP mode is not a byte-for-byte mirror of local mode, though: some
  177. operations are knowingly refused (the wire has no way to express them) or
  178. degrade to a different-but-not-misreadable behavior (for example, a few
  179. unbounded listing shapes lose single-query snapshot isolation and instead
  180. walk the server page by page). Every one of these is a deliberate, tested
  181. row, never a silent gap — see
  182. [`engdocs/design/http-divergence-ledger.md`](engdocs/design/http-divergence-ledger.md)
  183. for the full, generated list of what differs and why before depending on an
  184. HTTP-backed workspace for a workflow you haven't checked against it. One
  185. refusal to know up front: `bd close --claim-next` closes nothing over HTTP,
  186. because the wire's batch close cannot carry the claim. Close without it, then
  187. run `bd ready --claim`.
  188. [Cross-repo dependencies](docs/core-concepts/dependencies.md#cross-repo-dependencies)
  189. keep their policy over HTTP. The client resolves each `external:` reference
  190. against its own `external_projects` configuration. `bd dep tree` shows the
  191. reference as a leaf, and while it is unsatisfied the issue stays out of
  192. `bd ready` and `bd ready --claim`, and `bd close` refuses it without
  193. `--force`. A server that advertises enforcing that policy itself is trusted
  194. to do so instead.
  195. Three CLI-level differences are worth knowing up front:
  196. - IDs resolve exactly: an abbreviated id is not expanded (the wire has no
  197. substring search), and a missing id is reported as not found after one
  198. lookup.
  199. - `bd update -s closed` does not record `closed_by_session` (from `--session`
  200. or `CLAUDE_SESSION_ID`), because the wire's update cannot carry it; the
  201. close itself happens as usual. `bd close` does record the session. `bd
  202. reopen`'s history entry carries the server's own label.
  203. - Contributor auto-routing (`routing.*` settings) is read from local
  204. `config.yaml` / environment only, never from the server's settings: its
  205. targets are local paths.
  206. `bd connect` writes two things on success: `.beads/metadata.json` gets
  207. `"backend": "http"`, and a per-user, never-git-tracked sidecar
  208. (`.beads/http_target.json`) records the server URL and pinned project id. It
  209. never writes a credential to disk. A bearer credential, if the server
  210. requires one, comes from `BEADS_HTTP_TOKEN=host[:port]=<token>`, then
  211. `BEADS_HTTP_TOKEN_COMMAND=host[:port]=<command>` (a helper that prints a
  212. token), then the credentials file, then no credential at all. Both variables
  213. must name the server they are for (a pattern without a port matches that
  214. host on any port); a bare value is refused, because it would be sent to
  215. whatever server the workspace's `http_target.json` names. Connecting to a
  216. non-loopback server over plain `http://` is refused by default (a bearer
  217. credential would cross the network unencrypted) — pass `--allow-plaintext` to
  218. override, or use `https://`. Switching a workspace that already selects a
  219. different backend needs `--force`.
  220. Each read (a GET, or the POST batch get) gives its first attempt 15s, from
  221. when the request is sent, to get the server's response headers
  222. (`BEADS_HTTP_RESPONSE_HEADER_TIMEOUT`: a duration such as `30s`, a number of
  223. seconds, or `off`). A read whose headers do not arrive in time, or whose
  224. connection is reset, is retried once on another connection, and each retry
  225. is logged to stderr with its count. The retry has no header timer, but it
  226. runs on what is left of the 60s bound on the whole request, counted from
  227. when the first attempt was sent: a slow but healthy read still finishes if
  228. the retry's headers and body together fit in that remainder (about 45s after
  229. a header timeout), and one that needs longer now fails at 60s. The header
  230. timer never cuts off a body that is still streaming; the 60s bound still
  231. does. The events:watch stream's connect gets neither the header timer nor
  232. the retry. On Windows a reset connection is retried only when it surfaces as
  233. an early EOF, because the check matches the Unix reset error (`ECONNRESET`),
  234. which a Windows reset (`WSAECONNRESET`) is not. A write gets no
  235. header timer (the server answers a write only after it commits, so a large
  236. one can be slow and healthy) and is never retried; if the 60s bound expires
  237. after it was sent but before its headers, it fails with an error naming the
  238. server's host, because it may or may not have been applied. A batch apply of
  239. more than 100 items (a large `bd create --graph` plan, say) gets 6 minutes
  240. instead of 60s, because `bd serve` gives such a request its
  241. `--large-apply-ceiling` (5 minutes by default) and finishes it even after the
  242. client has given up. A server whose ceiling is raised past about 5m15s can
  243. still outlast the client. A dial or TLS timeout stays a plain connection
  244. error, since the server never saw the request, and a connect that fails says
  245. so: it names the address that refused the connection (nothing listening) or
  246. never answered (a filtered port or a down host, after the dialer's 30s), or
  247. the host name that did not resolve. `off` turns off only the
  248. header timer: a reset read is still retried, and a write's timeout is still
  249. reported as above.
  250. Whether the server applies bd's external-dependency policy itself (the
  251. `policy.external_dependencies` capability) is remembered for 5 minutes per
  252. server URL and pinned project, in `beads/http-policy/` under the user cache
  253. directory, so `bd ready` does not fetch the server's context before every
  254. listing just to learn it. `BEADS_HTTP_POLICY_CACHE_TTL` sets that window (a
  255. duration such as `1m`, a number of seconds, or `off`); a server restarted
  256. with a different composition is seen once it passes. Claims and closes never
  257. use the cached answer: they ask the server, since a stale one could skip the
  258. client-side refusal of externally blocked work. A workspace connected without
  259. a project pin is not cached.
  260. `bd search`, `bd show --current` and `bd recompute-blocked` work over HTTP
  261. too, each in its own way. `bd search` asks the server's listing with its text (`q`, behind the `issues.list.search` capability) and
  262. refuses before dialing against a server that does not advertise it. `bd list
  263. --no-assignee`, `--title` and `--id` likewise ride the listing's
  264. `no_assignee`, `title` and repeatable `id`, each behind its own capability
  265. (`issues.list.noAssignee`, `issues.list.title`, `issues.list.ids`), and the
  266. rest of `bd list`'s filters (`--updated-*`, `--closed-*`, `--defer-*`,
  267. `--due-*`, `--priority*`, the text and external-ref matches, `--spec`,
  268. `--label-pattern`/`--label-regex`, `--exclude-type`, `--no-parent`,
  269. `--no-labels`, `--empty-description`, `--pinned`/`--no-pinned`,
  270. `--deferred`, `--overdue`, `--mol-type`, `--wisp-type`) ride it behind one
  271. capability, `issues.list.filters`. Time bounds are resolved on the client as
  272. they are locally; `--overdue` compares against the server's clock. The
  273. default `--parent` tree view does not carry those filters yet and refuses one
  274. rather than drop it; `--flat` or `--json` applies them to the parent's direct
  275. children (not its whole subtree).
  276. `bd show --current` finds the actor's in-progress or hooked issue through the
  277. server's boolean query. `bd recompute-blocked` is a no-op that exits 0: the
  278. server maintains `is_blocked` on every write, and repairing a stale flag is
  279. done in the server's own workspace (`--json` reports
  280. `{"rows_corrected": 0, "maintained_by": "server"}`).
  281. An embedding program that links beads as a library rather than running
  282. `cmd/bd` registers this backend itself through the public
  283. [`backend/http`](backend/http) package (`bdhttp.Register`), and can open a
  284. workspace with a credential scoped to one caller via
  285. `beads.OpenBestAvailableWith` — see that package's doc comment for the
  286. multi-tenant case. This surface is EXPERIMENTAL: pin an exact beads version.
  287. ## 🧹 Compacting Claude Rules
  288. `bd rules audit` scans `.claude/rules/*.md` for contradictions and
  289. near-duplicates; `bd rules compact` merges related rules into one composite.
  290. ```bash
  291. bd rules compact --auto # Preview: composite, dropped lines, backups, deletes
  292. bd rules compact --auto --force # Apply
  293. ```
  294. Compact only previews unless you pass `--force`. A composite keeps only the
  295. `**Do:**` and `**Don't:**` lines of its sources, and the preview lists every
  296. other line it drops. Applying writes the composite, copies each source to
  297. `<name>.md.backup`, then deletes the sources; it refuses a group whose
  298. composite or backup path already exists. To undo a merge, delete the composite
  299. and rename each `<name>.md.backup` back to `<name>.md`.
  300. ## 🔁 GitHub Issues Sync
  301. `bd github sync` (and `bd github pull`/`push`) syncs the one repository named
  302. by `github.owner` and `github.repo`, but a database can hold beads from
  303. several repositories. In releases after v1.3.2, sync matches, fetches and
  304. updates only beads whose issue URL points at the configured repository, so
  305. pulling issue 1313 from a second repository creates a new bead instead of
  306. overwriting the bead linked to the first repository's issue 1313. A
  307. `github:<number>` ref has no repository and is always read as the configured
  308. one. A repository you renamed or transferred keeps syncing whichever of its
  309. names the config holds: GitHub redirects a former name to the repository, and
  310. sync asks GitHub which repository each other name your beads link under
  311. belongs to now (one request per name), so beads linked under the old name and
  312. under the new one stay matched to their issues, and a pull relinks them to the
  313. current URL. If the old name now belongs to another repository, beads still
  314. linked under it count as another repository's: relink them
  315. (`bd update <id> --external-ref <new-url>`), or the next pull imports their
  316. issues again as new beads. If GitHub gives no answer to one of these requests
  317. (any failure but a 404: an outage, a dropped connection, a rate limit, a
  318. refused token), the command stops with an error that names the repository,
  319. instead of syncing without knowing which beads are the configured
  320. repository's: a sync that skipped them would move its cursor past their edits,
  321. and a later sync could overwrite those edits with no conflict. If the failure
  322. is temporary, run the command again. If the error names another repository
  323. your beads link to and GitHub refuses the token for it (a 403), give the token
  324. read access to it. If the name is a former name of the configured repository,
  325. relinking those beads to their issues' current URLs also ends the lookup.
  326. ## 🌐 Community Tools
  327. See [docs/community-tools.md](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.
  328. See [docs/related-projects.md](docs/related-projects.md) for adjacent or complementary projects that solve different problems in the same neighborhood.
  329. ## 🚀 Git-Free Usage
  330. Beads works without git. The Dolt database is the storage backend — git
  331. integration (hooks, repo discovery, identity) is optional.
  332. ```bash
  333. # Initialize without git
  334. export BEADS_DIR=/path/to/your/project/.beads
  335. bd init --quiet --stealth
  336. # All core commands work with zero git calls
  337. bd create "Fix auth bug" -p 1 -t bug
  338. bd ready --json
  339. bd update bd-a1b2 --claim
  340. bd prime
  341. bd close bd-a1b2 "Fixed"
  342. ```
  343. `BEADS_DIR` tells bd where to put the `.beads/` database directory,
  344. bypassing git repo discovery. `--stealth` sets `no-git-ops: true` in
  345. config, disabling bd's own git hook installation and git commands. It
  346. does not stop Dolt network sync; set `dolt.local-only: true` for that.
  347. This is useful for:
  348. - **Non-git VCS** (Sapling, Jujutsu, Piper) — no `.git/` directory needed
  349. - **Monorepos** — point `BEADS_DIR` at a specific subdirectory
  350. - **CI/CD** — isolated task tracking without repo-level side effects
  351. - **Evaluation/testing** — ephemeral databases in `/tmp`
  352. ## 📝 Documentation
  353. * [Documentation site](https://beads.gascity.com/) | [Installing](docs/getting-started/installation.md) | [Sync Concepts](docs/core-concepts/sync-concepts.md) | [Agent Setup](docs/getting-started/ide-setup.md) | [Copilot CLI Setup](docs/integrations/copilot-cli.md) | [Copilot VS Code MCP](docs/integrations/github-copilot.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/reference/protected-branches.md) | [Troubleshooting](docs/reference/troubleshooting.md) | [FAQ](docs/reference/faq.md)
  354. * Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) (Bazel builds and tests beads: install [Bazelisk](https://github.com/bazelbuild/bazelisk), then `make test`) | [Roadmap](ROADMAP.md) | [Contributor agent instructions](AGENTS.md)
  355. * [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gastownhall/beads)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.