The runtime crate is the central coordination layer of claw. It bridges the low-level API clients and tool implementations into a cohesive, stateful conversation experience. The primary entity, ConversationRuntime, manages the "turn loop"—the iterative process of sending prompts to an LLM, parsing tool calls, enforcing permissions, executing tools, and feeding results back into the context.
The runtime is designed around a decoupled architecture where the conversation logic is agnostic of the specific LLM provider or the underlying terminal UI. It relies on the ApiClient trait for model communication and the ToolExecutor trait for capability execution.
This diagram illustrates how the ConversationRuntime coordinates between different subsystems to process a single user message.
"ConversationRuntime Coordination Flow"
Sources: rust/crates/runtime/src/conversation.rs126-139 rust/crates/runtime/src/lib.rs71-75
The core of the engine is ConversationRuntime::run_turn(). This method handles the complexity of streaming responses and managing multi-step tool invocations. It integrates a robust hook system (HookRunner) that allows plugins and system defaults to intercept the loop at three critical points: PreToolUse, PostToolUse, and PostToolUseFailure. These hooks can modify tool inputs, provide additional context, or even abort execution.
For details, see Conversation Loop & Hook System.
Sources: rust/crates/runtime/src/conversation.rs224-250 rust/crates/runtime/src/hooks.rs18-23
The Session struct manages the conversation history, represented as a series of ConversationMessage and ContentBlock objects. To prevent context window overflow and reduce latency, the runtime implements an automatic compaction system. When the auto_compaction_input_tokens_threshold (default 100,000) is exceeded, the compact_session() logic triggers, summarizing older messages while preserving critical context.
For details, see Session Persistence & Compaction.
Sources: rust/crates/runtime/src/session.rs149-152 rust/crates/runtime/src/compact.rs55-58 rust/crates/runtime/src/conversation.rs18-19
The runtime behavior is governed by a hierarchical configuration system. ConfigLoader merges settings from global, project, and local files into a RuntimeConfig. This configuration influences the SystemPromptBuilder, which dynamically assembles the LLM's instructions by scanning for CLAUDE.md, analyzing the ProjectContext, and calculating prompt budgets.
For details, see Configuration & System Prompt.
Sources: rust/crates/runtime/src/config.rs59-66 rust/crates/runtime/src/prompt.rs130-133
Security is enforced via the PermissionPolicy and PermissionEnforcer. Every tool execution request is evaluated against a PermissionMode (e.g., ReadOnly, WorkspaceWrite). The system includes specialized validation for bash commands (bash_validation.rs) to detect destructive operations and ensure execution remains within defined boundaries.
For details, see Permission System & Security.
Sources: rust/crates/runtime/src/permissions.rs118-121 rust/crates/runtime/src/permission_enforcer.rs29 rust/crates/runtime/src/bash_validation.rs8
The following diagram maps the internal code structures used during a single model interaction.
"Runtime Logic to Code Entity Mapping"
Sources: rust/crates/runtime/src/conversation.rs23-26 rust/crates/runtime/src/conversation.rs30-40 rust/crates/runtime/src/conversation.rs109-117 rust/crates/runtime/src/session_control.rs38-39
The runtime also serves as the host for the Model Context Protocol (MCP) and Plugins.
McpServerManager manages the lifecycle of external tool providers via stdio or remote transports. rust/crates/runtime/src/mcp_stdio.rs107PluginLifecycle handles the discovery and state management of internal and external extensions. rust/crates/runtime/src/plugin_lifecycle.rs122-125Refresh this wiki