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

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

### Direct Reference

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

### Run Directly

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

## Usage

### Basic Commands

```bash
# 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

```bash
# 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

```bash
# 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

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

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

### Bulk Operations

```bash
# 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

```bash
# 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

```bash
# 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
# 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](https://github.com/steveyegge/beads)

## 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](../guides/adding-packages.md) - How to add new packages
- [Quick Start](../QUICKSTART.md) - Getting started guide