520e1007f1
* docs: fix Go version typo in CONTRIBUTING.md (1.25 -> 1.24) * docs: update Go version requirement to 1.24+ across docs * docs: fix broken links to docs/ in npm-package/README.md * docs: fix QUICKSTART.md path reference in AGENTS.md
125 lines
3.4 KiB
Markdown
125 lines
3.4 KiB
Markdown
# @beads/bd - Beads Issue Tracker
|
|
|
|
[](https://www.npmjs.com/package/@beads/bd)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
**Give your coding agent a memory upgrade**
|
|
|
|
Beads is a lightweight memory system for coding agents, using a graph-based issue tracker. This npm package provides easy installation of the native bd binary for Node.js environments, including Claude Code for Web.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install -g @beads/bd
|
|
```
|
|
|
|
Or as a project dependency:
|
|
|
|
```bash
|
|
npm install --save-dev @beads/bd
|
|
```
|
|
|
|
## What is Beads?
|
|
|
|
Beads is an issue tracker designed specifically for AI coding agents. It provides:
|
|
|
|
- ✨ **Zero setup** - `bd init` creates project-local database
|
|
- 🔗 **Dependency tracking** - Four dependency types (blocks, related, parent-child, discovered-from)
|
|
- 📋 **Ready work detection** - Automatically finds issues with no open blockers
|
|
- 🤖 **Agent-friendly** - `--json` flags for programmatic integration
|
|
- 📦 **Git-versioned** - JSONL records stored in git, synced across machines
|
|
- 🌍 **Distributed by design** - Share one logical database via git
|
|
|
|
## Quick Start
|
|
|
|
After installation, initialize beads in your project:
|
|
|
|
```bash
|
|
bd init
|
|
```
|
|
|
|
Then tell your AI agent to use bd for task tracking instead of markdown:
|
|
|
|
```bash
|
|
echo "Use 'bd' commands for issue tracking instead of markdown TODOs" >> AGENTS.md
|
|
```
|
|
|
|
Your agent will automatically:
|
|
- Create and track issues during work
|
|
- Manage dependencies between tasks
|
|
- Find ready work with `bd ready`
|
|
- Keep long-term context across sessions
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Find ready work
|
|
bd ready --json
|
|
|
|
# Create an issue
|
|
bd create "Fix bug" -t bug -p 1
|
|
|
|
# Show issue details
|
|
bd show bd-a1b2
|
|
|
|
# List all issues
|
|
bd list --json
|
|
|
|
# Update status
|
|
bd update bd-a1b2 --status in_progress
|
|
|
|
# Add dependency
|
|
bd dep add bd-f14c bd-a1b2
|
|
|
|
# Close issue
|
|
bd close bd-a1b2 --reason "Fixed"
|
|
```
|
|
|
|
## Claude Code for Web Integration
|
|
|
|
To auto-install bd in Claude Code for Web sessions, add to your SessionStart hook:
|
|
|
|
```bash
|
|
# .claude/hooks/session-start.sh
|
|
npm install -g @beads/bd
|
|
bd init --quiet
|
|
```
|
|
|
|
This ensures bd is available in every new session without manual setup.
|
|
|
|
## Platform Support
|
|
|
|
This package downloads the appropriate native binary for your platform:
|
|
|
|
- **macOS**: darwin-amd64, darwin-arm64
|
|
- **Linux**: linux-amd64, linux-arm64
|
|
- **Windows**: windows-amd64
|
|
|
|
## Full Documentation
|
|
|
|
For complete documentation, see the [beads GitHub repository](https://github.com/steveyegge/beads):
|
|
|
|
- [Complete README](https://github.com/steveyegge/beads#readme)
|
|
- [Quick Start Guide](https://github.com/steveyegge/beads/blob/main/docs/QUICKSTART.md)
|
|
- [Installation Guide](https://github.com/steveyegge/beads/blob/main/docs/INSTALLING.md)
|
|
- [FAQ](https://github.com/steveyegge/beads/blob/main/docs/FAQ.md)
|
|
- [Troubleshooting](https://github.com/steveyegge/beads/blob/main/docs/TROUBLESHOOTING.md)
|
|
|
|
## Why npm Package vs WASM?
|
|
|
|
This npm package wraps the native bd binary rather than using WebAssembly because:
|
|
|
|
- ✅ Full SQLite support (no custom VFS needed)
|
|
- ✅ All features work identically to native bd
|
|
- ✅ Better performance (native vs WASM overhead)
|
|
- ✅ Simpler maintenance
|
|
|
|
## License
|
|
|
|
MIT - See [LICENSE](LICENSE) for details.
|
|
|
|
## Support
|
|
|
|
- [GitHub Issues](https://github.com/steveyegge/beads/issues)
|
|
- [Documentation](https://github.com/steveyegge/beads)
|