install

Additional install commands

macOS

Homebrewverified · 100%

brew install beads

local Homebrew formula metadata

MacPortsverified · 94%

sudo port install bd

MacPorts ports tree · sysutils/bd/Portfile · source: api.github.com

Linux

Debian aptverified · 92%

sudo apt install beads

Debian stable package indexes · beads · source: deb.debian.org

Nixverified · 92%

nix profile install nixpkgs#beads

nixpkgs package indexes · pkgs/by-name/be/beads/package.nix · source: api.github.com

Windows

Windows Package Managerverified · 92%

winget install --id GasTownHall.Beads -e

Windows Package Manager source index · GasTownHall.Beads · source: cdn.winget.microsoft.com

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

https://api.github.com/repos/gastownhall/beads
https://api.github.com/repos/gastownhall/beads/releases
https://raw.githubusercontent.com/gastownhall/beads/main/README.md
source_facts.package-manager

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 post-install hook is recorded in formula metadata.
Homebrew bottle metadata is available for 6 platform targets.
Installs with 2 runtime dependencies.
Build metadata lists 1 build dependencies.

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`	cli	global executable
`beads`	cli	global executable

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-07-07

manager version1.1.0

manager updated2026-07-04

local dataok

upstreamcurrent

latest detectedv1.1.0

https://github.com/gastownhall/beads

okNo freshness warnings were generated.

install metadata

Package metadata

Package key	brew:beads
Version	1.1.0
Package manager	Homebrew
Package manager page	https://formulae.brew.sh/formula/beads
Homepage	https://github.com/gastownhall/beads
Repository	https://github.com/gastownhall/beads
Upstream docs	https://gastownhall.github.io/beads
License	MIT
Source archive	https://github.com/gastownhall/beads/archive/refs/tags/v1.1.0.tar.gz
Last updated	2026-07-04T10:22:22+03:00
Pulse	updated
Dependencies	dolt, icu4c@78
Build dependencies	go
Bottle	available (on arm64_linux, arm64_sequoia, arm64_sonoma, arm64_tahoe, sonoma, x86_64_linux)
Homebrew post-install	not defined
Service	none declared

registry facts

Source database details

Source Database	Homebrew formula API
Tap	homebrew/core
Full Name	beads
Version Scheme	0
Revision	0
Head Version	HEAD
Bottle Stable Root URL	https://ghcr.io/v2/homebrew/core
Deprecated	no
Disabled	no
Keg Only	no
URL Keys	head stable

source database matches

Other package-manager records

Matches are pulled from external package-manager indexes and kept separate from local Automic Vault package links.

Debian apt95%

beads 1.1.22-1+b5

2-DE electrophoresis gel image spot detection

http://pappso.inrae.fr/bioinfo/beads

sudo apt install beads

Section: science
Architecture: amd64
Source Package: beads
13 dependencies
normalized package name match
Matched by: Beads

Debian stable package indexes · deb.debian.org · Debian stable package indexes: beads from https://deb.debian.org/debian/dists/stable/main/binary-amd64/Packages.xz

Nix95%

beads

nix profile install nixpkgs#beads

normalized package name match
Matched by: Beads

nixpkgs package indexes · api.github.com · nixpkgs package indexes: pkgs/by-name/be/beads/package.nix from https://api.github.com/repos/NixOS/nixpkgs/git/trees/master?recursive=1

Ubuntu apt95%

beads 1.1.22-1build4

2-DE electrophoresis gel image spot detection

http://pappso.inrae.fr/bioinfo/beads

sudo apt install beads

Section: universe/science
Architecture: amd64
13 dependencies
normalized package name match
Matched by: Beads

Ubuntu 24.04 LTS package indexes · archive.ubuntu.com · Ubuntu 24.04 LTS package indexes: beads from https://archive.ubuntu.com/ubuntu/dists/noble/universe/binary-amd64/Packages.gz

winget95%

GasTownHall.Beads

winget install --id GasTownHall.Beads -e

normalized package name match
Matched by: Beads

Windows Package Manager source index · cdn.winget.microsoft.com · Windows Package Manager source index: GasTownHall.Beads from https://cdn.winget.microsoft.com/cache/source.msix

MacPorts94%

bd

sudo port install bd

installed executable or alias match
Matched by: Bd

MacPorts ports tree · api.github.com · MacPorts ports tree: sysutils/bd/Portfile from https://api.github.com/repos/macports/macports-ports/git/trees/master?recursive=1

Debian apt92%

bd 1.03-5

quickly go back to a specific parent directory in bash

https://github.com/vigneshwaranr/bd

sudo apt install bd

Section: utils
Architecture: all
1 dependencies
installed executable or alias match
Matched by: Bd

Debian stable package indexes · deb.debian.org · Debian stable package indexes: bd from https://deb.debian.org/debian/dists/stable/main/binary-amd64/Packages.xz

Ubuntu apt92%

bd 1.03-3

quickly go back to a specific parent directory in bash

https://github.com/vigneshwaranr/bd

sudo apt install bd

Section: universe/utils
Architecture: all
1 dependencies
installed executable or alias match
Matched by: Bd

Ubuntu 24.04 LTS package indexes · archive.ubuntu.com · Ubuntu 24.04 LTS package indexes: bd from https://archive.ubuntu.com/ubuntu/dists/noble/universe/binary-amd64/Packages.gz

package graph

Links come from deterministic package relationships, av.db category and tag curation, ecosystem matches, and package hub membership.

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.

combined/beads.yml

Used sources

Geiger risk classifier
Nucleus package database
av.db category and tag curation
cross-ecosystem install command graph
curated configuration and credential file locations
curated package history
external package-manager database matches
package relationship graph
package version freshness
package-page enrichment

Install beads with Homebrew, apt, Nix, winget, MacPorts