nixpkgs/docs/packages/beads.md

beads

Lightweight memory system for AI coding agents with graph-based issue tracking.

Description

beads is a command-line tool designed to provide persistent memory and issue tracking for AI coding agents. It features a graph-based system for managing issues, dependencies, and discovered work across development sessions.

Features

• 🧠 Persistent Memory: Store and retrieve context across AI sessions
• 📊 Graph-Based Issue Tracking: Manage issues with dependency relationships
• 🔄 Discovered Work: Track work discovered during development
• 🎯 Multi-Session Continuity: Resume work from previous sessions
• 📝 Git Integration: Seamless integration with git workflows
• 🐚 Shell Completions: Bash, Fish, and Zsh completions included

Installation

Via Overlay

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    beads
  ];
}

Direct Reference

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.m3ta-nixpkgs.packages.${pkgs.system}.beads
  ];
}

Run Directly

nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#beads

Usage

Basic Commands

# Show available issues ready to work on
bd ready

# Create a new issue
bd create "Fix authentication bug" --type bug --priority 2

# Show issue details
bd show beads-123

# Update issue status
bd update beads-123 --status in_progress

# Close completed issues
bd close beads-123

# Sync with git remote
bd sync

Issue Types

• task: General tasks
• bug: Bug fixes
• feature: New features
• epic: Large-scale initiatives

Priority Levels

• 0 (P0): Critical
• 1 (P1): High
• 2 (P2): Medium
• 3 (P3): Low
• 4 (P4): Backlog

Dependency Management

# Add dependency (beads-123 depends on beads-456)
bd dep add beads-123 beads-456

# Show blocked issues
bd blocked

# Show what blocks an issue
bd show beads-123 --blocked-by

Advanced Usage

Finding Work

# Show ready tasks (no blockers)
bd ready

# Show all open issues
bd list --status open

# Show in-progress work
bd list --status in_progress

Assignment

# Assign issue to yourself
bd update beads-123 --assignee username

# Create assigned issue
bd create "Review PR" --assignee reviewer

Bulk Operations

# Close multiple issues at once
bd close beads-123 beads-456 beads-789

# Close with reason
bd close beads-123 --reason "Completed in v1.2.0"

Hooks

# Install git hooks for automatic sync
bd hooks install

# Remove hooks
bd hooks uninstall

Configuration

Environment Variables

• BEADS_DATA_DIR: Custom directory for beads data (default: .beads/)
• BEADS_CONFIG: Custom configuration file path
• BEADS_EDITOR: Default editor for editing issues

Git Integration

beads integrates with git for version-controlled issue tracking:

• Automatic sync before commits (via hooks)
• Issue references in commit messages
• Branch name tracking
• Git-aware issue states

Workflow Integration

Typical Development Workflow

1. Start session: bd prime or check bd ready
2. Claim work: bd update beads-123 --status in_progress
3. Work on task: Implement changes
4. Discover new work: bd create "Discovered subtask" as needed
5. Complete task: bd close beads-123
6. Sync: bd sync (automatic via hooks)

Team Collaboration

# Create issue and assign
bd create "Implement feature X" --assignee dev1

# Review assigned work
bd list --assignee yourname

# Close with review notes
bd close beads-123 --reason "Reviewed and approved"

Shell Completions

beads provides shell completions for bash, fish, and zsh:

# Bash completions are auto-loaded
source <(bd completion bash)

# Fish completions
bd completion fish | source

# Zsh completions
bd completion zsh > ~/.zfunc/_bd

Build Information

• Version: 0.47.1
• Language: Go
• License: MIT
• Source: GitHub

Platform Support

• Linux
• macOS

Notes

• Tests are disabled in the Nix package due to git worktree operations that fail in the sandbox
• Security tests on Darwin are skipped due to /etc/passwd unavailability in sandbox
• Shell completions are installed for platforms that can execute the build target

Related

• Adding Packages - How to add new packages
• Quick Start - Getting started guide