[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-4766":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":25,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":30,"readmeContent":31,"aiSummary":32,"trendingCount":16,"starSnapshotCount":16,"syncStatus":33,"lastSyncTime":34,"discoverSource":35},4766,"beads","gastownhall\u002Fbeads","gastownhall","Beads - A memory upgrade for your coding agent","",null,"Go",24466,1634,90,242,0,13,122,928,76,44.64,"MIT License",false,"main",true,[27,28,29],"agents","claude-code","coding","2026-06-12 02:01:03","# bd - Beads\n\n**Distributed graph issue tracker for AI agents, powered by [Dolt](https:\u002F\u002Fgithub.com\u002Fdolthub\u002Fdolt).**\n\n**Platforms:** macOS, Linux, Windows, FreeBSD\n\n[![License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fgastownhall\u002Fbeads)](LICENSE)\n[![Go Report Card](https:\u002F\u002Fgoreportcard.com\u002Fbadge\u002Fgithub.com\u002Fsteveyegge\u002Fbeads)](https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002Fsteveyegge\u002Fbeads)\n[![Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fgastownhall\u002Fbeads)](https:\u002F\u002Fgithub.com\u002Fgastownhall\u002Fbeads\u002Freleases)\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@beads\u002Fbd)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@beads\u002Fbd)\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fbeads-mcp)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fbeads-mcp\u002F)\n\n**Docs:** https:\u002F\u002Fgastownhall.github.io\u002Fbeads\u002F\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:\u002F\u002Fraw.githubusercontent.com\u002Fgastownhall\u002Fbeads\u002Fmain\u002Fscripts\u002Finstall.sh | bash\n\n# Initialize in YOUR project\ncd your-project\nbd init\n\n# Optional: install richer instructions for your agent\nbd setup codex    # Codex CLI - creates\u002Fupdates AGENTS.md\nbd setup claude   # Claude Code - installs hooks\u002Fsettings\nbd setup factory  # Factory.ai Droid - creates\u002Fupdates 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`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\u002FSETUP.md).\n\nManual copy-paste is only for unsupported agents, existing projects where you cannot rerun `bd init`\u002F`bd setup`, or custom instruction files. In those cases, run `bd onboard` and paste the printed snippet into the file your agent reads.\n\nIf your agent is not covered by `bd setup`, add this minimal `AGENTS.md` section:\n\n```markdown\nThis project uses bd (beads) for issue tracking.\n\n- Run `bd prime` for workflow context and command guidance.\n- Use `bd ready`, `bd show \u003Cid>`, `bd update \u003Cid> --claim`, and `bd close \u003Cid>`.\n- Use `bd remember \"insight\"` for persistent project memory; do not create MEMORY.md files.\n- Do not use markdown TODO lists for task tracking.\n```\n\n## 🛠 Features\n\n* **[Dolt](https:\u002F\u002Fgithub.com\u002Fdolthub\u002Fdolt)-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\u002Fmulti-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> --claim` | Atomically claim a task (sets assignee + in_progress). |\n| `bd dep add \u003Cchild> \u003Cparent>` | Link tasks (blocks, related, parent-child). |\n| `bd show \u003Cid>` | View task details and audit trail. |\n| `bd prime` | Print agent workflow context and persistent memories. |\n| `bd remember \"insight\"` | Store project memory that `bd prime` injects later. |\n\n## 🔗 Hierarchy & 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., `~\u002F.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```bash\nbrew install beads           # macOS \u002F Linux (recommended)\nnpm install -g @beads\u002Fbd     # Node.js users\n```\n\n**Other methods:** [install script](docs\u002FINSTALLING.md#quick-install-script-all-platforms) | [go install](docs\u002FINSTALLING.md#a-note-on-go-install-capability) | [from source](docs\u002FINSTALLING.md#build-dependencies-contributors-only) | [Windows](docs\u002FINSTALLING.md#windows-11) | [Arch AUR](docs\u002FINSTALLING.md#linux)\n\n**Requirements:** macOS, Linux, Windows, or FreeBSD. See [docs\u002FINSTALLING.md](docs\u002FINSTALLING.md) for complete installation guide.\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\u002Finstall.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\u002FANTIVIRUS.md](docs\u002FANTIVIRUS.md) for Windows AV false-positive guidance and verification workflow.\n\n## 💾 Storage Modes\n\nBeads uses [Dolt](https:\u002F\u002Fgithub.com\u002Fdolthub\u002Fdolt) 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\u002Fembeddeddolt\u002F`. 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\u002Fdolt\u002F`.\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-socket` | `BEADS_DOLT_SERVER_SOCKET` | (none; uses TCP) |\n| `--server-user` | `BEADS_DOLT_SERVER_USER` | `root` |\n| | `BEADS_DOLT_PASSWORD` | (none) |\n| | `BEADS_DOLT_CLI_DIR` | local Dolt database path for CLI push\u002Fpull |\n\n**Unix domain sockets:** Use `--server-socket` to connect via a Unix socket\ninstead of TCP. This avoids port conflicts between concurrent projects and\nis useful in sandboxed environments (e.g., Claude Code) where file-level\naccess control is simpler than network allowlists. The Dolt server must be\nstarted with `dolt sql-server --socket \u003Cpath>`. Auto-start is not supported\nin socket mode.\n\nWhen `BEADS_DOLT_SERVER_MODE=1` points at a Dolt server managed outside\nBeads, set `BEADS_DOLT_CLI_DIR` if `bd dolt push` \u002F `bd dolt pull` must use\nthe local `dolt` CLI (for example git-protocol remotes or credentials that\nonly exist in the current shell). Use the actual Dolt database directory, not\nthe server root.\n\n### Backup & 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 \u002Fpath\u002Fto\u002Fbackup\nbd backup sync\n\n# Restore into a new project (any mode)\nbd init           # or bd init --server\nbd backup restore --force \u002Fpath\u002Fto\u002Fbackup\n```\n\nSee [docs\u002FDOLT.md](docs\u002FDOLT.md#migrating-between-backends) for full\nmigration instructions.\n\n## 🌐 Community Tools\n\nSee [docs\u002FCOMMUNITY_TOOLS.md](docs\u002FCOMMUNITY_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=\u002Fpath\u002Fto\u002Fyour\u002Fproject\u002F.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\u002F` 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\u002F` directory needed\n- **Monorepos** — point `BEADS_DIR` at a specific subdirectory\n- **CI\u002FCD** — isolated task tracking without repo-level side effects\n- **Evaluation\u002Ftesting** — ephemeral databases in `\u002Ftmp`\n\nFor daemon mode without git, use `bd daemon start --local`\n(see [PR #433](https:\u002F\u002Fgithub.com\u002Fgastownhall\u002Fbeads\u002Fpull\u002F433)).\n\n## 📝 Documentation\n\n* [Documentation site](https:\u002F\u002Fgastownhall.github.io\u002Fbeads\u002F) (versioned) | [Installing](docs\u002FINSTALLING.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot Setup](docs\u002FCOPILOT_INTEGRATION.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs\u002FPROTECTED_BRANCHES.md) | [Troubleshooting](docs\u002FTROUBLESHOOTING.md) | [FAQ](docs\u002FFAQ.md)\n* [![Ask DeepWiki](https:\u002F\u002Fdeepwiki.com\u002Fbadge.svg)](https:\u002F\u002Fdeepwiki.com\u002Fgastownhall\u002Fbeads)\n","Beads 是一个为编码代理提供持久化、结构化内存的工具，旨在通过依赖感知图替换混乱的Markdown计划，使代理能够处理长期任务而不丢失上下文。它基于Dolt构建，利用版本控制的SQL数据库支持单元级合并、原生分支和内置同步功能。此外，Beads针对AI代理进行了优化，提供了JSON输出、依赖跟踪和自动准备任务检测等功能，确保在多代理环境中不会发生冲突。适用于需要长期记忆支持以执行复杂或长时间运行任务的开发场景中使用。",2,"2026-06-11 03:00:22","top_language"]