zclaw

The smallest possible AI personal assistant for ESP32.

zclaw is written in C and runs on ESP32 boards with a strict all-in 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 cap is all-in firmware size, not just app code. It includes zclaw logic plus ESP-IDF/FreeRTOS runtime, Wi-Fi/networking, TLS/crypto, and cert bundle overhead.

Fun to use, fun to hack on.

Full Documentation

Use the docs site for complete guides and reference.

• Full documentation
• Local Admin Console
• Use cases: useful + fun
• Changelog (web)
• Complete README (verbatim)

Quick Start

One-line bootstrap (macOS/Linux):

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

Already cloned?

./install.sh

Non-interactive install:

./install.sh -y

Highlights

• Chat via Telegram or hosted web relay
• Timezone-aware schedules (daily, periodic, and one-shot once)
• Built-in + user-defined tools
• For brand-new built-in capabilities, add a firmware tool (C handler + registry entry) via the Build Your Own Tool docs.
• Runtime diagnostics via get_diagnostics (quick/runtime/memory/rates/time/all scopes)
• GPIO, DHT, and I2C control with guardrails (including gpio_read_all, i2c_scan, i2c_read/i2c_write, and dht_read)
• USB local admin console for recovery, safe mode, and pre-network bring-up
• Persistent memory across reboots
• Persona options: neutral, friendly, technical, witty

Hardware

Tested targets: ESP32, ESP32-C3, ESP32-S3, and ESP32-C6. Classic ESP32-WROOM/ESP32 DevKit boards are supported. Test reports for other ESP32 variants are very welcome!

Recommended starter board: Seeed XIAO ESP32-C3

Local Dev & Hacking

Typical fast loop:

./scripts/test.sh host
./scripts/build.sh
./scripts/flash.sh --kill-monitor /dev/cu.usbmodem1101
./scripts/provision-dev.sh --port /dev/cu.usbmodem1101
./scripts/monitor.sh /dev/cu.usbmodem1101

Profile setup once, then re-use:

./scripts/provision-dev.sh --write-template
# edit ~/.config/zclaw/dev.env
./scripts/provision-dev.sh --show-config
./scripts/provision-dev.sh

# if Telegram keeps replaying stale updates:
./scripts/telegram-clear-backlog.sh --show-config

More details in the Local Dev & Hacking guide.

Other Useful Scripts

Local Admin Console

When the board is in safe mode, unprovisioned, or the LLM path is unavailable, you can still operate it over USB serial without Wi-Fi or an LLM round trip.

./scripts/monitor.sh /dev/cu.usbmodem1101
# then type:
/wifi status
/wifi scan
/bootcount
/gpio all
/reboot

Available local-only commands:

• /gpio [all|pin|pin high|pin low]
• /diag [scope] [verbose]
• /reboot
• /wifi [status|scan]
• /bootcount
• /factory-reset confirm (destructive; wipes NVS and reboots)

Full reference: Local Admin Console

Size Breakdown

Current default esp32 breakdown (grouped image bytes from idf.py -B build size-components):

Total image size from this build is 853034 bytes; padded zclaw.bin is 853184 bytes (~833.2 KiB), leaving 56128 bytes (~54.8 KiB) under the 888 KiB cap.

Latency Benchmarking

Relay path benchmark (includes web relay processing + device round trip):

./scripts/benchmark.sh --mode relay --count 20 --message "ping"

Direct serial benchmark (host round trip + first response time). If firmware logs METRIC request ... lines, the report also includes device-side timing:

./scripts/benchmark.sh --mode serial --serial-port /dev/cu.usbmodem1101 --count 20 --message "ping"

License

MIT