____ _ _ _
/ ___|| |__ __ _ __| | _____ _____| | __ ___ __
\___ \| '_ \ / _` |/ _` |/ _ \ \ /\ / / __| |/ _` \ \ /\ / /
___) | | | | (_| | (_| | (_) \ V V / (__| | (_| |\ V V /
|____/|_| |_|\__,_|\__,_|\___/ \_/\_/ \___|_|\__,_| \_/\_/
**Shadowclaw** is a minimal, single‑binary agent harness written in C. It follows the *OpenClaw* philosophy: self‑hosted, tool‑using, persistent memory, and minimal dependencies. The core memory management uses **Tsoding's "shadow header" trick** (like `stb_ds` but for a growable arena). All data (conversation history, tool definitions, results) lives inside a single `realloc`‑ed memory block with a hidden header. The agent communicates with a local LLM (Ollama) via curl, can execute shell commands, read/write files, perform HTTP GET, and evaluate simple math expressions. State is automatically saved to disk after every interaction.
**Niche edge use cases:**
RPi Zero/IoT: offline sensor scripts (shell + persistent shadow.bin)
Air-gapped systems: USB-stick local LLM agent (file/HTTP/math)
Embedded routers: 100-200KB network automation (low-mem Linux)
Low-power edge nodes: self-hosted persistent AI, no cloud.
---
## Features
- **🧠 Local LLM integration** – works with any Ollama model (default: `tinyllama:1.1b`).
- **🔧 Built‑in tools** – `file_read`, `file_write`, `http_get`, `math`, `list_dir`, `shell` (disabled by default), and more.
- **⏰ Cron jobs** – schedule recurring tasks using `@every N[s/m/h]`, `@hourly`, `@daily`, `@weekly`.
- **🌐 Webhooks** – trigger HTTP POST calls on tool execution or cron events.
- **🎓 Dynamic skills** – create reusable multi‑step workflows without recompiling.
- **💾 Core memory** – persistent key‑value storage (JSON) that survives across sessions.
- **📜 Soul file** – Markdown export of all memories (conversation, skills, crons, webhooks, core memory).
- **🎨 Colored TUI** – optional GNU readline support for line editing and history.
- **⚡ Thread‑safe** – cron jobs run in a separate thread, tool calls are queued.
- **🛡️ Security** – path sandboxing, domain allowlist, shell opt‑in, dry‑run mode.
---
## 📦 Requirements
- **Linux / macOS / WSL** (tested on Ubuntu 22.04, Kali)
- **Ollama** (running locally) – optional, the agent can run in `--no-llm` mode
- **Dependencies**:
- `libcurl` (HTTP requests)
- `libpthread` (threading)
- `libreadline` (optional, for TUI enhancements)
- `gcc` or `clang` with C99 support
---
## Installation + Launch
*Put all files into a single folder on your system*
```bash
cd ~/shadowclaw (The folder you put the files in)
make clean && make
./start.sh
```
## Setup your local Ollama model
*Shadowclaw is set to use qwen2.5:0.5b as a default, to change this:*
Find line 633 in the shadowclaw.c file:
```bash
static const char *ollama_endpoint = "http://localhost:11434";
static const char *ollama_model = "qwen2.5:0.5b"; (Change this to desired model)
static long llm_connect_timeout = 15;
```
Also line 16 in the start.sh file:
```bash
OLLAMA_ENDPOINT="${OLLAMA_ENDPOINT:-http://localhost:11434}"
OLLAMA_MODEL="${OLLAMA_MODEL:-qwen2.5:0.5b}" (Change this to desired model)
```
---
### First start
- The agent creates `shadowclaw.bin` (binary state) and a folder `shadowclaw_data/` containing `shadowsoul.md`.
- If Ollama is not reachable, it automatically falls back to `--no-llm` mode.
- A default heartbeat cron job (`@every 120s`) is added automatically to keep the soul file updated.
---
## Interactive Commands
Shadowclaw understands both natural language (sent to the LLM) and slash commands.
| Command | Description |
|---------|-------------|
| `/help` | Show help and list all commands. |
| `/tools` | List available built‑in tools. |
| `/state` | Show arena memory usage and soul file stats. |
| `/clear` | Erase conversation history (keeps system prompt and core memory). |
| `/exit` | Quit the agent. |
| `/loop