clawft

clawft Overview

A Rust-native agent framework for building multi-channel, tool-augmented LLM agents with tiered routing, skill auto-generation, and cost tracking.

What is clawft?

clawft is a Rust agent framework -- the user-space agent runtime that powers WeftOS. It implements a complete agent lifecycle: message consumption, context assembly, LLM pipeline routing, tool execution, skill management, memory persistence, and multi-channel communication.

The framework compiles to native binaries, WASM for browsers, and WASI for server-side sandboxing. The primary binary is weft (the CLI agent).

The agent-runtime crates form a strict dependency hierarchy -- shared types at the bottom, platform abstraction above them, then the core engine, with tools, channels, services, plugins, and the CLI at the top. A WASM crate provides a browser-compatible entrypoint. The wider workspace adds the WeftOS kernel, the node daemon (weaver), mesh, voice and GUI crates.

clawft as an Agent

clawft is not a library for calling LLM APIs. It is a complete agent runtime -- the Rust-native equivalent to frameworks like Hermes (NousResearch) or OpenClaw. The AgentLoop at its center implements a consume-process-respond cycle with tool use:

  1. Inbound -- A message arrives from one of the production channels (Telegram, Slack, Discord, or the in-process web channel) via the MessageBus. Seven more adapters exist as library code that weft gateway does not register; see Channels for the per-adapter status.
  2. Session -- The loop retrieves or creates a conversation session.
  3. Context -- ContextBuilder assembles the system prompt, active skill instructions, memory (MEMORY.md), and conversation history into an LLM-ready message list.
  4. Pipeline -- The message passes through a 6-stage pluggable pipeline: Classifier, Router, Assembler, Transport, Scorer, Learner.
  5. Tool Loop -- If the LLM responds with tool calls, the agent executes them, appends results, and re-invokes the LLM -- up to max_tool_iterations rounds.
  6. Outbound -- The final response is dispatched back through the MessageBus to the originating channel.

See Agent Loop for the full architecture and Pipeline for stage-by-stage detail.

Positioning

ConcernclawftHermes (Python)
LanguageRust (native + WASM + WASI)Python
Pipeline6-stage pluggable, trait-basedSimple LLM call
Tiered routingComplexity-scored, cost-tracked, permission-awareKeyword heuristic
Skill hot-reloadFilesystem watcher, atomic swapNot available
Cost trackingPer-tier budget enforcement with daily/monthly limitsNot available
Rate limitingPer-senderNot available
Kernel integrationPID tracking, governance, ExoChain, ECC, WASM sandbox, meshNone

clawft's differentiator is the kernel integration layer: when running on WeftOS, agents gain ExoChain cryptographic provenance, three-branch constitutional governance, ECC cognitive substrate, WASM sandboxing, and mesh networking.

