Crate recursive 

Recursive: a minimal, orthogonal, self-improving coding agent kernel.

The kernel is intentionally tiny:

• Message is the only data primitive shared across the system.
• ChatProvider abstracts model backends (HTTP, mock, future local…).
• Tool abstracts side effects the model can request.
• Agent is a thin loop that wires them together.

Everything else is opt-in. New capabilities are added by implementing Tool or ChatProvider, never by editing the loop.

Lint policy

unwrap() / expect() are banned in production code (AGENTS.md invariant #5). Test code relaxes this via #![cfg_attr(test, allow(...))] below. Any remaining production exception carries #[allow(..., reason = "...")].

Re-exports

pub use agent::FinishReason;

pub use agent::PermissionDecision;

pub use checkpoint::CheckpointId;

pub use checkpoint::CheckpointInfo;

pub use checkpoint::RestoreStats;

pub use checkpoint::ShadowRepo;

pub use checkpoint_log::read_log as read_checkpoint_log;

pub use checkpoint_log::truncate_to_turn as truncate_checkpoint_log;

pub use checkpoint_log::CheckpointLogWriter;

pub use checkpoint_log::CheckpointRecord;

pub use checkpoint_log::TouchedVia;

pub use compact::reinject::build_file_reinjector_from_env;

pub use compact::reinject::build_skill_reinjector_from_env;

pub use compact::Compactor;

pub use compact::FileReinjector;

pub use compact::Microcompactor;

pub use compact::SkillReinjector;

pub use config::Config;

pub use error::Error;

pub use error::Result;

pub use event::AgentEvent;

pub use event::ChannelSink;

pub use event::CompositeSink;

pub use event::EventSink;

pub use event::NullSink;

pub use hooks::ExternalHookRunner;

pub use hooks::ToolTimingHook;

pub use hooks::Hook;

pub use hooks::HookAction;

pub use hooks::HookEvent;

pub use hooks::HookRegistry;

pub use hooks::SdkHookForwarder;

pub use kernel::AgentKernel;

pub use kernel::AgentKernelBuilder;

pub use kernel::TurnContext;

pub use kernel::TurnOutcome;

pub use llm::context_window_tokens_for_model;

pub use llm::default_compact_threshold_chars;

pub use llm::estimate_tokens;

pub use llm::pricing_for;

pub use llm::ChatProvider;

pub use llm::Completion;

pub use llm::ContextBreakdown;

pub use llm::ModelPricing;

pub use llm::RetryPolicy;

pub use llm::TokenUsage;

pub use llm::ToolCall;

pub use llm::ToolSpec;

pub use mcp::discover_mcp_servers;

pub use mcp::load_mcp_config;

pub use mcp::new_elicitation_slot;

pub use mcp::ElicitationHandler;

pub use mcp::ElicitationRequest;

pub use mcp::McpClient;

pub use mcp::McpPrompt;

pub use mcp::McpPromptArgument;

pub use mcp::McpPromptMessage;

pub use mcp::McpResource;

pub use mcp::McpResourceContent;

pub use mcp::McpServer;

pub use mcp::McpServerConfig;

pub use mcp::McpTool;

pub use mcp::McpToolSpec;

pub use mcp::ServerCapabilities;

pub use mcp::SharedElicitationHandler;

pub use mcp_server::McpServerManager;

pub use mcp_server::McpServerRunner;

pub use message::Message;

pub use message::Role;

pub use migrate::migrate_workspace;

pub use migrate::MigrateReport;

pub use multi::register_subagent_if_enabled;

pub use multi::AgentMessage;

pub use multi::AgentPool;

pub use multi::AgentRole;

pub use multi::MessageBus;

pub use multi::MessageType;

pub use multi::SharedMemory;

pub use paths::legacy_paths_in_workspace;

pub use paths::user_data_dir;

pub use paths::user_scratchpad_path;

pub use paths::user_sessions_dir;

pub use paths::user_shadow_git_dir;

pub use paths::user_workspace_dir;

pub use paths::workspace_hash;

pub use permissions::auto_classifier::AutoClassifier;

pub use permissions::auto_classifier::DenialTracker;

pub use permissions::PermissionMode;

pub use permissions::LayeredPermissionsConfig;

pub use permissions::PermissionLayer;

pub use permissions::RuleSource;

pub use permissions::RuleBehavior;

pub use permissions::SharedPermissions;

pub use providers::all_presets;

pub use providers::all_presets_dynamic;

pub use providers::all_presets_effective;

pub use providers::find_preset;

pub use providers::find_preset_effective;

pub use providers::find_preset_extended;

pub use providers::ModelSpec;

pub use providers::ProviderPreset;

pub use rewind::apply_rewind;

pub use rewind::checkpoint_log_path;

pub use rewind::detect_conflicts;

pub use rewind::plan_rewind;

pub use rewind::ConflictReport;

pub use rewind::RewindPlan;

pub use rewind::RewindResult;

pub use runtime::AgentRuntime;

pub use runtime::AgentRuntimeBuilder;

pub use runtime::RuntimeOutcome;

pub use session::OrphanToolCall;

pub use session::SessionFile;

pub use session::SessionPersistenceSink;

pub use session::SessionReader;

pub use session::SessionStatus;

pub use session::SessionWriter;

pub use session::entry_to_message;

pub use session::truncate_transcript_to_turn;

pub use session::SessionLock;

pub use session::SessionMeta;

pub use session::TranscriptEntry;

pub use session::TruncateStats;

pub use skills::discover_skills;

pub use skills::skill_index;

pub use skills::skills_for_injection;

pub use skills::Skill;

pub use skills::SkillMode;

pub use skills::SkillParam;

pub use skills::SkillRef;

pub use skills::SkillScript;

pub use skills::SkillSection;

pub use storage::AgentCheckpointState;

pub use storage::LocalStorageBackend;

pub use storage::NoopSessionStore;

pub use storage::SessionStore;

pub use storage::StorageBackend;

pub use system_prompt::assemble_system_prompt;

pub use system_prompt::AssembledPrompt;

pub use system_prompt::PromptSegments;

pub use tool_set_provider::LocalToolSetProvider;

pub use tool_set_provider::PolicyToolSetProvider;

pub use tool_set_provider::SandboxMode;

pub use tool_set_provider::ToolSetProvider;

pub use tools::policy_sandbox::FsPolicy;

pub use tools::policy_sandbox::PolicyConfig;

pub use tools::policy_sandbox::ShellPolicy;

pub use tools::PermissionHook;

pub use tools::build_standard_tools;

pub use tools::build_standard_tools_with_roots;

pub use tools::new_shared_sandbox_roots;

pub use tools::AccessTier;

pub use tools::AuditMeta;

pub use tools::EnterPlanModeTool;

pub use tools::ExitPlanModeTool;

pub use tools::PlanApprovalGate;

pub use tools::PlanApprovalResult;

pub use tools::PlanModeRequestGate;

pub use tools::PlanModeRequestResult;

pub use tools::ReadFileState;

pub use tools::RequestPlanModeTool;

pub use tools::SharedSandboxRoots;

pub use tools::TodoItem;

pub use tools::TodoStatus;

pub use tools::TodoWriteTool;

pub use tools::Tool;

pub use tools::ToolDispatch;

pub use tools::ToolRegistry;

pub use tools::ToolSideEffect;

pub use tools::TouchedFiles;

pub use tools::AUDIT_ERR_MAX_BYTES;

pub use transcript::TranscriptFile;

pub use transcript::TranscriptMeta;

Modules

acp

ACP (Agent Client Protocol) v1 server support.

agent

Agent types — FinishReason, PermissionDecision, PermissionHook, and PlanningMode.

checkpoint

Shadow bare git repository for per-session, per-turn checkpoints.

checkpoint_log

Per-session log of turn-level checkpoint records.

compact

Context compaction.

config

Runtime configuration.

config_file

Config file support: ~/.recursive/config.toml

coordinator

Coordinator mode gate and tool-set allow-list.

cost

Cost tracking for agent runs.

error

Crate-wide error and Result.

event

Event-sink abstraction for consuming agent lifecycle events.

hooks

Lifecycle hooks for the agent loop.

http

HTTP API server for the Recursive agent.

kernel

Turn-level types for the Agent Run Kernel architecture.

llm

LLM provider abstraction.

logging

Tracing writer that suppresses output while the TUI is active.

mcp

MCP (Model Context Protocol) client — stdio and HTTP+SSE transport, JSON-RPC 2.0.

mcp_server

MCP server lifecycle management.

memory

Vector memory layer — semantic storage and retrieval of agent memories.

message

Chat message primitive.

migrate

Migrate legacy in-tree state to the per-user data dir.

multi

Multi-agent orchestration: agent pool, role definitions, and message bus.

paths

Centralised path resolution for per-user and per-workspace state.

permissions

Static tool permission configuration.

providers

Static vendor preset catalog, embedded at compile time.

providers_cache

Remote provider preset catalog — download, cache, and merge with the bundled + providers.d preset sources.

rewind

Selective rewind for a session’s checkpoint chain.

run_core

Stateless execution kernel — RunCore<'a> and RunInnerOutcome.

runtime

High-level stateful agent runtime.

runtime_goal

Goal-loop primitives: GoalStatus, GoalState, GoalVerdict, and the GoalEvaluator judge model.

session

Session files for production pause/resume.

skills

Skill system: file-based capability extension.

storage

Storage abstraction layer for Recursive.

system_prompt

Unified system-prompt assembly.

tasks

In-memory background-task registry.

tool_set_provider

Tool set provider trait for pluggable, swappable tool implementations.

tools

Tool abstraction: any side effect the model can request.

transcript

Persistent on-disk format for transcripts.

Functions

truncate_str

Safely truncate a string to at most max_bytes bytes without splitting a multi-byte UTF-8 character. Returns the full string if it’s already within the limit.