zclaw – 888 KiB AI Personal Assistant for ESP32 (C/C++)
Introduction
zclaw is a minimal, all‑in‑firmware AI personal assistant that runs on ESP32‑based microcontrollers with a strict 888 KiB size envelope. The project is written in plain C and leverages ESP‑IDF and FreeRTOS, so it can be flashed to any ESP32‑C3, ESP32‑S3 or ESP32‑C6 board with little effort.
Why zclaw?
Typical on‑device LLM solutions require gigabytes of RAM or an external GPU. zclaw sidesteps those limitations by * shipping a small, single‑purpose LLM backend (Ollama, OpenAI, Anthropic, etc.) * using compact scheduling and GPIO APIs for simple “cron‑like” tasks * storing all credentials and configuration in ESP‑NVS with optional AES encryption * providing a Telegram chat interface and a lightweight web relay for browsers.
The result is an edge AI that runs off‑line in 850 KiB of flash and can answer natural‑language queries in real time.
Key Features
| Feature | Description |
|---|---|
| Tiny Footprint | 858 KiB default build, ≤ 888 KiB with secure configuration |
| Scheduling | Daily, periodic, and one‑shot tasks with timezone awareness |
| GPIO Control | Read / write with guardrails, bulk gpio_read_all() |
| Persisted State | Fast I/O to NVS so data survives reboots |
| Custom Tools | Register your own C functions as LLM plugins |
| Secure Mode | AES‑256 encryption for flash‑backed credentials |
| Chat Channels | Telegram bot + optional web‑relay UI |
| LLM Backends | Anthropic, OpenAI, OpenRouter, Ollama, or any custom endpoint |
| CLI Scripts | Bootstrap, install, provision, flash, monitor, and benchmark |
Prerequisites
- ESP‑IDF – Install the latest SDK following the official guide.
- Git – Clone the repo.
- Python 3.8+ – For the provisioning and testing scripts.
- Telegram Bot Token – (optional, for chat) or an HTTP LLM endpoint.
- Wi‑Fi Credentials – Network details to boot the device.
Getting Started in One Line
bash <(curl -fsSL https://raw.githubusercontent.com/tnm/zclaw/main/scripts/bootstrap.sh)
The bootstrap script will:
* Clone or pull the latest zclaw source.
* Run the non‑interactive install.sh that builds the firmware.
* Flash the build to the chosen board.
* Provision Wi‑Fi and LLM credentials.
If you already have a local clone, just use ./install.sh or ./install.sh -y for a dry‑run.
Flashing and Secure Provisioning
Secure mode protects your API keys and Wi‑Fi passwords using ESP‑NVS encryption.
# Flash with encryption and set a simple passphrase
./scripts/flash-secure.sh
After flashing, run ./scripts/provision.sh. The script will prompt for:
* Wi‑Fi SSID / password
* LLM provider name (e.g. ollama, openai)
* Provider endpoint and API key
* Optional Telegram bot token and chat ID
All values are stored hashed in flash. The --flash-mode secure flag ensures that any future upgrades also preserve encryption.
Running the Chat Service
Once provisioned, the device boots into Wi‑Fi and waits for a chat connection.
- Telegram – The bot will automatically forward received messages and return replies.
- Web Relay – Run
./scripts/web-relay.shfrom a host machine. It opens a short‑lived HTTPS endpoint that the ESP32 connects to. Open the given URL in a browser and chat in real time.
Both interfaces stream the LLM output live, so the experience feels near‑native.
Scheduling Tasks
zclaw’s scheduler feels like a lightweight cron.
int main() {
scheduler_register("");
// Schedule a daily ping at 3 AM
scheduler_schedule("3 * * * *", "ping_device");
}
The JSON‑formatted cron syntax is timezone‑aware and can trigger any registered zclaw tool or custom C function.
GPIO and Persistence
The GPIO API is safe‑guarded: every write can be limited to a range of pins, and the gpio_read_all() call returns a contiguous bitmap of pin states.
Persistent memory is exposed via a simple key‑value API in NVS:
nvs_set("user_pref", 42);
int val = nvs_get("user_pref");
Use this to store user profiles, last‑prompt times, or your own application state.
Extending zclaw with Custom Tools
zclaw ships with a small plugin system. To add a new tool:
1. Create a C function conforming to the zclaw_tool_t signature.
2. Edit main/config.h to register the tool.
3. Rebuild with ./scripts/build.sh.
The new tool can then be invoked from the chat interface by prefixing the prompt with tool: YourToolName.
Development Workflow
Typical development loop:
./scripts/test.sh host # Validate the host tests
./scripts/build.sh # Compile the firmware
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --write-template # Set up a local dev profile
./scripts/monitor.sh /dev/cu.usbmodem1101
The repo includes a full CI pipeline in .github/workflows/ that automatically builds, tests, and verifies each commit.
Contributing
All contributions are welcome!
* Fork, create a feature or bug‑fix branch.
* Ensure tests pass locally.
* Open a PR and reference the relevant issue.
* Licensing is MIT – a quick look at LICENSE will confirm.
If you find a security flaw, send a direct message to the maintainer or use the GitHub security reporting feature.
License & Credits
zclaw is released under the MIT license. The code is a collaborative effort from the open‑source community. Big thanks to the ESP‑IDF team, FreeRTOS contributors, and all users who tested on real hardware.
For more information visit the official documentation at https://zclaw.dev or the GitHub repo.