zclaw docs
chapter 0
zclaw is an ESP32-resident AI agent written in C. It runs as a practical assistant over Telegram or host relay, with scheduling, GPIO control, memory, and a tight firmware budget.
You send plain language, zclaw maps to tool calls, firmware executes on silicon.
You: In 20 minutes, check the garage sensor Agent: Created schedule #7: once in 20 min -> check the garage sensor
The 888 KiB target is an all-in firmware cap, not just zclaw application logic. It includes app code plus ESP-IDF/FreeRTOS runtime, Wi-Fi/networking, TLS/crypto, and cert bundle overhead.
Current default esp32s3 build (grouped loadable image bytes from idf.py -B build size-components; rows sum to total image size):
| Layer | Size | Share |
|---|---|---|
zclaw app logic (libmain.a) | 35,742 bytes (~34.9 KiB) | ~4.1% |
| Wi-Fi + networking stack | 397,356 bytes (~388.0 KiB) | ~45.7% |
| TLS/crypto stack | 112,922 bytes (~110.3 KiB) | ~13.0% |
| Cert bundle + app metadata | 99,722 bytes (~97.4 KiB) | ~11.5% |
| Other ESP-IDF/runtime/drivers/libc | 224,096 bytes (~218.8 KiB) | ~25.8% |
Total image size from this build is 869,838 bytes; padded zclaw.bin is 869,952 bytes (~849.6 KiB), under the 888 KiB cap.
Chapter 1 · Getting Started Bootstrap install, flash, provision, and first successful boot. Chapter 2 · Tool Surface Current built-in tools and scheduling behavior, including one-shot jobs. Chapter 3 · Runtime Anatomy Task model, queues, LLM path, and practical constraints. Chapter 4 · Security & Ops Safety defaults, flash encryption, and production handling guidance. Chapter 5 · Build Your Own Tool Design, create, validate, and maintain custom natural-language tools. Chapter 6 · Local Dev & Hacking Practical local iteration loops, provisioning profiles, and debug workflows. Chapter 7 · Use Cases Useful and playful ideas that are only practical when the assistant lives on your device. Chapter 8 · Changelog Release notes and a timeline of what changed across versions.