Key Features

  • 6-stage processing pipeline -- Classify, route, assemble context, transport to LLM, score quality, and feed learning signals. Every stage is trait-based and replaceable.
  • Tiered model routing -- Complexity-based routing across four model tiers (Free/Standard/Premium/Elite) with per-sender cost tracking and budget enforcement.
  • Context compression -- When a conversation outgrows its token budget, older turns are summarized into the window (an LLM summarizer, with a first-sentence fallback) while the full text stays on the chain (crates/clawft-core/src/agent/context_compress.rs, ADR-058). Opt-in via ContextBuilder::with_compression(config).
  • GEPA prompt evolution -- Genetic Evolution of Prompt Architectures. The pipeline's Scorer and Learner stages are now production-ready: FitnessScorer evaluates responses on 4 weighted dimensions, and TrajectoryLearner collects trajectories, extracts patterns, and applies prompt mutation strategies (rephrase, add examples, remove ineffective, emphasize).
  • Local LLM provider -- OpenAI-compatible provider for local inference servers. Factory methods for Ollama (LocalProvider::ollama()), vLLM (::vllm()), llama.cpp (::llamacpp()), and LM Studio (::lmstudio()). Key-optional auth, streaming, and model listing. See the Quickstart for setup.
  • Skill auto-generation -- Detects repeated tool-call patterns and generates skill candidates after a configurable threshold (default: 3 repetitions). Requires user approval.
  • Cost tracking -- Per-tier budget enforcement with daily and monthly spending limits, recording both estimated and actual costs.
  • Multi-provider LLM routing -- Nine hosted providers (OpenAI, Anthropic, Groq, DeepSeek, Mistral, Together, OpenRouter, Gemini, xAI) plus the local/ and ollama/ local providers, with prefix-based routing, automatic retry, and environment-driven API keys.
  • Channels -- Telegram, Slack, Discord and the in-process web channel are wired into weft gateway; adapters for Email, WhatsApp, Signal, Matrix, IRC, Google Chat and Microsoft Teams exist as library code. All share one trait interface and lifecycle.
  • Built-in tool system -- File I/O, shell execution, memory, web search/fetch, messaging, voice, and subprocess spawning -- all workspace-sandboxed with security policies.
  • Plugin architecture -- Six extension points (Tool, Channel, Pipeline, Skill, Memory, Voice), WASM sandbox (wasmtime), hot-reload, permission system, and slash-command registry.
  • Skills and agents -- Reusable prompt bundles (SKILL.md) and named agent personas (agent.yaml) with template variables, tool allowlists, and three-level discovery (workspace, user, builtin).
  • MCP integration -- Serve tools to external MCP clients or consume tools from external MCP servers. Internal-only mode for infrastructure servers with skill-based per-turn filtering.
  • WASM / browser target -- The clawft-wasm crate compiles to WebAssembly for in-browser operation.
  • Security-first -- Workspace containment, command allowlists, SSRF protection, permission-gated tool access, WASM fuel metering, prompt injection stripping, and 57-check security auditor.

Quick Install

Install weft from a release (installer, Homebrew or Docker; see Installation):

curl -fsSL https://raw.githubusercontent.com/WeftOS/weftos/master/scripts/install.sh | sh
# or
brew install weave-logic-ai/tap/clawft-cli

Or build from source with the project build script (Rust 1.95 or newer):

git clone https://github.com/WeftOS/weftos.git
cd weftos
scripts/build.sh native          # release build; binary at target/release/weft
scripts/build.sh native-debug    # faster iteration

For Docker (the entrypoint is weft, so arguments go straight to it):

docker run --rm ghcr.io/weftos/weftos:latest --version

First Run

Set an API key for any supported provider:

export ANTHROPIC_API_KEY="sk-ant-..."

Start an interactive session:

weft agent

Send a single message:

weft agent -m "Summarize the Rust async ecosystem"

Documentation Sections

  • Getting Started -- Installation, first conversation, key concepts
  • Architecture -- Crate structure, pipeline, message flow
  • Agent Runtime
    • Agent Loop -- The consume-process-respond cycle, auto-delegation, tool execution
    • Pipeline -- 6-stage processing pipeline, tiered routing, cost tracking
    • Skills -- SKILL.md format, discovery chain, auto-generation, hot-reload
    • Memory -- MEMORY.md / HISTORY.md, directory resolution, platform abstraction
  • Integration
    • Tools -- Built-in tools, MCP tools, custom tool providers
    • Channels -- Communication channels setup and custom channels
    • Providers -- LLM provider configuration, routing, custom providers
    • Plugins -- Plugin system, built-in plugins, WASM sandbox
  • Infrastructure
    • CLI Reference -- Complete command-line reference for weft
    • Configuration -- Config file format, environment variables, all keys
    • Browser Mode -- WASM build, browser quickstart, test harness
    • Deployment -- Docker, WASM, CI/CD pipeline
    • Security -- Security model, command policies, SSRF protection, WASM sandbox

On this page