beads/npm-package
Julian Knutsen f45b249ce6
release: make release/1.3.0 tag-ready — revert #6281, stamp 1.3.0, date the changelog (#6564)
* revert: drop the journaled ownership handoff API from the release branch (#6281)

This reverts commit 74e25cba15, restoring the
release branch to the exact tree validated as v1.3.0-rc.2.

#6281 landed one commit past rc.2, so no release candidate ever exercised it.
Nothing imports `internal/ownershiphandoff` and no command registers it — the
package is unreachable from any `bd` entry point, so removing it cannot change
shipped behavior. It is superseded by a redesign that builds a fresh
`internal/ownershiphandoffv2` and deletes this package outright, and its
Hooks/Execute shape is the scaffolding of an architecture the owner rejected.

The commit never landed on main, so this is release-branch-only and nothing is
lost anywhere else. Reverting also returns
engdocs/design/ownership-handoff-contract.md to its prospective voice, which is
accurate again now that the implementation it described is gone.

* release: stamp 1.3.0 and date the changelog entry to the release day

`verify-version-consistency` in .github/workflows/release.yml compares the tag
name against the `Version = ` constant in cmd/bd/version.go and fails the job on
any mismatch, so a v1.3.0 tag against the 1.3.0-rc.2 stamp would abort the
pipeline before it built anything.

Bumped with ./scripts/update-versions.sh 1.3.0, which carries the stamp into all
seven version files, the two uv.lock entries, the ten githook managed-section
markers and the winres strings. The winres numeric file_version/product_version
and the manifest assemblyIdentity never carried the prerelease suffix and are
unchanged. ./scripts/check-versions.sh passes 24/24.

CHANGELOG.md's [1.3.0] heading carried 2026-08-28, the branch-cut date, which
predated both of its own release candidates. It and the matching
cmd/bd/info.go versionChanges entry now read 2026-09-15, the release date. The
section's reviewed content is untouched and [Unreleased] remains empty.

Dating the entry truthfully also forced its position. versionChanges is
reverse-chronological and getVersionsSince treats array index as recency, so
TestGetVersionsSinceOrder failed: the 1.3.0 entry still sat below its own rc.1
and rc.2, where the branch-cut date had made it look like the oldest of the
three. The entry moves to the head of the array, byte for byte unchanged. That
restores the strict date ordering and fixes the behavior it was hiding — an
rc.2 tester upgrading to the release now gets the [1.3.0] digest from
`bd upgrade review` instead of being told there is nothing new.
2026-09-15 12:13:59 -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 release: make release/1.3.0 tag-ready — revert #6281, stamp 1.3.0, date the changelog (#6564) 2026-09-15 12:13:59 -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