Architecture
Crate dependency structure, core abstractions, pipeline stages, and message flow in the clawft framework.
Crate Structure
This page covers the agent-runtime crates of the workspace. They form a strict dependency hierarchy: shared types at the bottom, platform abstraction above them, then core engine logic, with tools, channels, services, plugins, and the CLI at the top. The workspace has many more crates (the kernel, the node daemon clawft-weave, mesh, voice, GUI and hardware crates); see the WeftOS architecture page and the crates/ directory.
clawft-cli (weft binary)
/ | | | \ \ \
clawft- clawft- clawft- clawft- clawft- clawft-
tools channels services plugin llm security
| | | | |
+--------+-------+ | |
| | |
clawft-core (plugin crates x8) |
| \ | |
clawft- clawft- clawft-plugin -----+
platform llm |
\ |
clawft-types -----------+
clawft-wasm (browser entrypoint)
|
clawft-typesclawft-llm is a standalone LLM provider abstraction with no dependency on the agent-loop crates.
Crate Reference
clawft-types
Foundation crate with zero internal dependencies. All other crates depend on it.
Key types:
ClawftError/ChannelError-- error enums used framework-wideConfig-- root configuration schema (deserialized from JSON)AgentsConfig/AgentDefaults-- agent parameters (model, max_tokens, temperature, memory_window, max_tool_iterations)InboundMessage/OutboundMessage-- message events flowing through the busLlmResponse/ContentBlock/StopReason/Usage-- LLM response typesSession-- conversation session state with JSONL-backed persistence
clawft-platform
Platform abstraction layer enabling portability across native and WASM targets.
Key traits:
Platform-- bundlesfs(),env(),http(), andprocess()accessorsNativePlatform-- production implementation (reqwest, tokio::fs, std::env, tokio::process)HttpClient/FileSystem/Environment/ProcessSpawner-- async abstractionsConfigLoader-- config file discovery chain with camelCase-to-snake_case normalization
ProcessSpawner returns Option from Platform::process() since WASM lacks process spawning.
clawft-llm
Standalone LLM provider abstraction.
Key types:
Providertrait -- definescomplete(ChatRequest) -> ChatResponseOpenAiCompatProvider-- implementation for any OpenAI-compatible HTTP APIProviderRouter-- routes model identifiers (e.g.,"openai/gpt-4o") to provider instances via longest-prefix matchingProviderConfig-- connection configuration (base URL, API key, headers)ChatRequest/ChatResponse/ToolCall/Usage-- request/response types
clawft-core
Central engine containing the agent loop, message bus, pipeline, session management, and security primitives.
Modules:
- bus --
MessageBus: tokio MPSC channels for inbound/outbound message routing - pipeline -- 6-stage pluggable pipeline with
PipelineRegistrymappingTaskTypeto specialized pipelines - agent --
AgentLoop(message processing),ContextBuilder(system prompt + skills + memory + history),MemoryStore,SkillsLoader - session --
SessionManager: JSONL-backed persistence keyed by"{channel}:{chat_id}" - security --
validate_session_id(),sanitize_content(),truncate_result()(64KB cap) - bootstrap --
AppContext: wires all dependencies;enable_live_llm()swaps stub forClawftLlmAdapter
Optional feature: vector-memory -- enables embeddings, vector store, intelligent router, session indexer.
clawft-tools
Built-in tool implementations: file tools (read_file, write_file, edit_file, list_directory), exec_shell, memory tools, web_search, web_fetch, spawn, UI rendering, sub-agent tools, and voice and audio tools when the voice feature is on (crates/clawft-tools/src/lib.rs, register_all). All file tools enforce workspace path containment. See Tools for the list.
clawft-channels
Plugin-based chat channel system with three core traits (Channel, ChannelHost, ChannelFactory) and PluginHost for lifecycle management. weft gateway registers Telegram, Slack and Discord, and the gateway serves the in-process web channel. Seven more adapters (email, whatsapp, signal, matrix, irc, google_chat, teams) exist behind Cargo features but are not registered by the gateway. See Channels for the per-adapter status table.
clawft-services
Background services: CronService (scheduled jobs), HeartbeatService, MCP subsystem (server and client modes), and DelegationEngine (task routing).
clawft-plugin
Plugin trait definitions and runtime infrastructure: six extension-point traits, the plugin manifest, skill loader, hot-reload watcher, permission system and slash-command registry. The wasmtime-based plugin host lives in clawft-wasm-host, re-exported by clawft-wasm behind the wasm-plugins feature.
clawft-cli
The weft binary. Depends on all workspace crates. Provides the clap-derived CLI command tree and terminal-friendly markdown rendering.
clawft-wasm
Browser and WASI entrypoint. By default it depends on clawft-types; the browser feature adds clawft-core, clawft-llm, clawft-tools and clawft-platform for the in-tab agent. See Browser Mode.
Pipeline Architecture
Every message flows through a 6-stage pipeline:
ChatRequest
|
[1. Classifier] -- TaskProfile (type, complexity)
|
[2. Router] -- RoutingDecision (provider, model)
|
[3. Assembler] -- AssembledContext (messages, token estimate)
|
[4. Transport] -- LlmResponse
|
[5. Scorer] -- QualityScore (overall, relevance, coherence)
|
[6. Learner] -- Trajectory
|
LlmResponseThe PipelineRegistry maps TaskType variants to specialized Pipeline instances. Unregistered task types fall back to the default pipeline. Default (Level 0) implementations; configuration can select Level 1 stages (FitnessScorer, TrajectoryLearner) and the tiered router:
| Stage | Implementation | Behavior |
|---|---|---|
| Classifier | KeywordClassifier | Keyword-based TaskType assignment |
| Router | StaticRouter | Config-driven model selection |
| Assembler | TokenBudgetAssembler | chars/4 heuristic, drops middle messages |
| Transport | OpenAiCompatTransport | Stub or live via ClawftLlmAdapter |
| Scorer | NoopScorer | Returns 1.0 |
| Learner | NoopLearner | Discards trajectories |
Message Flow
- A Channel plugin receives an external message and publishes an
InboundMessageto theMessageBus. - The AgentLoop consumes the inbound message, retrieves or creates a
Session, and builds the LLM context viaContextBuilder. - The Pipeline processes the request through all 6 stages.
- If the LLM response contains
ToolUseblocks, the agent enters a tool execution loop:- Each tool is executed via the
ToolRegistry. - Results are truncated to 64KB and appended as tool-result messages.
- The pipeline is re-invoked with the extended message list.
- The loop continues until no tool calls remain or
max_tool_iterationsis reached.
- Each tool is executed via the
- The agent saves the session and dispatches an
OutboundMessageto the bus. - The bus routes the outbound message to the target channel, which sends it via the platform API.
Bootstrap Sequence
AppContext::new(config, platform)
|
+-- Create MessageBus
+-- Initialize SessionManager (discover sessions dir)
+-- Initialize MemoryStore (discover memory dir)
+-- Initialize SkillsLoader (discover skills dir)
+-- Create ContextBuilder
+-- Create empty ToolRegistry
+-- Wire default Level 0 Pipeline
|
+-- tools_mut().register() -- Register tools
+-- enable_live_llm() -- Replace stub with ClawftLlmAdapter
+-- set_pipeline() -- Inject custom pipeline (optional)
|
+-- into_agent_loop()
+-- AgentLoop::run()Build Configuration
- Rust edition: 2024
- Minimum Rust version: 1.95 (
rust-versioninCargo.toml;rust-toolchain.tomlpins1.95) - License: MIT OR Apache-2.0
- Release profile:
opt-level = 3, LTO, stripped symbols, single codegen unit, abort on panic - WASM release profile (
release-wasm): inherits release withopt-level = "z"