8619d08db9
Creates an ARTICLES.md with both official and community articles and tutorials about Beads. This will help others get find resources and get started.
75 lines
3.4 KiB
Markdown
75 lines
3.4 KiB
Markdown
# bd - Beads
|
|
|
|
**Distributed, git-backed graph issue tracker for AI agents.**
|
|
|
|
[](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 (macOS/Linux/FreeBSD)
|
|
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
|
|
|
|
# Initialize (Humans run this once)
|
|
bd init
|
|
|
|
# Tell your agent
|
|
echo "Use 'bd' for task tracking" >> AGENTS.md
|
|
|
|
```
|
|
|
|
## 🛠 Features
|
|
|
|
* **Git as Database:** Issues stored as JSONL in `.beads/`. Versioned, branched, and merged like code.
|
|
* **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.
|
|
* **Invisible Infrastructure:** SQLite local cache for speed; background daemon for auto-sync.
|
|
* **Compaction:** Semantic "memory decay" summarizes old closed tasks to save context window.
|
|
|
|
## 📖 Essential Commands
|
|
|
|
| Command | Action |
|
|
| --- | --- |
|
|
| `bd ready` | List tasks with no open blockers. |
|
|
| `bd create "Title" -p 0` | Create a P0 task. |
|
|
| `bd dep add <child> <parent>` | Link tasks (blocks, related, parent-child). |
|
|
| `bd show <id>` | 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.
|
|
|
|
**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 steveyegge/beads/bd`
|
|
* **Go:** `go install github.com/steveyegge/beads/cmd/bd@latest`
|
|
|
|
**Requirements:** Linux, FreeBSD, macOS, or Windows.
|
|
|
|
## 🌐 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.
|
|
|
|
## 📝 Documentation
|
|
|
|
* [Installing](docs/INSTALLING.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/PROTECTED_BRANCHES.md) | [Troubleshooting](docs/TROUBLESHOOTING.md) | [FAQ](docs/FAQ.md)
|
|
* [](https://deepwiki.com/steveyegge/beads)
|