Development Guide

git clone https://github.com/librefang/librefang.git
cd librefang

# Build entire workspace
cargo build --workspace

# Build CLI
cargo build -p librefang-cli

# Build desktop app
cargo build -p librefang-desktop

# Run all tests
cargo test --workspace

# Run specific crate
cargo test -p librefang-kernel

# Run doc tests
cargo test --doc

# Must have zero warnings
cargo clippy --workspace --all-targets -- -D warnings

# Format check
cargo fmt --all -- --check

# Install just (if not already installed)
# macOS: brew install just
# Linux: cargo install just

# List all available commands
just

# Common workflows
just build          # Build workspace (lib only)
just test           # Run all tests
just lint           # Clippy with zero warnings
just fmt            # Format all code
just ci             # Run full local CI (fmt-check + lint + test)
just check          # Quick compilation check
just doc            # Generate and open docs
just sync-versions  # Sync version across all crates

# Install pre-commit
pip install pre-commit

# Install the hooks
pre-commit install

# Now cargo fmt and clippy run automatically on each commit

librefang/
├── Cargo.lock
├── Cargo.toml
├── crates/
│   ├── librefang-cli/          # CLI tool
│   ├── librefang-api/         # REST API server
│   ├── librefang-kernel/      # Core kernel
│   ├── librefang-runtime/     # Agent runtime
│   ├── librefang-memory/      # Memory subsystem
│   ├── librefang-types/       # Shared types
│   ├── librefang-channels/    # Channel adapters
│   ├── librefang-skills/      # Skill system
│   ├── librefang-hands/       # Hands system
│   ├── librefang-wire/        # P2P protocol
│   ├── librefang-desktop/     # Desktop app
│   ├── librefang-migrate/     # Migration tools
│   └── librefang-extensions/   # Extensions
├── xtask/                      # Build scripts
├── docs/                       # Project documentation
└── scripts/                    # Helper scripts

// crates/librefang-channels/src/my_channel.rs

use async_trait::async_trait;
use crate::channel::{Channel, Message, ChannelConfig};

pub struct MyChannel {
    config: ChannelConfig,
}

#[async_trait]
impl Channel for MyChannel {
    async fn send(&self, message: Message) -> Result<(), Error> {
        // Implement send logic
        Ok(())
    }

    async fn receive(&self) -> Result<Message, Error> {
        // Implement receive logic
        Ok(Message::default())
    }
}

// crates/librefang-channels/src/lib.rs

pub mod my_channel;

use crate::registry::ChannelRegistry;

pub fn register_channels(registry: &mut ChannelRegistry) {
    registry.register("my_channel", |config| {
        Ok(Box::new(MyChannel::new(config)))
    });
}

// crates/librefang-types/src/config.rs

#[derive(Debug, Clone, Deserialize)]
pub struct MyChannelConfig {
    pub api_key_env: String,
    pub allowed_users: Option<Vec<String>>,
}

# skills/my-skill/skill.toml
name = "my-skill"
version = "1.0.0"
description = "My custom skill"

[runtime]
type = "python"
entrypoint = "main.py"

[tools]
provided = ["my_tool"]

[requirements]
packages = ["requests"]

# skills/my-skill/main.py

def my_tool(param: str) -> str:
    """My custom tool description"""
    # Implement logic
    return f"Result: {param}"

# Register tools
TOOLS = [my_tool]

# Skills are automatically compiled into binary
cargo build --workspace

// crates/librefang-runtime/src/tools/mod.rs

use crate::tool::{Tool, ToolResult};

pub struct MyTool;

impl Tool for MyTool {
    fn name(&self) -> &str {
        "my_tool"
    }

    fn description(&self) -> &str {
        "My custom tool description"
    }

    async fn execute(&self, params: Value) -> ToolResult {
        // Implement tool logic
        Ok(Value::String("result".to_string()))
    }
}

// crates/librefang-runtime/src/lib.rs

pub fn register_tools(registry: &mut ToolRegistry) {
    registry.register(MyTool::new());
}

// crates/librefang-runtime/src/llm/my_provider.rs

use crate::llm::{LlmDriver, LlmResponse, LlmError};

pub struct MyProvider {
    api_key: String,
    base_url: String,
}

#[async_trait]
impl LlmDriver for MyProvider {
    async fn complete(&self, prompt: &str) -> Result<LlmResponse, LlmError> {
        // Call API
        Ok(LlmResponse {
            text: "response".to_string(),
            tokens: 100,
        })
    }
}

// crates/librefang-types/src/models.rs

pub fn get_provider(name: &str) -> Option<Box<dyn LlmDriver>> {
    match name {
        "my_provider" => Some(Box::new(MyProvider::new())),
        _ => None,
    }
}

# Format: <type>(<scope>): <description>

git commit -m "feat(kernel): add new scheduling algorithm"
git commit -m "fix(channels): resolve Slack rate limit"
git commit -m "docs(api): update endpoint documentation"
git commit -m "test(runtime): add tool execution tests"

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_my_function() {
        assert_eq!(my_function(2), 4);
    }
}

#[tokio::test]
async fn test_agent_spawn() {
    let kernel = Kernel::new().await;
    let agent = kernel.spawn("test-agent").await;
    assert!(agent.is_running());
}

// crates/librefang-kernel/tests/my_feature_test.rs

use librefang_kernel::Kernel;
use librefang_types::AgentManifest;

#[tokio::test]
async fn test_my_feature() {
    // 1. Setup — create test fixtures
    let kernel = Kernel::new_for_testing().await;
    let manifest = AgentManifest::default();

    // 2. Action — exercise the feature
    let agent_id = kernel.spawn_agent(manifest).await.unwrap();

    // 3. Assert — verify expected behavior
    assert!(kernel.get_agent(&agent_id).is_some());
}

#[tokio::bench]
async fn benchmark_llm_call(b: &mut Bencher) {
    b.iter(|| {
        runtime.block_on(llm.complete("test prompt"))
    })
}

use tracing::{info, warn, error};

info!("Starting agent {}", agent_id);
warn!("Rate limit exceeded for channel {}", channel_id);
error!("Failed to connect to provider: {}", error);

# Enable verbose logging
RUST_LOG=debug cargo run

# See specific module only
RUST_LOG=librefang_kernel=trace cargo run

# CPU profiling
cargo flamegraph --bin librefang-cli -- start

# Memory profiling
cargo leptos --bin librefang-cli -- start

# 1. Update version
cargo version bump patch

# 2. Update CHANGELOG
vim CHANGELOG.md

# 3. Create tag
git tag v0.1.0

# 4. Build release
cargo build --release

# 5. Publish to crates.io
cargo publish