claurst-claude-code-rust

What this skill does

```markdown
---
name: claurst-claude-code-rust
description: Clean-room Rust reimplementation of Claude Code CLI with multi-agent orchestration, tool system, and memory consolidation
triggers:
  - "use claurst"
  - "build with claurst"
  - "claude code rust implementation"
  - "set up claurst CLI"
  - "claurst tool system"
  - "claurst agent orchestration"
  - "implement claurst memory"
  - "claurst bash tool"
---

# Claurst — Claude Code in Rust

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Claurst is a clean-room Rust reimplementation of Claude Code's behavior, derived from exhaustive behavioral specifications (not the original TypeScript source). It reproduces the full Claude Code CLI feature set — multi-agent orchestration, 40+ tools, background memory consolidation ("dream"), KAIROS proactive mode, ULTRAPLAN remote planning, and the BUDDY companion system — in idiomatic Rust.

---

## Project Structure

```
claurst/
├── spec/                        # Behavioral specifications (AI-generated from analysis)
├── src-rust/
│   └── crates/
│       ├── cli/                 # Entry point (main.rs)
│       ├── assistant/           # Core agent loop, KAIROS proactive mode
│       ├── tools/               # All tool implementations (bash, fs, search, etc.)
│       ├── query/               # Memory compaction (autoDream / consolidationPrompt)
│       ├── buddy/               # Tamagotchi companion (feature-flagged)
│       └── ...
```

---

## Installation

### Prerequisites

- Rust toolchain (stable, 1.75+): https://rustup.rs
- An Anthropic API key set as `ANTHROPIC_API_KEY`

### Build from Source

```bash
git clone https://github.com/Kuberwastaken/claurst
cd claurst/src-rust

# Default build
cargo build --release

# With optional features
cargo build --release --features buddy,proactive

# Run directly
cargo run --release -- --help
```

### Install Binary

```bash
cargo install --path src-rust/crates/cli
claurst --help
```

---

## Key CLI Commands

```bash
# Start interactive session
claurst

# Run a single prompt non-interactively
claurst -p "Refactor src/lib.rs to use async/await"

# Specify model
claurst --model claude-opus-4-6

# Enable verbose tool output
claurst --verbose

# Use a specific working directory
claurst --cwd /path/to/project

# Trigger ULTRAPLAN mode for complex tasks
claurst --ultraplan "Design the full architecture for a distributed cache"

# Show version
claurst --version
```

---

## Configuration

Configuration is resolved in this order (later entries override earlier):

1. `~/.claurst/config.toml` — global user config
2. `.claurst.toml` in the project root — project-level config
3. Environment variables — highest priority

### `~/.claurst/config.toml`

```toml
[api]
# Key is read from ANTHROPIC_API_KEY env var by default
model = "claude-opus-4-6"
max_tokens = 8192

[memory]
memory_dir = "~/.claurst/memory"
auto_dream = true
dream_interval_hours = 24
dream_session_threshold = 5

[tools]
allowed = ["bash", "read_file", "write_file", "search", "grep"]
bash_timeout_secs = 30

[kairos]
enabled = false          # Requires PROACTIVE feature flag at compile time
tick_interval_secs = 60
blocking_budget_secs = 15

[ultraplan]
enabled = true
poll_interval_secs = 3
max_duration_secs = 1800  # 30 minutes
model = "claude-opus-4-6"
```

### Environment Variables

```bash
export ANTHROPIC_API_KEY="sk-ant-..."          # Required
export CLAURST_MODEL="claude-sonnet-4-5"       # Override model
export CLAURST_MEMORY_DIR="$HOME/.claurst/mem" # Memory storage path
export CLAURST_LOG_LEVEL="debug"               # trace|debug|info|warn|error
export CLAURST_MAX_TOKENS="4096"               # Token budget
export CLAURST_BASH_TIMEOUT="60"               # Bash tool timeout
```

---

## Core Concepts

### Agent Loop

The main loop in `crates/assistant/` runs a read-eval-act cycle:

1. Receive user message
2. Build context (memory, tool results, conversation history)
3. Call Anthropic API
4. Parse tool calls from response
5. Execute tools, append results
6. Continue until no more tool calls or stop condition

### Tool System

Tools implement the `Tool` trait:

```rust
// crates/tools/src/lib.rs
use async_trait::async_trait;
use serde_json::Value;

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &'static str;
    fn description(&self) -> &'static str;
    fn input_schema(&self) -> Value;
    async fn execute(&self, input: Value) -> ToolResult;
}

