Crate rusty_beads 

Rusty Beads

A Git-backed graph issue tracker for AI coding agents.

Rusty Beads provides 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
• Dependency Graphs: Model complex relationships with cycle detection
• Context Store: Git-aware caching for file summaries, symbols, and project context
• Semantic Compaction: Reduce context size while preserving essential information
• SQLite Storage: Fast, reliable local storage with WAL mode
• JSONL Export: Git-friendly format for version control
• Background Daemon: RPC server for concurrent access

Quick Start

As a Library

Add to your Cargo.toml:

[dependencies]
rusty-beads = "0.1"

Basic 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, Namespace};
use serde_json::json;
use anyhow::Result;

fn main() -> Result<()> {
    // Open context store
    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 key-value data
    let entry = ContextEntry::new(
        "custom:my-key",
        json!({"data": "value"})
    ).with_ttl(3600); // Expires in 1 hour
    store.set(entry)?;

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

    Ok(())
}

Dependencies

Model complex task relationships:

use rusty_beads::{SqliteStorage, Storage, Dependency, DependencyType};
use anyhow::Result;

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

    // Create a blocking dependency (bd-0002 is blocked by bd-0001)
    let dep = Dependency::blocks("bd-0002", "bd-0001");

    // Check for cycles before adding
    if !storage.would_create_cycle("bd-0002", "bd-0001", DependencyType::Blocks)? {
        storage.add_dependency(&dep)?;
    }

    Ok(())
}

Modules

• types - Core data types (Issue, Status, Dependency, etc.)
• storage - Storage backends (SQLite, JSONL export/import)
• context - Context store for AI agents
• idgen - Hash-based ID generation
• compact - Semantic compaction
• daemon - Background RPC server
• git - Git integration utilities
• cli - Command-line interface

CLI Tool

Install the bd command-line tool:

cargo install rusty-beads

Basic commands:

# Initialize a new repository
bd init

# Create an issue
bd create -t "Fix bug in parser"

# List ready (unblocked) issues
bd ready

# Add a dependency
bd dep add bd-0002 bd-0001

# Use context store
bd context set "file:main.rs" '{"summary": "Entry point"}'
bd context get "file:main.rs"

Architecture

rusty-beads/
├── types/       # Core data types
├── storage/     # SQLite + JSONL backends
├── 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
└── cli/         # Command-line interface

Re-exports

pub use cli::Cli;

pub use cli::run;

pub use types::Issue;

pub use types::Status;

pub use types::IssueType;

pub use types::Dependency;

pub use types::DependencyType;

pub use types::Comment;

pub use types::Event;

pub use types::EventType;

pub use types::Label;

pub use types::IssueFilter;

pub use types::AgentState;

pub use types::MolType;

pub use types::BlockedIssue;

pub use types::Statistics;

pub use storage::Storage;

pub use storage::SqliteStorage;

pub use idgen::generate_id;

pub use context::ContextStore;

pub use context::ContextEntry;

pub use context::Namespace;

pub use context::FileContext;

pub use context::ProjectContext;

pub use context::SessionContext;

Modules

cli

CLI commands for Beads.

compact

Semantic compaction for Beads.

context

Context store for AI coding agents.

daemon

Background daemon for Beads.

git

Git integration for Beads.

idgen

ID generation for Beads.

storage

Storage layer for Beads.

types

Core data types for the Beads issue tracker.

Constants

DEFAULT_PREFIX

Default ID prefix for issues.

VERSION

Library version.