macOS
Homebrewverified ยท 100%
brew install beadsprovider-native install command
brew / rank 1080
Install beads with Homebrew
Memory upgrade for your coding agent. Version 1.1.2 via Homebrew; verified 2026-07-27.
install
Additional install commands
overview
Package summary
Memory upgrade for your coding agent
Project links
Commands and aliases
- bd
- beads
history
Project history and usage
Beads is a distributed graph issue tracker for AI-assisted software work. Its core idea is to give coding agents persistent, structured project memory using a dependency-aware issue graph stored in Dolt rather than ad hoc markdown plans.
Project history
The public GitHub repository for gastownhall/beads was created on 2025-10-12. Its README presents the tool as 'bd - Beads' and describes a cross-platform CLI for macOS, Linux, Windows, and FreeBSD, with Dolt as the version-controlled SQL storage backend.
The project moved quickly from pre-1.0 tags in October 2025 to 1.0.x releases in April and May 2026, followed by a 1.1.0 release candidate in June 2026. The README documents agent setup commands for Codex, Claude Code, Factory.ai Droid, Cursor, Copilot, and other environments, showing that agent integration became part of the main product surface rather than an add-on.
Adoption history
Beads adoption is unusually fast for a young developer tool. The official repository metadata showed 24,977 stars and 1,668 forks on 2026-06-30, and the README documents installation through Homebrew, npm, an install script, Go source builds, Windows support, Arch AUR, and related MCP/PyPI packaging.
The package-manager facts in this batch list Homebrew, Debian, Ubuntu, MacPorts, Nix, and winget entries. That distribution spread matters because Beads is meant to be installed once and used across projects, including by automated agents that need a predictable CLI.
How it is used
Typical use starts with 'bd init' inside a project. Core commands include 'bd ready' for unblocked work, 'bd create' for new tasks, 'bd update --claim' for atomic claiming, 'bd dep add' for dependency links, 'bd show' for details, 'bd prime' for agent context, and 'bd remember' for persistent project memory.
The README documents two storage modes: embedded Dolt by default for a single-writer local database, and server mode for an external dolt sql-server when concurrent writers matter. It also describes git-free and stealth modes for non-git workspaces, CI, monorepos, evaluations, and personal planning.
Why package nerds care
Beads is package-nerd significant because it packages a new workflow assumption: issue tracking as local, mergeable, agent-readable state in the repository neighborhood. It sits at the intersection of CLI issue trackers, local-first databases, Dolt, MCP, and coding-agent coordination.
It is also a good example of a modern package needing many ecosystem edges at once: Homebrew formulae for shell users, npm for Node workflows, PyPI/MCP for agent integrations, winget for Windows, and docs that teach agents as first-class users.
Timeline
- 2025-10-12: gastownhall/beads repository is created.
- 2025-10-14: v0.9.1 is published as an early public release.
- 2026-04-15: v1.0.1 and v1.0.2 are published.
- 2026-05-09: v1.0.4 is published.
- 2026-06-26: v1.1.0-rc.1 is published.
Related projects
- Dolt is the storage backend named by the README.
- Beads Viewer is a companion terminal UI and graph-analysis sidecar for Beads issue exports.
- MCP, Codex, Claude Code, Factory.ai Droid, Cursor, and Copilot appear in the official setup and integration docs as agent/editor surfaces.
Sources
security posture
No protected-tool coverage found yet
No matching local secret-handling manifest was found for beads. Nucleus package metadata is still published here so future coverage has a stable package URL.
Install behavior
- No Homebrew bottle metadata was recorded.
Recommended review
Before unattended agent use, check whether the tool reads plaintext credentials, writes remote state, publishes artifacts, or shells out to plugins.
local files
Configuration and credential file locations
These source-backed paths show where this package keeps local settings or durable credentials. Automic Vault can use them as review targets for secret scanning, migration, and command approval.
Configuration files
Config paths the tool may read or write during local use.
- Unix
~/.beads/config.yaml~/.config/bd/config.yaml<repo>/.beads/config.yaml$BEADS_DIR/config.yaml<repo>/.beads/config.local.yaml
executables
Installed executables
| Command | Kind | Exposure | Note |
|---|---|---|---|
bd | executable | indexed executable | Discovered from the local executable index. |
beads | executable | indexed executable | Discovered from the local executable index. |
freshness
Version and freshness
These signals separate page generation age, package-manager activity, and upstream release comparison. Version lag is warned only when an evidence URL and comparable versions are present.
page generated2026-08-03
manager version1.1.2
manager updated2026-07-27
local dataunknown
upstreamnot available
latest detectednot detected
- okNo freshness warnings were generated.
install metadata
Package metadata
| Package key | brew:beads |
|---|---|
| Version | 1.1.2 |
| Package manager | Homebrew |
| Homepage | https://github.com/gastownhall/beads |
| Repository | https://github.com/gastownhall/beads |
| Last updated | 2026-07-27T03:23:28Z |
| Pulse | updated |
| Bottle | not recorded |
| Service | none declared |
source trail
Generated from repository data
This page is generated by av-web from the private package SQLite artifact built by scripts/generate-pkg-sqlite.py.
Combined YAML source
View the package source record on GitHub.
Used sources
- Geiger risk classifier
- Nucleus package database
- curated configuration and credential file locations
- curated package history
- pkgdb category and tag curation