#[derive(Debug)]
pub struct ToolResult {
    pub output: String,
    pub is_error: bool,
}
```

### Registering a Custom Tool

```rust
// crates/tools/src/custom_tool.rs
use async_trait::async_trait;
use serde_json::{json, Value};
use crate::{Tool, ToolResult};

pub struct MyCustomTool;

#[async_trait]
impl Tool for MyCustomTool {
    fn name(&self) -> &'static str { "my_custom_tool" }

    fn description(&self) -> &'static str {
        "Does something useful for the agent"
    }

    fn input_schema(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "target": {
                    "type": "string",
                    "description": "The target to operate on"
                }
            },
            "required": ["target"]
        })
    }

    async fn execute(&self, input: Value) -> ToolResult {
        let target = input["target"].as_str().unwrap_or("");
        ToolResult {
            output: format!("Processed: {}", target),
            is_error: false,
        }
    }
}

// Register in tool registry (crates/cli/src/main.rs)
registry.register(Box::new(MyCustomTool));
```

---

## Built-in Tools Reference

| Tool | Description |
|------|-------------|
| `bash` | Execute shell commands with timeout |
| `read_file` | Read file contents |
| `write_file` | Write or overwrite a file |
| `edit_file` | Apply targeted edits to a file |
| `list_dir` | List directory contents |
| `search_files` | Glob-based file search |
| `grep` | Regex search across files |
| `web_fetch` | Fetch a URL |
| `send_user_file` | Push file to user (KAIROS only) |
| `subscribe_pr` | Monitor pull request (KAIROS only) |

---

## Memory System (autoDream)

The dream system consolidates conversation memory in the background.

### Three-Gate Trigger

All three conditions must be true before a dream runs:

```rust
// Pseudo-representation of gate logic
fn should_dream(state: &DreamState) -> bool {
    let hours_since = state.last_dream.elapsed().as_secs() / 3600;
    let sessions_since = state.sessions_since_last_dream;
    let lock_available = state.consolidation_lock.try_acquire().is_ok();

    hours_since >= 24 && sessions_since >= 5 && lock_available
}
```

### Four Dream Phases

Defined in `crates/query/src/compact.rs`:

1. **Orient** — `ls` memory dir, read `MEMORY.md`, skim topic files
2. **Gather** — Pull recent session logs, extract key facts and decisions
3. **Synthesize** — Merge into structured topic files, resolve contradictions
4. **Commit** — Write updated files, release lock, record timestamp

### Memory Directory Layout

```
~/.claurst/memory/
├── MEMORY.md          # Top-level summary, always read first
├── topics/
│   ├── architecture.md
│   ├── preferences.md
│   └── projects.md
└── sessions/
    ├── 2026-03-31.log
    └── 2026-04-01.log
```

### Manually Trigger a Dream

```bash
claurst --dream-now
```

---

## BUDDY — Tamagotchi Companion (Feature Flag)

Build with `--features buddy` to enable.

```bash
cargo build --release --features buddy
```

Species is deterministically assigned per user via Mulberry32 PRNG seeded from `userId` hash + salt `friend-2026-401`. Same user always gets the same species.

```rust
// Mulberry32 PRNG (ported to Rust in crates/buddy/src/rng.rs)
fn mulberry32(seed: u32) -> impl FnMut() -> f64 {
    let mut s = seed;
    move || {
        s = s.wrapping_add(0x6D2B79F5);
        let mut t = (s ^ (s >> 15)).wrapping_mul(1u32.wrapping_add(s));
        t = (t ^ (t >> 7)).wrapping_mul(61u32.wrapping_ad