README

zclaw

The smallest possible AI personal assistant for ESP32.

zclaw is written in C and runs on ESP32 boards with a strict firmware budget target of <= 888 KiB on the default build. It supports scheduled tasks, GPIO control, persistent memory, and custom tool composition through natural language.

The 888 KiB target is all-in firmware size, not just app logic. It includes zclaw code plus ESP-IDF/FreeRTOS runtime, Wi-Fi/networking, TLS/crypto, and cert bundle overhead.

Fun to use, fun to hack on.

Lobster soldering a Seeed Studio XIAO ESP32-C3

Current default esp32s3 breakdown (idf.py -B build size-components, flash totals):

Layer	Size	Share
zclaw app logic (`libmain.a`)	26,430 bytes (~25.8 KiB)	~3.1%
Wi-Fi + networking stack	375,278 bytes (~366.5 KiB)	~43.7%
TLS/crypto stack	125,701 bytes (~122.8 KiB)	~14.7%
Cert bundle + app metadata	92,654 bytes (~90.5 KiB)	~10.8%
Other ESP-IDF/runtime/drivers/libc	237,889 bytes (~232.3 KiB)	~27.7%

zclaw.bin from the same build is 865,888 bytes (~845.6 KiB), under the 888 KiB cap.

Full Documentation

Quick Start

One-line bootstrap (macOS/Linux):

bash <(curl -fsSL https://raw.githubusercontent.com/tnm/zclaw/main/scripts/bootstrap.sh)

Optional checksum-verified bootstrap (same flow):

ZCLAW_BOOTSTRAP_SHA256="<sha256-from-release-notes>" \
bash <(curl -fsSL https://raw.githubusercontent.com/tnm/zclaw/main/scripts/bootstrap.sh)

Already cloned?

./install.sh

Non-interactive install:

./install.sh -y

Important setup notes:

bootstrap.sh clones/updates the repo and then runs ./install.sh. You can inspect/verify the bootstrap flow first (including ZCLAW_BOOTSTRAP_SHA256 integrity checks); see Getting Started.
For encrypted credentials in flash, use secure mode (--flash-mode secure in install flow, or ./scripts/flash-secure.sh directly).
After flashing, provision WiFi + LLM credentials with ./scripts/provision.sh.
Telegram control commands: /start and /help show help, /settings shows bot status, /stop pauses message intake, /resume re-enables message intake.
If serial port is busy, run ./scripts/release-port.sh and retry.
Full setup/provisioning details are in the docs site index.

Highlights

Chat via Telegram or hosted web relay
Timezone-aware schedules (daily, periodic, and one-shot once)
Built-in + user-defined tools
GPIO read/write control with guardrails
Persistent memory across reboots
Provider support for Anthropic, OpenAI, and OpenRouter

Hardware

Tested targets: ESP32-C3, ESP32-S3, and ESP32-C6. Other ESP32 variants should work fine (some may require manual ESP-IDF target setup).

Recommended starter board: Seeed XIAO ESP32-C3

Useful Scripts

Script	Purpose
`./scripts/build.sh`	Build firmware
`./scripts/flash.sh`	Flash firmware
`./scripts/flash-secure.sh`	Flash with encryption
`./scripts/provision.sh`	Provision credentials to NVS
`./scripts/monitor.sh`	Serial monitor
`./scripts/emulate.sh`	Run QEMU profile
`./scripts/web-relay.sh`	Hosted relay + mobile chat UI
`./scripts/docs-site.sh`	Serve docs site locally
`./scripts/test.sh`	Run host/device test flows

License

MIT