██████╗ ██╗ ██╗███████╗████████╗██╗ ██╗ ██████╗██╗ █████╗ ██╗ ██╗
██╔══██╗██║ ██║██╔════╝╚══██╔══╝╚██╗ ██╔╝██╔════╝██║ ██╔══██╗██║ ██║
██████╔╝██║ ██║███████╗ ██║ ╚████╔╝ ██║ ██║ ███████║██║ █╗ ██║
██╔══██╗██║ ██║╚════██║ ██║ ╚██╔╝ ██║ ██║ ██╔══██║██║███╗██║
██║ ██║╚██████╔╝███████║ ██║ ██║ ╚██████╗███████╗██║ ██║╚███╔███╔╝
╚═╝ ╚═╝ ╚═════╝ ╚══════╝ ╚═╝ ╚═╝ ╚═════╝╚══════╝╚═╝ ╚═╝ ╚══╝╚══╝
# 🦞 RustyClaw 0.6.0 – Local Agent Harness
[](https://www.rust-lang.org/)
[](https://opensource.org/licenses/MIT)
**RustyClaw** is a terminal‑based, minimal barebones and OEM local‑only agent harness powered by [Ollama](https://ollama.com/).
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:
```bash
cd ~/rustyclaw (The folder you have the files installed)
cargo build --release
./start.sh --rebuild
```
### 2. Install Ollama
```bash
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)
```bash
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:
```yaml
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
```
| Field | Description |
|----------------------------|-----------------------------------------------------------------------------|
| `ollama_url` | Ollama API endpoint (default `http://localhost:11434`) |
| `ollama_model` | Model to use for chat and consolidation |
| `api_port` | Port for the REST API |
| `root_dir` | Where `bio.md` and `data/` live (default `~/.rustyclaw`) |
| `git_auto_commit` | Automatically commit file writes in the `data/` folder |
| `memory_sync_interval_secs`| How often to run automatic memory consolidation |
---
## `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**.
| Command | Description |
|---------|-------------|
| `/help` | Show all commands |
| `/bio` | Display the current `bio.md` content |
| `/consolidate` | Force memory consolidation (summarises recent chats into `## MEMORY`) |
| `/write_file