webxos/rustyclaw-rs

<div align="center"> <pre style="color: #CD7F32; font-size: 5pt; font-weight: bold; line-height: 1.2; margin: 0;">

██████╗ ██╗ ██╗███████╗████████╗██╗ ██╗ ██████╗██╗ █████╗ ██╗ ██╗ ██╔══██╗██║ ██║██╔════╝╚══██╔══╝╚██╗ ██╔╝██╔════╝██║ ██╔══██╗██║ ██║ ██████╔╝██║ ██║███████╗ ██║ ╚████╔╝ ██║ ██║ ███████║██║ █╗ ██║ ██╔══██╗██║ ██║╚════██║ ██║ ╚██╔╝ ██║ ██║ ██╔══██║██║███╗██║ ██║ ██║╚██████╔╝███████║ ██║ ██║ ╚██████╗███████╗██║ ██║╚███╔███╔╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝ ╚═╝ ╚═╝ ╚═════╝╚══════╝╚═╝ ╚═╝ ╚══╝╚══╝

</pre> </div>

🦞 RustyClaw 0.6.0 – Local Agent Harness

 

RustyClaw is a terminal‑based, minimal barebones and OEM local‑only agent harness powered by Ollama.

It combines a TUI chat interface, file system operations, Git versioning, memory consolidation, and a REST API – all inside a single Rust binary.

✨ Features

• —🧠 Persistent memory – bio.md evolves with every conversation.
• —🖥️ Full‑screen TUI – built with ratatui and crossterm.
• —🤖 Local Ollama – no data leaves your machine (supports any model).
• —📁 Sandboxed file ops – read/write files inside ~/.rustyclaw/data/.
• —🔐 Whitelisted shell commands – ls, cat, echo, git, pwd.
• —📦 Git versioning – every file change is auto‑committed (optional).
• —🧠 Memory consolidation – periodic summarisation of conversations into bio.md.
• —🌐 REST API – GET /api/bio to fetch the current bio.md.
• —🎨 Permanent ASCII logo – RustyClaw branding stays on screen.
• —⚡ Non‑blocking runtime – smooth TUI even while background tasks run.

File Structure

rustyclaw/
├── src/
│   └── main.rs                 # single‑file application
├── Cargo.toml                  # dependencies
├── start.sh                    # launcher script (build + run)
├── config.yaml                 # optional – auto‑created on first run
├── data/                       # sandboxed file storage (Git repo) - auto-created on first run

Note: ~/.rustyclaw/ is created automatically on first launch. The data/ folder inside it is initialised as a Git repository if git is available.

🛠️ Installation

1. Once you have the files downloaded run this bash command:

cd ~/rustyclaw              (The folder you have the files installed)
cargo build --release
./start.sh --rebuild

2. Install Ollama

curl -fsSL https://ollama.com/install.sh | sh
ollama serve &                 # start the server
ollama pull qwen2.5:0.5b      # pull a small model (or any you like)

3. Install Git (optional but recommended)

sudo apt install git          # Debian/Ubuntu
# or brew install git on macOS

Warning: The first build may take a few minutes. Subsequent runs will reuse the cached binary.

Configuration

On first launch, a default config.yaml is created in the current directory. You can edit it to change behaviour:

ollama_url: "http://localhost:11434"
ollama_model: "qwen2.5:0.5b"
api_port: 3030
root_dir: "/home/you/.rustyclaw"
bio_file: "/home/you/.rustyclaw/bio.md"
heartbeat_log: "/home/you/.rustyclaw/data/logs/heartbeat.log"
memory_sync_interval_secs: 3600   # consolidate every hour
max_log_lines: 200
git_auto_commit: true

bio.md – The Living Agent Memory

bio.md is a Markdown file that acts as the agent’s persistent long‑term memory. It is read on every chat and updated during /consolidate. The file is structured into five sections:

1. # BIO.MD – Living Agent Identity

• —Contains the last updated timestamp (auto‑refreshed after each chat).

2. ## SOUL

• —Core personality, values, constraints, and behavioural rules.
• —Example: “Stay sandboxed, respect security, be concise and helpful.”

3. ## SKILLS

• —Reusable capabilities and “how‑to” instructions.
• —Example: “Read/write local files, run whitelisted shell commands.”

4. ## MEMORY

• —Curated long‑term knowledge.
• —During /consolidate, the agent summarises recent conversations and appends a new entry here (e.g., ### Summary for 2025-04-02 14:30 …).

5. ## CONTEXT

• —Current runtime state (OS, working directory, active model).

6. ## SESSION TREE

• —Pointers or summaries of active conversation branches (currently a placeholder – can be extended).

You can edit `bio.md` manually – the agent will respect your changes in future chats.

Usage – TUI Commands

Launch the TUI with ./start.sh. All commands are typed at the bottom input line and sent with Enter.

Any text not starting with `/` is sent as a chat message to the AI.

REST API

While the TUI is running, a simple HTTP server listens on http://127.0.0.1:3030.

• —GET /health → {"status":"ok"}
• —GET /api/bio → returns the current bio.md as JSON:

  {"bio": "# BIO.MD – Living Agent Identity\n**Last Updated:** ..."}

You can use curl to fetch the agent’s memory:

curl http://127.0.0.1:3030/api/bio

How Memory Consolidation Works

1. 1.Every chat interaction is logged as a JSON line in ~/.rustyclaw/data/logs/heartbeat.log.
2. 2.Periodically (default every 3600 seconds), the agent reads the last 20 entries.
3. 3.It sends a summarisation prompt to Ollama.
4. 4.The summary is inserted into the ## MEMORY section of bio.md with a timestamp.
5. 5.The agent’s future chats include the updated bio.md, giving it long‑term recall.

You can also trigger consolidation manually with /consolidate.

Tool Functions Explained

The core of RustyClaw is the run_command dispatcher in main.rs. Each command is handled in a non‑blocking worker task.

All file operations are sandboxed – the sanitize_path function ensures no path can escape ~/.rustyclaw/data/.

📜 License

MIT License