{"id":47653496,"url":"https://github.com/gastownhall/beads","last_synced_at":"2026-04-05T19:01:00.149Z","repository":{"id":318735393,"uuid":"1074561042","full_name":"gastownhall/beads","owner":"gastownhall","description":"Beads - A memory upgrade for your coding agent","archived":false,"fork":false,"pushed_at":"2026-03-31T21:32:59.000Z","size":6878799,"stargazers_count":20040,"open_issues_count":48,"forks_count":1326,"subscribers_count":77,"default_branch":"main","last_synced_at":"2026-03-31T21:35:59.039Z","etag":null,"topics":["agents","claude-code","coding"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gastownhall.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-12T03:09:46.000Z","updated_at":"2026-03-31T21:33:08.000Z","dependencies_parsed_at":"2025-10-28T19:18:35.460Z","dependency_job_id":"fff6be7b-43c1-40da-94f3-82cb4f358090","html_url":"https://github.com/gastownhall/beads","commit_stats":null,"previous_names":["steveyegge/beads","gastownhall/beads"],"tags_count":112,"template":false,"template_full_name":null,"purl":"pkg:github/gastownhall/beads","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastownhall%2Fbeads","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastownhall%2Fbeads/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastownhall%2Fbeads/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastownhall%2Fbeads/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gastownhall","download_url":"https://codeload.github.com/gastownhall/beads/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gastownhall%2Fbeads/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31319726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T23:57:25.032Z","status":"ssl_error","status_checked_at":"2026-04-02T23:57:06.281Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","claude-code","coding"],"created_at":"2026-04-02T08:00:43.346Z","updated_at":"2026-04-03T00:01:06.198Z","avatar_url":"https://github.com/gastownhall.png","language":"Go","readme":"# bd - Beads\n\n**Distributed graph issue tracker for AI agents, powered by [Dolt](https://github.com/dolthub/dolt).**\n\n**Platforms:** macOS, Linux, Windows, FreeBSD\n\n[![License](https://img.shields.io/github/license/steveyegge/beads)](LICENSE)\n[![Go Report Card](https://goreportcard.com/badge/github.com/steveyegge/beads)](https://goreportcard.com/report/github.com/steveyegge/beads)\n[![Release](https://img.shields.io/github/v/release/steveyegge/beads)](https://github.com/steveyegge/beads/releases)\n[![npm version](https://img.shields.io/npm/v/@beads/bd)](https://www.npmjs.com/package/@beads/bd)\n[![PyPI](https://img.shields.io/pypi/v/beads-mcp)](https://pypi.org/project/beads-mcp/)\n\nBeads 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.\n\n## ⚡ Quick Start\n\n```bash\n# Install beads CLI (system-wide - don't clone this repo into your project)\ncurl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash\n\n# Initialize in YOUR project\ncd your-project\nbd init\n\n# Tell your agent\necho \"Use 'bd' for task tracking\" \u003e\u003e AGENTS.md\n```\n\n**Note:** Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.\n\n## 🛠 Features\n\n* **[Dolt](https://github.com/dolthub/dolt)-Powered:** Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.\n* **Agent-Optimized:** JSON output, dependency tracking, and auto-ready task detection.\n* **Zero Conflict:** Hash-based IDs (`bd-a1b2`) prevent merge collisions in multi-agent/multi-branch workflows.\n* **Compaction:** Semantic \"memory decay\" summarizes old closed tasks to save context window.\n* **Messaging:** Message issue type with threading (`--thread`), ephemeral lifecycle, and mail delegation.\n* **Graph Links:** `relates_to`, `duplicates`, `supersedes`, and `replies_to` for knowledge graphs.\n\n## 📖 Essential Commands\n\n| Command | Action |\n| --- | --- |\n| `bd ready` | List tasks with no open blockers. |\n| `bd create \"Title\" -p 0` | Create a P0 task. |\n| `bd update \u003cid\u003e --claim` | Atomically claim a task (sets assignee + in_progress). |\n| `bd dep add \u003cchild\u003e \u003cparent\u003e` | Link tasks (blocks, related, parent-child). |\n| `bd show \u003cid\u003e` | View task details and audit trail. |\n\n## 🔗 Hierarchy \u0026 Workflow\n\nBeads supports hierarchical IDs for epics:\n\n* `bd-a3f8` (Epic)\n* `bd-a3f8.1` (Task)\n* `bd-a3f8.1.1` (Sub-task)\n\n**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.\n\n**Contributor vs Maintainer:** When working on open-source projects:\n\n* **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.\n* **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.\n\n## 📦 Installation\n\n* **npm:** `npm install -g @beads/bd`\n* **Homebrew:** `brew install beads`\n* **Go:** `go install github.com/steveyegge/beads/cmd/bd@latest`\n\n**Requirements:** Linux, FreeBSD, macOS, or Windows.\n\n### Building from Source\n\nBuilding from source requires **CGO** (a C compiler). The embedded Dolt engine\nlinks against C libraries.\n\n```bash\n# Install dependencies\n# macOS: xcode-select --install \u0026\u0026 brew install icu4c\n# Ubuntu/Debian: sudo apt install build-essential\n# Fedora: sudo dnf install gcc gcc-c++\n\n# Build and install\nmake install\n```\n\n`CGO_ENABLED=1` is set automatically by the Makefile. On macOS, Homebrew's\n`icu4c` paths are detected automatically. On Windows, MinGW or MSYS2 provides\nthe C compiler (ICU is not required — a pure-Go fallback is used).\n\n### Security And Verification\n\nBefore trusting any downloaded binary, verify its checksum against the release `checksums.txt`.\n\nThe install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.\n\nOn 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`.\n\nSee [docs/ANTIVIRUS.md](docs/ANTIVIRUS.md) for Windows AV false-positive guidance and verification workflow.\n\n## 💾 Storage Modes\n\nBeads uses [Dolt](https://github.com/dolthub/dolt) as its database. Two modes\nare available:\n\n### Embedded Mode (default)\n\n```bash\nbd init\n```\n\nDolt runs in-process — no external server needed. Data lives in\n`.beads/embeddeddolt/`. Single-writer only (file locking enforced).\nThis is the recommended mode for most users.\n\n### Server Mode\n\n```bash\nbd init --server\n```\n\nConnects to an external `dolt sql-server`. Data lives in `.beads/dolt/`.\nSupports multiple concurrent writers. Configure the connection with flags\nor environment variables:\n\n| Flag | Env Var | Default |\n|------|---------|---------|\n| `--server-host` | `BEADS_DOLT_SERVER_HOST` | `127.0.0.1` |\n| `--server-port` | `BEADS_DOLT_SERVER_PORT` | `3307` |\n| `--server-user` | `BEADS_DOLT_SERVER_USER` | `root` |\n| | `BEADS_DOLT_PASSWORD` | (none) |\n\n### Backup \u0026 Migration\n\nBack up your database and migrate between modes using `bd backup`:\n\n```bash\n# Set up a backup destination and push\nbd backup init /path/to/backup\nbd backup sync\n\n# Restore into a new project (any mode)\nbd init           # or bd init --server\nbd backup restore --force /path/to/backup\n```\n\nSee [docs/DOLT.md](docs/DOLT.md#migrating-between-backends) for full\nmigration instructions.\n\n## 🌐 Community Tools\n\nSee [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.\n\n## 🚀 Git-Free Usage\n\nBeads works without git. The Dolt database is the storage backend — git\nintegration (hooks, repo discovery, identity) is optional.\n\n```bash\n# Initialize without git\nexport BEADS_DIR=/path/to/your/project/.beads\nbd init --quiet --stealth\n\n# All core commands work with zero git calls\nbd create \"Fix auth bug\" -p 1 -t bug\nbd ready --json\nbd update bd-a1b2 --claim\nbd prime\nbd close bd-a1b2 \"Fixed\"\n```\n\n`BEADS_DIR` tells bd where to put the `.beads/` database directory,\nbypassing git repo discovery. `--stealth` sets `no-git-ops: true` in\nconfig, disabling all git hook installation and git operations.\n\nThis is useful for:\n- **Non-git VCS** (Sapling, Jujutsu, Piper) — no `.git/` directory needed\n- **Monorepos** — point `BEADS_DIR` at a specific subdirectory\n- **CI/CD** — isolated task tracking without repo-level side effects\n- **Evaluation/testing** — ephemeral databases in `/tmp`\n\nFor daemon mode without git, use `bd daemon start --local`\n(see [PR #433](https://github.com/steveyegge/beads/pull/433)).\n\n## 📝 Documentation\n\n* [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)\n* [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/steveyegge/beads)\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgastownhall%2Fbeads","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgastownhall%2Fbeads","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgastownhall%2Fbeads/lists"}