* docs: clarify export versus database backup * docs: remove remaining JSONL backup wording
213 lines
9.7 KiB
Markdown
213 lines
9.7 KiB
Markdown
# 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/gastownhall/beads/releases)
|
|
[](https://www.npmjs.com/package/@beads/bd)
|
|
[](https://pypi.org/project/beads-mcp/)
|
|
|
|
**Docs:** https://gastownhall.github.io/beads/
|
|
|
|
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/gastownhall/beads/main/scripts/install.sh | bash
|
|
|
|
# Initialize in YOUR project
|
|
cd your-project
|
|
bd init
|
|
|
|
# Optional: install richer instructions for your agent
|
|
bd setup codex # Codex CLI - creates/updates AGENTS.md
|
|
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. It skips agent files only when you pass `--skip-agents` or `--stealth`, or when you configure a custom agent file. 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/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:
|
|
|
|
```markdown
|
|
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 persistent project memory; do not create MEMORY.md files.
|
|
- Do not use markdown TODO lists for task tracking.
|
|
```
|
|
|
|
## 🛠 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 <id> --claim` | Atomically claim a task (sets assignee + in_progress). |
|
|
| `bd dep add <child> <parent>` | Link tasks (blocks, related, parent-child). |
|
|
| `bd show <id>` | View task details and audit trail. |
|
|
| `bd prime` | Print agent workflow context and persistent memories. |
|
|
| `bd remember "insight"` | Store project memory that `bd prime` injects later. |
|
|
|
|
## 🔗 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
|
|
|
|
```bash
|
|
brew install beads # macOS / Linux (recommended)
|
|
npm install -g @beads/bd # Node.js users
|
|
```
|
|
|
|
**Other methods:** [install script](docs/INSTALLING.md#quick-install-script-all-platforms) | [go install](docs/INSTALLING.md#a-note-on-go-install-capability) | [from source](docs/INSTALLING.md#build-dependencies-contributors-only) | [Windows](docs/INSTALLING.md#windows-11) | [Arch AUR](docs/INSTALLING.md#linux)
|
|
|
|
**Requirements:** macOS, Linux, Windows, or FreeBSD. See [docs/INSTALLING.md](docs/INSTALLING.md) for complete installation guide.
|
|
|
|
### 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.
|
|
|
|
When the git repo has an `origin` remote, `bd init` configures a Dolt remote
|
|
named `origin` automatically. Cross-machine sync uses `bd dolt push` and
|
|
`bd dolt pull` against `refs/dolt/data`; `.beads/issues.jsonl` is an export
|
|
for viewers and interchange, not the source of truth or a full database
|
|
backup.
|
|
|
|
### 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-socket` | `BEADS_DOLT_SERVER_SOCKET` | (none; uses TCP) |
|
|
| `--server-user` | `BEADS_DOLT_SERVER_USER` | `root` |
|
|
| | `BEADS_DOLT_PASSWORD` | (none) |
|
|
|
|
**Unix domain sockets:** Use `--server-socket` to connect via a Unix socket
|
|
instead of TCP. This avoids port conflicts between concurrent projects and
|
|
is useful in sandboxed environments (e.g., Claude Code) where file-level
|
|
access control is simpler than network allowlists. The Dolt server must be
|
|
started with `dolt sql-server --socket <path>`. Auto-start is not supported
|
|
in socket mode.
|
|
|
|
### 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.
|
|
|
|
`bd export` and `.beads/issues.jsonl` are issue-table exports. They are useful
|
|
for review, migration, and interoperability, but they do not capture Dolt
|
|
branches, commit history, working-set state, or non-issue tables. Use
|
|
`bd backup` or a manual Dolt backup when you need a restorable database backup.
|
|
|
|
## 🌐 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/gastownhall/beads/pull/433)).
|
|
|
|
## 📝 Documentation
|
|
|
|
* [Documentation site](https://gastownhall.github.io/beads/) (versioned) | [Installing](docs/INSTALLING.md) | [Sync Concepts](docs/SYNC_CONCEPTS.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot CLI Setup](docs/COPILOT_CLI_INTEGRATION.md) | [Copilot VS Code MCP](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/gastownhall/beads)
|