da921e1829
Implements @beads/bd npm package for easy installation in Node.js environments, especially Claude Code for Web. Features: - Automatic platform-specific binary download during postinstall - CLI wrapper that invokes native bd binary - Full feature parity with standalone bd - Works with SessionStart hooks for auto-installation Package structure: - bin/bd.js: Node.js CLI wrapper - scripts/postinstall.js: Downloads correct binary from GitHub releases - scripts/test.js: Verification tests - Comprehensive documentation (6 guides) Published to npm: https://www.npmjs.com/package/@beads/bd Benefits vs WASM: - Full SQLite support (no custom VFS) - Better performance (native vs WASM) - Simpler implementation and maintenance - All commands work identically Closes bd-febc, bd-be7a, bd-e2e6, bd-f282, bd-87a0, bd-b54c 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
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/QUICKSTART.md)
|
|
- [Installation Guide](https://github.com/steveyegge/beads/blob/main/INSTALLING.md)
|
|
- [FAQ](https://github.com/steveyegge/beads/blob/main/FAQ.md)
|
|
- [Troubleshooting](https://github.com/steveyegge/beads/blob/main/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)
|