# Install beads with Homebrew, apt, Nix, winget, MacPorts Memory upgrade for your coding agent. Version 1.1.0 via Homebrew; verified 2026-07-04. ## Install ```sh sudo av install brew:beads ``` Additional install commands: ### macOS - Homebrew (100%): ```sh brew install beads ``` Evidence: local Homebrew formula metadata - MacPorts (94%): ```sh sudo port install bd ``` Evidence: MacPorts ports tree: sysutils/bd/Portfile from https://api.github.com/repos/macports/macports-ports/git/trees/master?recursive=1 ### Linux - Debian apt (92%): ```sh sudo apt install beads ``` Evidence: Debian stable package indexes: beads from https://deb.debian.org/debian/dists/stable/main/binary-amd64/Packages.xz - Nix (92%): ```sh nix profile install nixpkgs#beads ``` Evidence: nixpkgs package indexes: pkgs/by-name/be/beads/package.nix from https://api.github.com/repos/NixOS/nixpkgs/git/trees/master?recursive=1 ### Windows - winget (92%): ```sh winget install --id GasTownHall.Beads -e ``` Evidence: Windows Package Manager source index: GasTownHall.Beads from https://cdn.winget.microsoft.com/cache/source.msix ## Package facts - **Package key:** brew:beads - **Package manager:** Homebrew - **Package manager page:** - **Version:** 1.1.0 - **Source summary:** Memory upgrade for your coding agent - **Homepage:** - **Repository:** - **Upstream docs:** - **License:** MIT - **Source archive:** - **Last updated:** 2026-07-04T10:22:22+03:00 - **Generated:** 2026-07-08T07:18:31+00:00 ## Executables - bd (cli) - beads (cli) - bd (alias) - beads (alias) ## Dependencies - dolt - icu4c@78 ## Build dependencies - go ## Install behavior - Post-install hook: not defined - Bottle: available on arm64_linux, arm64_sequoia, arm64_sonoma, arm64_tahoe, sonoma, x86_64_linux ## Freshness - Page generated: 2026-07-08 - Package-manager version: 1.1.0 - Package-manager updated: 2026-07-04 - Local data: ok - Upstream repository: https://github.com/gastownhall/beads - Upstream latest detected: v1.1.0 (current) ## 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 - - - - source_facts.package-manager ## Security Notes 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. ## 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 - Unix: ~/.beads/config.yaml, ~/.config/bd/config.yaml, /.beads/config.yaml, $BEADS_DIR/config.yaml, /.beads/config.local.yaml ## 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:** - **Deprecated:** no - **Disabled:** no - **Keg Only:** no - **URL Keys:** head, stable ## Other Package-Manager Records - Debian apt - beads - 1.1.22-1+b5: normalized package name match | Debian stable package indexes: beads from https://deb.debian.org/debian/dists/stable/main/binary-amd64/Packages.xz | 2-DE electrophoresis gel image spot detection | http://pappso.inrae.fr/bioinfo/beads - Nix - beads: normalized package name match | nixpkgs package indexes: pkgs/by-name/be/beads/package.nix from https://api.github.com/repos/NixOS/nixpkgs/git/trees/master?recursive=1 - Ubuntu apt - beads - 1.1.22-1build4: normalized package name match | Ubuntu 24.04 LTS package indexes: beads from https://archive.ubuntu.com/ubuntu/dists/noble/universe/binary-amd64/Packages.gz | 2-DE electrophoresis gel image spot detection | http://pappso.inrae.fr/bioinfo/beads - winget - GasTownHall.Beads: normalized package name match | Windows Package Manager source index: GasTownHall.Beads from https://cdn.winget.microsoft.com/cache/source.msix - MacPorts - bd: installed executable or alias match | MacPorts ports tree: sysutils/bd/Portfile from https://api.github.com/repos/macports/macports-ports/git/trees/master?recursive=1 - Debian apt - bd - 1.03-5: installed executable or alias match | Debian stable package indexes: bd from https://deb.debian.org/debian/dists/stable/main/binary-amd64/Packages.xz | quickly go back to a specific parent directory in bash | https://github.com/vigneshwaranr/bd - Ubuntu apt - bd - 1.03-3: installed executable or alias match | Ubuntu 24.04 LTS package indexes: bd from https://archive.ubuntu.com/ubuntu/dists/noble/universe/binary-amd64/Packages.gz | quickly go back to a specific parent directory in bash | https://github.com/vigneshwaranr/bd ## Related links - [Source-control packages](https://www.automicvault.com/pkg/source-control-tools/) - Belongs to a source-control command family. - [Terminal utility packages](https://www.automicvault.com/pkg/terminal-utilities/) - Matched terminal and command-line workflow metadata. - [Text processing packages](https://www.automicvault.com/pkg/text-processing-tools/) - Matched text, document, or structured-data processing metadata. - [Developer build packages](https://www.automicvault.com/pkg/developer-build-tools/) - Matched build, compiler, generator, or developer workflow metadata. - [dolt](https://www.automicvault.com/pkg/brew/dolt/) - Runtime dependency declared by Homebrew. - [go](https://www.automicvault.com/pkg/brew/go/) - Build dependency declared by Homebrew. - [gascity](https://www.automicvault.com/pkg/brew/gascity/) - Popular package that depends on this formula. - [gastown](https://www.automicvault.com/pkg/brew/gastown/) - Popular package that depends on this formula. - [letta-code](https://www.automicvault.com/pkg/brew/letta-code/) - Shares av.db curated category or tags: cli, coding-agent, developer-tools, memory. - [cline](https://www.automicvault.com/pkg/brew/cline/) - Shares av.db curated category or tags: cli, coding-agent, developer-tools. - [hermes-agent](https://www.automicvault.com/pkg/brew/hermes-agent/) - Shares av.db curated category or tags: cli, developer-tools, memory. - [kimi-cli](https://www.automicvault.com/pkg/brew/kimi-cli/) - Shares av.db curated category or tags: cli, coding-agent, developer-tools. - [mistral-vibe](https://www.automicvault.com/pkg/brew/mistral-vibe/) - Shares av.db curated category or tags: cli, coding-agent, developer-tools. - [qwen-code](https://www.automicvault.com/pkg/brew/qwen-code/) - Shares av.db curated category or tags: cli, coding-agent, developer-tools. - [memray](https://www.automicvault.com/pkg/brew/memray/) - Shares av.db curated category or tags: cli, developer-tools, memory. - [beads_viewer](https://www.automicvault.com/pkg/brew/beads-viewer/) - Package names and metadata indicate a similar tool family. Shared terms: beads, cli, developer, developer-tools. ## Combined YAML source View the package source record on GitHub. [combined/beads.yml](https://github.com/automic-vault/db/blob/main/combined/beads.yml) ## Sources - Nucleus package database - Geiger risk classifier - package-page enrichment - curated configuration and credential file locations - curated package history - package version freshness - av.db category and tag curation - package relationship graph - external package-manager database matches - cross-ecosystem install command graph