https://github.com/gastownhall/beads
Beads - A memory upgrade for your coding agent
https://github.com/gastownhall/beads
agents claude-code coding
Last synced: 3 days ago
JSON representation
Beads - A memory upgrade for your coding agent
- Host: GitHub
- URL: https://github.com/gastownhall/beads
- Owner: gastownhall
- License: mit
- Created: 2025-10-12T03:09:46.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T21:32:59.000Z (5 days ago)
- Last Synced: 2026-03-31T21:35:59.039Z (5 days ago)
- Topics: agents, claude-code, coding
- Language: Go
- Homepage:
- Size: 6.41 GB
- Stars: 20,040
- Watchers: 77
- Forks: 1,326
- Open Issues: 48
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# bd - Beads
**Distributed graph issue tracker for AI agents, powered by [Dolt](https://github.com/dolthub/dolt).**
**Platforms:** macOS, Linux, Windows, FreeBSD
[](LICENSE)
[](https://goreportcard.com/report/github.com/steveyegge/beads)
[](https://github.com/steveyegge/beads/releases)
[](https://www.npmjs.com/package/@beads/bd)
[](https://pypi.org/project/beads-mcp/)
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.
## ⚡ Quick Start
```bash
# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# Initialize in YOUR project
cd your-project
bd init
# Tell your agent
echo "Use 'bd' for task tracking" >> 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.
## 🛠 Features
* **[Dolt](https://github.com/dolthub/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`, and `replies_to` for 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 --claim` | Atomically claim a task (sets assignee + in_progress). |
| `bd dep add ` | Link tasks (blocks, related, parent-child). |
| `bd show ` | View task details and audit trail. |
## 🔗 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](#-git-free-usage) below.
**Contributor vs Maintainer:** When working on open-source projects:
* **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.
* **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.
## 📦 Installation
* **npm:** `npm install -g @beads/bd`
* **Homebrew:** `brew install beads`
* **Go:** `go install github.com/steveyegge/beads/cmd/bd@latest`
**Requirements:** Linux, FreeBSD, macOS, or Windows.
### Building from Source
Building from source requires **CGO** (a C compiler). The embedded Dolt engine
links against C libraries.
```bash
# Install dependencies
# macOS: xcode-select --install && brew install icu4c
# Ubuntu/Debian: sudo apt install build-essential
# Fedora: sudo dnf install gcc gcc-c++
# Build and install
make install
```
`CGO_ENABLED=1` is set automatically by the Makefile. On macOS, Homebrew's
`icu4c` paths are detected automatically. On Windows, MinGW or MSYS2 provides
the C compiler (ICU is not required — a pure-Go fallback is used).
### 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/ANTIVIRUS.md](docs/ANTIVIRUS.md) for Windows AV false-positive guidance and verification workflow.
## 💾 Storage Modes
Beads uses [Dolt](https://github.com/dolthub/dolt) as its database. Two modes
are available:
### Embedded Mode (default)
```bash
bd init
```
Dolt runs in-process — no external server needed. Data lives in
`.beads/embeddeddolt/`. Single-writer only (file locking enforced).
This is the recommended mode for most users.
### Server Mode
```bash
bd init --server
```
Connects to an external `dolt sql-server`. Data lives in `.beads/dolt/`.
Supports multiple concurrent writers. Configure the connection with flags
or environment variables:
| Flag | Env Var | Default |
|------|---------|---------|
| `--server-host` | `BEADS_DOLT_SERVER_HOST` | `127.0.0.1` |
| `--server-port` | `BEADS_DOLT_SERVER_PORT` | `3307` |
| `--server-user` | `BEADS_DOLT_SERVER_USER` | `root` |
| | `BEADS_DOLT_PASSWORD` | (none) |
### Backup & Migration
Back up your database and migrate between modes using `bd backup`:
```bash
# Set up a backup destination and push
bd backup init /path/to/backup
bd backup sync
# Restore into a new project (any mode)
bd init # or bd init --server
bd backup restore --force /path/to/backup
```
See [docs/DOLT.md](docs/DOLT.md#migrating-between-backends) for full
migration instructions.
## 🌐 Community Tools
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.
## 🚀 Git-Free Usage
Beads works without git. The Dolt database is the storage backend — git
integration (hooks, repo discovery, identity) is optional.
```bash
# 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_DIR` at a specific subdirectory
- **CI/CD** — isolated task tracking without repo-level side effects
- **Evaluation/testing** — ephemeral databases in `/tmp`
For daemon mode without git, use `bd daemon start --local`
(see [PR #433](https://github.com/steveyegge/beads/pull/433)).
## 📝 Documentation
* [Installing](docs/INSTALLING.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot Setup](docs/COPILOT_INTEGRATION.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/PROTECTED_BRANCHES.md) | [Troubleshooting](docs/TROUBLESHOOTING.md) | [FAQ](docs/FAQ.md)
* [](https://deepwiki.com/steveyegge/beads)