Crate ravenclaws 

RavenClaws

Lightweight, secure Rust agent framework with multi-provider LLM support.

RavenClaws is a single-binary agent runtime that supports:

• Single agent mode — one prompt, one response
• Swarm mode — multiple parallel agents with different personas
• Supervisor mode — task decomposition with sub-agent spawning
• Heartbeat mode — autonomous long-running agents
• REPL mode — interactive conversation
• Server mode — HTTP server with health/metrics endpoints
• MCP server mode — expose tools over stdio via MCP protocol

Architecture

The crate is organized into 18 modules:

Module	Purpose
agent	Agent implementations, agent loop, conversation memory
llm	LLM provider abstraction + 5 client implementations
config	Configuration structs, TOML/env loading, validation
tools	Tool abstraction, registry, 5 built-in tools
policy	Deny-by-default policy engine
sandbox	Sandboxed execution (workdir jail, resource limits)
audit	Tamper-evident audit log (HMAC-SHA256 chained)
mcp	MCP client + server (JSON-RPC 2.0 over stdio + SSE)
swarm	Swarm orchestration, worker profiles, health monitoring
heartbeat	Autonomous heartbeat agent
background	Background task manager with disk persistence
scheduler	Scheduling & triggers (cron, webhook, file-watch)
server	HTTP server mode (health, readiness, metrics)
telemetry	OpenTelemetry tracing (OTLP gRPC/stdout)
ravenfabric	RavenFabric mesh client
eval	Eval harness with assertions and run traces
error	Unified error types

Quick Start

use ravenclaws::config::Config;
use ravenclaws::llm::{create_client, LLMProviderTrait};

let config = Config::load(None)?;
let llm = create_client(&config.llm)?;
let response = llm.chat(vec![
    ravenclaws::llm::ChatMessage {
        role: "user".to_string(),
        content: "Hello!".to_string(),
    },
]).await?;
println!("{}", response.choices[0].message.content);

Security

RavenClaws uses a deny-by-default security model:

• All tool calls are validated by PolicyEngine before execution
• Shell commands execute in a Sandbox with resource limits
• All operations are logged to a tamper-evident AuditLog
• API keys are zeroized on drop

Feature Flags

• otel-grpc (default) — OpenTelemetry tracing via OTLP gRPC exporter
• otel-stdout — OpenTelemetry tracing via stdout exporter

Minimum Supported Rust Version (MSRV)

Rust 1.86 or later. This crate uses edition 2021.

Semver Guarantees

RavenClaws follows semantic versioning. The public API consists of all items documented in this module and re-exported below. Items marked #[doc(hidden)] or in __private modules are not part of the public API and may change in minor releases.

All public enums and structs are #[non_exhaustive] — new variants/fields may be added in minor releases. Match statements on enums must include a wildcard arm, and struct literals must use .. syntax.

Re-exports

pub use agent::delete_checkpoint;

pub use agent::load_checkpoint;

pub use agent::run_agent_loop;

pub use agent::run_agent_loop_with_mcp;

pub use agent::run_agent_loop_with_mcp_and_registry;

pub use agent::run_agent_loop_with_registry;

pub use agent::save_checkpoint;

pub use agent::AgentLoopConfig;

pub use agent::CheckpointState;

pub use agent::ConversationMemory;

pub use audit::AuditLog;

pub use background::BackgroundTaskManager;

pub use config::Config;

pub use config::LLMConfig;

pub use config::LLMProvider;

pub use config::McpConfig;

pub use config::McpServerConfig;

pub use config::RuntimeConfig;

pub use config::SecurityConfig;

pub use error::RavenClawsError;

pub use eval::EvalRunner;

pub use heartbeat::HeartbeatAgent;

pub use llm::create_client;

pub use llm::ChatMessage;

pub use llm::ChatResponse;

pub use llm::LLMProviderTrait;

pub use llm::MultiModelManager;

pub use mcp::McpClient;

pub use mcp::McpClientManager;

pub use mcp::McpServer;

pub use mcp::McpSseServer;

pub use patterns::run_debate;

pub use patterns::run_debate_multi;

pub use patterns::run_research_synthesize;

pub use patterns::run_research_synthesize_multi;

pub use patterns::run_review_loop;

pub use patterns::run_review_loop_multi;

pub use patterns::run_voting;

pub use patterns::run_voting_multi;

pub use patterns::PatternConfig;

pub use policy::PolicyEngine;

pub use ravenfabric::RavenFabricClient;

pub use sandbox::Sandbox;

pub use scheduler::Scheduler;

pub use server::run_server;

pub use swarm::SwarmOrchestrator;

pub use telemetry::TelemetryGuard;

pub use tools::ToolCall;

pub use tools::ToolImpl;

pub use tools::ToolRegistry;

pub use tools::ToolResult;

Modules

agent

RavenClaws

audit

RavenClaws

background

Background task manager for long-horizon async runs

config

RavenClaws

error

RavenClaws

eval

RavenClaws

heartbeat

Autonomous heartbeat — persistent background agent loop

llm

Multi-provider LLM client integration

mcp

Model Context Protocol (MCP) for RavenClaws

patterns

Multi-agent pattern primitives

policy

RavenClaws

ravenfabric

RavenClaws

sandbox

RavenClaws

scheduler

Scheduling & triggers for proactive 24/7 agents

server

RavenClaws

swarm

Swarm orchestration — self-provisioning sub-agents with recursive supervision

telemetry

RavenClaws

tools

RavenClaws