Crate claw_branch 

claw-branch

A Rust library for isolated, SQLite-backed agent branch management.

claw-branch gives AI agents a structured way to diverge from a shared knowledge baseline, explore changes in isolation, diff and merge back, and evaluate outcomes in a fully sandboxed environment — all backed by SQLite and enforced through a strongly-typed async API.

Core concepts

Concept	Description
Branch	An isolated SQLite database snapshot with its own lifecycle state
Trunk	The canonical baseline branch; all other branches fork from it
Fork	Creates a copy-on-write snapshot of a parent branch
Diff	Entity-level comparison between two branches
Merge	Three-way merge with configurable conflict resolution strategy
Commit	Selective cherry-pick of entities from one branch to another
Sandbox	Temporary evaluation environment for speculative agent work
DAG	Directed acyclic graph tracking branch lineage

Quick-start

use claw_branch::prelude::*;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = BranchConfig::builder()
        .workspace_dir(PathBuf::from("/tmp/demo"))
        .build()?;

    let engine = BranchEngine::new(config, std::path::Path::new("/data/source.db")).await?;

    // Fork a feature branch from trunk
    let feature = engine.fork_trunk("feature/summariser").await?;

    // Diff against trunk
    let trunk = engine.trunk().await?;
    let diff  = engine.diff(trunk.id, feature.id).await?;
    println!("changed={}", diff.stats.modified);

    // Simulate an agent workload and get a recommendation
    let report = engine.simulate(feature.id, SimulationScenario {
        name: "trial".into(),
        description: "test run".into(),
        max_ops: Some(100),
        timeout_secs: Some(30),
        seed_data: None,
    }, |pool| async move {
        // agent writes to pool…
        Ok(serde_json::json!({"status": "done"}))
    }).await?;

    match report.recommendation {
        Recommendation::Commit => { engine.commit_to_trunk(feature.id).await?; }
        Recommendation::Discard => { engine.discard(feature.id).await?; }
        Recommendation::NeedsReview(notes) => println!("Review: {notes:?}"),
    }

    Ok(())
}

Re-exports

pub use config::BranchConfig;

pub use config::BranchConfigBuilder;

pub use engine::BranchConfigError;

pub use engine::BranchEngine;

pub use engine::BranchEngineBuilder;

pub use error::BranchError;

pub use error::BranchResult;

pub use types::Branch;

pub use types::BranchMetrics;

pub use types::BranchStatus;

pub use types::CommitLogEntry;

pub use types::CommitResult;

pub use types::DiffKind;

pub use types::DiffResult;

pub use types::DiffStats;

pub use types::EntityDiff;

pub use types::EntityType;

pub use types::FieldDiff;

pub use types::MergeConflict;

pub use types::MergeResult;

pub use types::SimulationOutcome;

pub use types::WorkspaceReport;

pub use diff::formatter::DiffSummary;

pub use merge::resolver::ResolvedValue;

pub use merge::strategies::MergeStrategy;

pub use merge::three_way::MergePreview;

pub use commit::cherry::CherryPick;

pub use commit::cherry::EntitySelection;

pub use commit::selective::SelectiveCommit;

pub use commit::validator::CommitValidator;

pub use commit::validator::ValidationReport;

pub use sandbox::environment::SandboxStatus;

pub use sandbox::environment::SimulationEnvironment;

pub use sandbox::environment::SimulationScenario;

pub use sandbox::evaluator::EvaluationReport;

pub use sandbox::evaluator::Recommendation;

pub use sandbox::evaluator::SandboxEvaluator;

pub use sandbox::runner::SandboxRunner;

pub use metrics::divergence::compute_score;

pub use metrics::divergence::divergence_label;

pub use metrics::divergence::time_weighted_score;

pub use metrics::reporter::MetricsReporter;

pub use metrics::tracker::MetricsTracker;

pub use metrics::tracker::OpKind;

pub use snapshot::gc::GcReport;

Modules

branch

Branch management primitives. Branch registry, lifecycle management, and naming helpers.

commit

Selective commit and history helpers. Selective commit and branch history helpers.

config

Shared configuration for branch operations. Branch engine configuration and environment loading.

dag

DAG lineage graph support. DAG lineage graph modules.

diff

Diff extraction and reporting. Diff extraction and reporting modules.

engine

Top-level engine orchestration. Unified BranchEngine coordinating all claw-branch subsystems.

error

Error types used across the crate. Error types for branch orchestration.

merge

Merge algorithms and conflict handling. Merge subsystem: three-way merges, conflict resolution, and apply helpers.

metrics

Metrics collection and reporting. Branch metrics subsystem: tracking, divergence scoring, and reporting.

prelude

Convenience re-exports for typical library consumers.

sandbox

Simulation sandbox support. Simulation sandbox modules for isolated agent evaluation.

snapshot

Snapshot creation, verification, and garbage collection. Snapshot creation, verification, and cleanup utilities.

types

Shared domain types. Shared domain types used across the branch engine.