claurst-claude-code-rust

---
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

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

---

Key CLI Commands

# 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

[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

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:

// 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

// 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:

// 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

claurst --dream-now

---

BUDDY — Tamagotchi Companion (Feature Flag)

Build with --features buddy to enable.

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.

// 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_add(t)) ^ t;
        ((t ^ (t >> 14)) as f64) / 4294967296.0
    }
}

Species Rarity Table

Rarity	Chance	Species
Common	60%	Pebblecrab, Dustbunny, Mossfrog, Twigling, Dewdrop, Puddlefish
Uncommon	25%	Cloudferret, Gustowl, Bramblebear, Thornfox
Rare	10%	Crystaldrake, Deepstag, Lavapup
Epic	4%	Stormwyrm, Voidcat, Aetherling
Legendary	1%	Cosmoshale, Nebulynx

Shiny chance: independent 1%. Shiny Legendary = 0.01%.

---

ULTRAPLAN — Remote 30-Minute Planning

For complex architectural tasks, ULTRAPLAN offloads planning to a remote Cloud Container Runtime (CCR) session:

claurst --ultraplan "Design a horizontally scalable job queue with exactly-once delivery"

Flow:

1. Task sent to remote CCR running tengu_ultraplan_model (Opus 4.6)
2. Local terminal polls every 3 seconds
3. Browser UI opens for live monitoring and approval
4. On approval, __ULTRAPLAN_TELEPORT_LOCAL__ sentinel returns result to terminal

Configure timeout and poll interval in config.toml:

[ultraplan]
poll_interval_secs = 3
max_duration_secs = 1800

---

KAIROS — Proactive Mode (Feature Flag)

Build with --features proactive:

cargo build --release --features proactive
claurst --kairos

KAIROS maintains append-only daily logs and receives <tick> prompts on an interval to decide whether to act proactively. Actions taking >15 seconds are deferred.

[kairos]
enabled = true
tick_interval_secs = 60
blocking_budget_secs = 15

---

Multi-Agent Orchestration

Spawn subagents from within a tool or agent context:

use claurst_assistant::{Agent, AgentConfig, Message};

let subagent = Agent::new(AgentConfig {
    model: "claude-sonnet-4-5".into(),
    system_prompt: "You are a focused code reviewer.".into(),
    tools: vec!["read_file", "grep"],
    max_tokens: 2048,
    ..Default::default()
});

let result = subagent
    .run(vec![Message::user("Review src/lib.rs for unsafe blocks")])
    .await?;

println!("{}", result.final_response());

---

Common Patterns

Non-Interactive Scripting

#!/usr/bin/env bash
# Run claurst headlessly in CI
export ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"

claurst -p "Run the test suite and summarize failures" \
  --no-interactive \
  --output-format json \
  > results.json

Piping Context

# Feed file contents as context
cat src/main.rs | claurst -p "Explain this code and suggest improvements"

# Pipe git diff for review
git diff HEAD~1 | claurst -p "Review this diff for bugs"

Custom System Prompt

claurst --system "You are an expert in embedded Rust. Always prefer no_std solutions." \
  -p "Implement a ring buffer for a bare-metal target"

---

Troubleshooting

API Key Not Found

Error: ANTHROPIC_API_KEY not set

export ANTHROPIC_API_KEY="sk-ant-..."
# Or add to ~/.claurst/config.toml under [api]

Bash Tool Timeout

ToolError: bash execution exceeded 30s timeout

Increase timeout:

[tools]
bash_timeout_secs = 120

Or per-invocation:

claurst --bash-timeout 120 -p "Run the full integration test suite"

Dream Not Running

Check that all three gates are satisfied:

• 24h have passed since last dream
• 5+ sessions since last dream
• No concurrent dream is running (check for stale lock: ~/.claurst/memory/.dream.lock)

Force a dream manually:

claurst --dream-now
rm ~/.claurst/memory/.dream.lock  # If lock is stale

Build Errors with Feature Flags

error[E0432]: unresolved import `claurst_buddy`

Feature flags must be passed consistently:

cargo build --features buddy,proactive
# Not just: cargo build

Memory Growing Too Large

# Inspect memory directory size
du -sh ~/.claurst/memory/

# Manually compact (triggers dream immediately)
claurst --dream-now --verbose

---

Spec-Driven Development

To contribute or extend claurst, follow the two-phase clean-room process:

1. Spec phase (spec/): Write behavioral specifications — inputs, outputs, tool contracts, data flows. No implementation details.
2. Implementation phase (src-rust/): Implement from spec alone. Never reference external proprietary source.

This mirrors the Phoenix Technologies v. IBM (1984) clean-room BIOS precedent.

---

Resources

• Repository: https://github.com/Kuberwastaken/claurst
• Blog breakdown: https://kuber.studio/blog/AI/Claude-Code's-Entire-Source-Code-Got-Leaked-via-a-Sourcemap-in-npm,-Let's-Talk-About-it
• Spec directory: spec/ — full behavioral specifications
• Anthropic API docs: https://docs.anthropic.com