beads/npm-package

@beads/bd - Beads Issue Tracker

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

npm install -g @beads/bd

Or as a project dependency:

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:

bd init

Then tell your AI agent to use bd for task tracking instead of markdown:

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

# 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:

# .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:

• Complete README
• Quick Start Guide
• Installation Guide
• FAQ
• Troubleshooting

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 for details.

Support

• GitHub Issues
• Documentation