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 tasksGPIO controlpersistent memoryand custom tool composition through natural language.

The 888 KiB cap is all-in firmware sizenot just app code. It includes zclaw logic plus ESP-IDF/FreeRTOS runtimeWi-Fi/networkingTLS/cryptoand cert bundle overhead.

Fun to usefun to hack on.

Use the docs site for complete guides and reference.

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

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

• Chat via Telegram or hosted web relay
• Timezone-aware schedules (dailyperiodicand one-shot once)
• Built-in + user-defined tools
• For brand-new built-in capabilitiesadd 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 read/write control with guardrails (including bulk gpio_read_all)
• USB local admin console for recoverysafe modeand pre-network bring-up
• Persistent memory across reboots
• Persona options: neutralfriendlytechnicalwitty
• Provider support for AnthropicOpenAIOpenRouterand Ollama (custom endpoint)

Tested targets: ESP32ESP32-C3ESP32-S3and 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

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 oncethen 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.

When the board is in safe modeunprovisionedor the LLM path is unavailableyou 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

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.

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 ... linesthe report also includes device-side timing:

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

MIT