beads/npm-package
Steve Yegge 634cbbc4bc chore(release): bump version to 1.2.1
Re-cut of the burned v1.2.0: that tag failed pre-publish in goreleaser on
the freebsd cross-compile break (no artifacts were published), and a
burned tag is never reused (v1.1.1 precedent), so the same content ships
as 1.2.1 with the fix (#5661) included. The [1.2.0] changelog section is
renamed to [1.2.1] with a note; versionChanges rides along. Also the
first bump to regenerate the tracked .githooks markers via the previous
commit's update-versions.sh fix, clearing the main-red from fa3d8cc5c.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-11 14:06:37 -07:00
..
bin Add npm package for bd with native binaries (bd-febc) 2025-11-03 11:41:18 -08:00
scripts docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
test Add PR CI wrapper command surface (#4211) 2026-05-29 18:52:53 -07:00
.npmignore Add npm package for bd with native binaries (bd-febc) 2025-11-03 11:41:18 -08:00
CLAUDE_CODE_WEB.md Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
INTEGRATION_GUIDE.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
LAUNCH.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
LICENSE Add npm package for bd with native binaries (bd-febc) 2025-11-03 11:41:18 -08:00
package.json chore(release): bump version to 1.2.1 2026-08-11 14:06:37 -07:00
PUBLISHING.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
README.md docs: redirect legacy GitHub Pages site to Mintlify (#4759) 2026-07-13 14:19:13 -07:00
SUMMARY.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
TESTING.md Add integration tests and release documentation for npm package 2025-11-03 11:54:37 -08:00

@beads/bd - Beads Issue Tracker

npm version License: 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

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
  • 📦 Version-controlled - Dolt database with full history and branching
  • 🌍 Distributed by design - Share one logical database via Dolt remotes

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

# Start work
bd update bd-a1b2 --claim

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

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