Rusty Beads

A Git-backed graph issue tracker for AI coding agents, written in Rust.

Rusty Beads is a Rust implementation of steveyegge/beads, providing a powerful issue tracking system designed specifically for AI coding agents with features like dependency graphs, semantic compaction, and a context store for caching file summaries, symbol indexes, and project metadata.

Features

• Issue Management - Create, update, and track issues with rich metadata (30+ fields)
• Dependency Graphs - Model complex task relationships with automatic cycle detection
• Context Store - Git-aware caching for file summaries, symbols, and project context
• Semantic Compaction - 3-level compaction to reduce context size while preserving essential info
• SQLite Storage - Fast, reliable local storage with WAL mode for concurrent access
• JSONL Export - Git-friendly format for version control and collaboration
• Background Daemon - JSON-RPC server over Unix sockets for concurrent access
• Hash-based IDs - Collision-free identifiers in bd-xxxx format

Installation

As a CLI Tool

cargo install rusty-beads

As a Library

Add to your Cargo.toml:

[dependencies]
rusty-beads = "0.1"

Quick Start

CLI Usage

# Initialize a new beads repository
bd init

# Create issues
bd create -t "Implement user authentication"
bd create -t "Add login endpoint" --parent bd-a1b2

# View ready (unblocked) work
bd ready

# Add dependencies
bd dep add bd-c3d4 bd-a1b2  # bd-c3d4 is blocked by bd-a1b2

# List issues
bd list
bd list --status open --assignee alice

# Update and close issues
bd update bd-a1b2 --status in_progress
bd close bd-a1b2 --reason "Completed"

# Use the context store
bd context set "file:src/main.rs" '{"summary": "Application entry point"}'
bd context get "file:src/main.rs"
bd context list --namespace file

Library Usage

use rusty_beads::{SqliteStorage, Storage, Issue, generate_id};
use anyhow::Result;

fn main() -> Result<()> {
    // Open or create a database
    let storage = SqliteStorage::open(".beads/beads.db")?;

    // Create an issue
    let id = generate_id("bd");
    let issue = Issue::new(&id, "Implement new feature", "developer");
    storage.create_issue(&issue)?;

    // Get ready work (unblocked issues)
    let ready = storage.get_ready_work()?;
    for issue in ready {
        println!("{}: {}", issue.id, issue.title);
    }

    Ok(())
}

Context Store

The context store helps AI agents cache and retrieve contextual information with automatic git-aware invalidation:

use rusty_beads::{ContextStore, ContextEntry, FileContext};
use serde_json::json;
use anyhow::Result;

fn main() -> Result<()> {
    let store = ContextStore::open(".beads/context.db")?;

    // Store file context
    let file_ctx = FileContext {
        path: "src/main.rs".to_string(),
        summary: Some("Application entry point".to_string()),
        language: Some("rust".to_string()),
        ..Default::default()
    };
    store.set_file_context("src/main.rs", &file_ctx)?;

    // Store arbitrary data with TTL
    let entry = ContextEntry::new("custom:cache-key", json!({"data": "value"}))
        .with_ttl(3600); // Expires in 1 hour
    store.set(entry)?;

    // Retrieve with automatic invalidation checking
    if let Some(ctx) = store.get_file_context("src/main.rs")? {
        println!("Summary: {:?}", ctx.summary);
    }

    Ok(())
}

Architecture

rusty-beads/
├── src/
│   ├── lib.rs           # Public API and documentation
│   ├── main.rs          # CLI entry point
│   ├── types/           # Core data types (Issue, Status, Dependency, etc.)
│   ├── storage/         # SQLite backend + JSONL import/export
│   ├── context/         # Context store with git-aware invalidation
│   ├── idgen/           # Hash-based ID generation (bd-xxxx)
│   ├── compact/         # Semantic compaction (3 levels)
│   ├── daemon/          # Background RPC server
│   ├── git/             # Git integration utilities
│   └── cli/             # Command-line interface

CLI Commands

Context Store Namespaces

The context store organizes data into namespaces:

Git-Aware Invalidation

The context store automatically invalidates cached entries when:

• File modification time (mtime) changes
• File has uncommitted git changes
• Git HEAD commit changes
• TTL expires

Issue Types

Rusty Beads supports various issue types for different use cases:

• bug, feature, task, epic, chore - Standard issue types
• molecule, gate, agent, role, rig - AI agent-specific types
• convoy, event, merge_request, slot - Advanced workflow types

Dependency Types

Model complex relationships between issues:

• blocks - Issue A blocks issue B
• parent_child - Hierarchical relationship
• relates_to - General relationship
• duplicates - Duplicate issues
• supersedes - Replacement relationship
• And 14 more specialized types

Storage

• SQLite with WAL mode for concurrent access
• JSONL export for git-friendly version control
• Dirty tracking for incremental exports
• Content hashing for change detection

Development

# Build
cargo build

# Run tests
cargo test

# Generate documentation
cargo doc --open

# Run with debug logging
RUST_LOG=debug cargo run -- list

Inspired By

This project is a Rust implementation inspired by steveyegge/beads, the original Go implementation.

License

MIT License - see LICENSE for details.