Skip to content

README.md

Latest commit

 

History

History
253 lines (175 loc) · 9.7 KB

README.md

File metadata and controls

253 lines (175 loc) · 9.7 KB

🦀 Claw RS

A modular agent runtime extracted from Claude Code, rebuilt in Rust, and still in active development.

Status Language Origin License PRs Welcome

English | 简体中文 | 日本語 | 한국어 | Español | Français

🚧Early-stage project under active development — not production-ready yet.

⭐ Star us to follow along — a usable version is coming within a month!

Project Overview

📖 Table of Contents

💡 What is This

This project extracts the core runtime ideas from Claude Code and reorganizes them into a set of reusable Rust crates. It's not a line-by-line TypeScript translation — it's a clean-room redesign of the capabilities an agent truly depends on:

  • Message Loop — driving multi-turn conversations
  • Tool Execution — orchestrating tool calls with schema validation
  • Permission Control — authorization before file/shell/network access
  • Long-running Tasks — background execution with lifecycle management
  • Context Compaction — keeping long sessions stable under token budgets
  • Model Providers — unified interface for streaming LLM backends
  • MCP Integration — extending capabilities via Model Context Protocol

Think of it as an agent runtime skeleton:

Layer Role
Top A thin CLI that assembles all crates
Middle Core runtime: message loop, tool orchestration, permissions, tasks, model abstraction
Bottom Concrete implementations: built-in tools, MCP client, context management

If the boundaries are clean enough, this can serve not only Claude-style coding agents, but any agent system that needs a solid runtime foundation.

🚀 Quick Start

Prerequisites

  • Rust 1.75+ (install)
  • Model backend — one of the following:
    • Ollama (recommended for local development)
    • Anthropic API key

Build

git clone <repo-url> && cd rust-clw
cargo build

Run with Ollama (local, no API key needed)

Make sure Ollama is running and has a model pulled:

# Pull a model (only needed once)
ollama pull qwen3.5:9b

# Single query
cargo run -- --provider ollama -m "qwen3.5:9b" -q "list files in the current directory"

# Interactive REPL
cargo run -- --provider ollama -m "qwen3.5:9b"

Any model with tool-calling support works. Larger models produce better tool-use results:

cargo run -- --provider ollama -m "qwen3.5:27b" -q "read Cargo.toml and summarize the workspace"

Run with Anthropic API

export ANTHROPIC_API_KEY="sk-ant-..."
cargo run -- -q "list files in the current directory"

CLI Options

Usage: claw-rs [OPTIONS]

Options:
  -m, --model <MODEL>          Model name (default: auto per provider)
  -s, --system <SYSTEM>        System prompt
  -p, --permission <MODE>      Permission mode: auto, interactive, deny
  -q, --query <QUERY>          Single query (non-interactive), omit for REPL
      --provider <PROVIDER>    Provider: anthropic, ollama, openai, stub
      --ollama-url <URL>       Ollama server URL (default: http://localhost:11434)
      --max-turns <N>          Max turns per conversation (default: 100)

Supported Providers

Provider Backend How to activate
ollama Ollama (local) --provider ollama or auto when no ANTHROPIC_API_KEY
anthropic Anthropic API Set ANTHROPIC_API_KEY env var
openai Any OpenAI-compatible API --provider openai + OPENAI_BASE_URL
stub No real model (for testing) --provider stub

🤔 Why Rebuild in Rust

Claude Code has excellent engineering quality, but it's a complete product, not a reusable runtime library. UI, runtime, tool systems, and state management are deeply intertwined. Reading the source teaches a lot, but extracting parts for reuse is nontrivial.

This project aims to:

  • Decompose tightly coupled logic into single-responsibility crates
  • Replace runtime constraints with trait and enum boundaries
  • Transform "only works inside this project" implementations into reusable agent components

🎯 Design Goals

  1. Runtime first, product later. Prioritize solid foundations for Agent loop, Tool, Task, and Permission.
  2. Each crate should be self-explanatory. Names reveal responsibility, interfaces reveal boundaries.
  3. Make replacement natural. Tools, model providers, permission policies, and compaction strategies should all be swappable.
  4. Learn from Claude Code's experience without replicating its UI or internal features.

🏗 Architecture

Architecture Overview

Crate Map

Crate Purpose Derived From (Claude Code)
clawcr-core Message model, state container, main loop, session query.ts, QueryEngine.ts, state/store.ts
clawcr-tools Tool trait, registry, execution orchestration, and built-in tools Tool.ts, tools.ts, tool service layer
clawcr-tasks Long task lifecycle and notification mechanism Task.ts, tasks.ts
clawcr-permissions Tool call authorization and rule matching types/permissions.ts, utils/permissions/
clawcr-provider Unified model interface, streaming, retry services/api/
clawcr-compact Context trimming and token budget control services/compact/, query/tokenBudget.ts
clawcr-mcp MCP client, connection, discovery, reconnect services/mcp/
clawcr-cli Executable entry point, assembles all crates CLI layer

🔍 Crate Overview

clawcr-core — The foundation

Manages how a conversation turn starts, continues, and stops. Defines the unified message model, main loop, and session state. This is the bedrock of the entire system.

clawcr-tools — Tools and dispatch

Defines tools, schedules them, and ships the built-in file, shell, search, and edit capabilities in one crate.

clawcr-tasks — Background task runtime

Separating tool calls from runtime tasks is critical for supporting long commands, background agents, and completion notifications fed back into the conversation.

clawcr-permissions — Authorization layer

Controls what the agent can do, when it must ask the user, and when to refuse outright. Essential whenever agents read files, write files, or execute commands.

clawcr-provider — Model abstraction

Shields the system from differences between model backends. Unifies streaming output, retry logic, and error recovery.

clawcr-compact — Context management

Ensures long session stability. Not just "summarization" — applies different compression levels and budget controls based on context to prevent unbounded growth.

clawcr-mcp — MCP integration

Connects to external MCP services, bringing remote tools, resources, and prompts into the unified capability surface.

clawcr-cli — CLI entry point

Packages the executable as claw-rs and wires together the runtime crates for interactive and one-shot use.

🗺 Roadmap

Roadmap

1-Week Plan

  • Day 1: Finalize crate boundaries and wire the minimal CLI
  • Day 2: Land Bash, FileRead, and FileWrite
  • Day 3: Stabilize provider flow, permissions, and session state
  • Day 4: Add editing and search tools
  • Day 5: Improve long-session handling with tasks and compaction
  • Day 6: Start MCP and plugin/skill integration
  • Day 7: Run focused testing, fix gaps, and document the next slice

🤝 Contributing

Contributions are welcome! This project is in its early design phase, and there are many ways to help:

  • Architecture feedback — Review the crate design and suggest improvements
  • RFC discussions — Propose new ideas via issues
  • Documentation — Help improve or translate documentation
  • Implementation — Pick up crate implementation once designs stabilize

Please feel free to open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License.

If you find this project useful, please consider giving it a ⭐