webxos/shadowclaw-c

Shadowclaw v3.4 (Testing)

<div style="max-width: 100%; overflow-x: auto; background: #f6f8fa; padding: 4px; border-radius: 4px;"> <pre style="font-family: 'Courier New', monospace; font-size: clamp(4px, 2vw, 10px); line-height: 1.2; margin: 0;"> ___ / __|| | _| | ___ ___| | _ \_ \| ' \ / ` |/ |/ _ \ \ /\ / / __| |/ _ \ \ /\ / / __) | | | | (| | (| | () \ V V / (_| | (| |\ V V / |___/|| ||\,|\_,|\__/ \/\/ \_||\_,| \/\/ </pre> </div>

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

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:

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:

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.

🛠️ Tools

Tools are invoked by the LLM during the “plan” phase. Each tool is described in the LLM prompt with its parameters and an example.

Security: The shell tool is compiled out by default. To enable it, add -DENABLE_SHELL_TOOL to CFLAGS and understand the risks.

Dynamic Skills

Skills are sequences of tool calls stored in the arena as BLOB_KIND_SKILL. Example creation:

{
  "name": "weather",
  "desc": "Get weather for a city",
  "steps": [
    {"tool": "http_get", "args": "https://wttr.in/{0}"},
    {"tool": "file_write", "args": "/tmp/weather.txt {result}"}
  ]
}

Placeholders supported:

• —{args} – the whole argument string passed to skill_run
• —{0}, {1}, … – positional arguments (split by spaces)
• —{result} – output of the previous step

Skills can also delegate to an external interpreter command (e.g., a Python script) via the optional interpreter_command field.

Soul File

All persistent memories are written to shadowclaw_data/shadowsoul.md in Markdown format. It contains:

• —## Core Memory – JSON key‑value store.
• —## Skills – list of registered skills (JSON).
• —## Cron Jobs – all scheduled jobs.
• —## Webhooks – registered webhooks.
• —## Conversation Log – user, assistant, tool calls, and results.

The file is updated every 5 writes (write‑behind) and immediately after important events.

⚙️ Configuration via Environment Variables

📁 Project Structure

shadowclaw/
├── shadowclaw.c          # Main program, arena, tools, cron, LLM
├── interpreter.c         # Local command interpreter (used in --no-llm mode)
├── interpreter.h         # Header for interpreter
├── cJSON.c / cJSON.h     # JSON library
├── Makefile              # Build instructions
├── start.sh              # Helper startup script (checks dependencies)
└── README.md             # This file

📄 License

MIT License.