[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74699":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":15,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":22,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":16,"starSnapshotCount":16,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},74699,"zclaw","tnm\u002Fzclaw","tnm","Your personal AI assistant at all-in 888KiB (~35KB in app code). Running on an ESP32. GPIO, cron, custom tools, memory, and more.","https:\u002F\u002Fzclaw.dev",null,"C",2159,183,16,7,0,3,33,9,71.59,"MIT License",false,"main",[],"2026-06-12 04:01:15","# zclaw\n\n\u003Cimg\n  src=\"docs\u002Fimages\u002Flobster_xiao_cropped_left.png\"\n  alt=\"Lobster soldering a Seeed Studio XIAO ESP32-C3\"\n  height=\"200\"\n  align=\"right\"\n\u002F>\n\nThe smallest possible AI personal assistant for ESP32.\n\nzclaw is written in C and runs on ESP32 boards with a strict all-in firmware budget target of **\u003C= 888 KiB** on the default build. It supports scheduled tasks, GPIO control, persistent memory, and custom tool composition through natural language.\n\nThe **888 KiB** cap is all-in firmware size, not just app code.\nIt includes `zclaw` logic plus ESP-IDF\u002FFreeRTOS runtime, Wi-Fi\u002Fnetworking, TLS\u002Fcrypto, and cert bundle overhead.\n\nFun to use, fun to hack on.\n\u003Cbr clear=\"right\" \u002F>\n\n## Full Documentation\n\nUse the docs site for complete guides and reference.\n\n- [Full documentation](https:\u002F\u002Fzclaw.dev)\n- [Local Admin Console](https:\u002F\u002Fzclaw.dev\u002Flocal-admin.html)\n- [Use cases: useful + fun](https:\u002F\u002Fzclaw.dev\u002Fuse-cases.html)\n- [Changelog (web)](https:\u002F\u002Fzclaw.dev\u002Fchangelog.html)\n- [Complete README (verbatim)](https:\u002F\u002Fzclaw.dev\u002Freference\u002FREADME_COMPLETE.md)\n\n\n## Quick Start\n\nOne-line bootstrap (macOS\u002FLinux):\n\n```bash\nbash \u003C(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Ftnm\u002Fzclaw\u002Fmain\u002Fscripts\u002Fbootstrap.sh)\n```\n\nAlready cloned?\n\n```bash\n.\u002Finstall.sh\n```\n\nNon-interactive install:\n\n```bash\n.\u002Finstall.sh -y\n```\n\n\u003Cdetails>\n\u003Csummary>Setup notes\u003C\u002Fsummary>\n\n- `bootstrap.sh` clones\u002Fupdates the repo and then runs `.\u002Finstall.sh`. You can inspect\u002Fverify the bootstrap flow first (including `ZCLAW_BOOTSTRAP_SHA256` integrity checks); see the [Getting Started docs](https:\u002F\u002Fzclaw.dev\u002Fgetting-started.html).\n- Linux dependency installs auto-detect `apt-get`, `pacman`, `dnf`, or `zypper` during `install.sh` runs.\n- In non-interactive mode, unanswered install prompts default to `no` unless you pass `-y` (or saved preferences\u002Fexplicit flags apply).\n- For encrypted credentials in flash, use secure mode (`--flash-mode secure` in install flow, or `.\u002Fscripts\u002Fflash-secure.sh` directly).\n- After flashing, provision WiFi + LLM credentials with `.\u002Fscripts\u002Fprovision.sh`.\n- You can re-run either `.\u002Fscripts\u002Fprovision.sh` or `.\u002Fscripts\u002Fprovision-dev.sh` at any time (no reflash required) to update runtime credentials: WiFi SSID\u002Fpassword, LLM backend\u002Fmodel\u002FAPI key (or Ollama API URL), and Telegram token\u002Fchat ID allowlist.\n- Default LLM rate limits are `100\u002Fhour` and `1000\u002Fday`; change compile-time limits in `main\u002Fconfig.h` (`RATELIMIT_*`).\n- Quick validation path: run `.\u002Fscripts\u002Fweb-relay.sh` and send a test message to confirm the device can answer.\n- If serial port is busy, run `.\u002Fscripts\u002Frelease-port.sh` and retry.\n- For repeat local reprovisioning without retyping secrets, use `.\u002Fscripts\u002Fprovision-dev.sh` with a local profile file (`provision-dev.sh` wraps `provision.sh --yes`).\n\n\u003C\u002Fdetails>\n\n## Highlights\n\n- Chat via Telegram or hosted web relay\n- Timezone-aware schedules (`daily`, `periodic`, and one-shot `once`)\n- Built-in + user-defined tools\n- For brand-new built-in capabilities, add a firmware tool (C handler + registry entry) via the Build Your Own Tool docs.\n- Runtime diagnostics via `get_diagnostics` (quick\u002Fruntime\u002Fmemory\u002Frates\u002Ftime\u002Fall scopes)\n- GPIO, DHT, and I2C control with guardrails (including `gpio_read_all`, `i2c_scan`, `i2c_read`\u002F`i2c_write`, and `dht_read`)\n- USB local admin console for recovery, safe mode, and pre-network bring-up\n- Persistent memory across reboots\n- Persona options: `neutral`, `friendly`, `technical`, `witty`\n- Provider support for Anthropic, OpenAI, OpenRouter, and Ollama (custom endpoint)\n\n## Hardware\n\nTested targets: **ESP32**, **ESP32-C3**, **ESP32-S3**, and **ESP32-C6**.\nClassic **ESP32-WROOM\u002FESP32 DevKit** boards are supported.\nTest reports for other ESP32 variants are very welcome!\n\nRecommended starter board: [Seeed XIAO ESP32-C3](https:\u002F\u002Fwww.seeedstudio.com\u002FSeeed-XIAO-ESP32C3-p-5431.html)\n\n## Local Dev & Hacking\n\nTypical fast loop:\n\n```bash\n.\u002Fscripts\u002Ftest.sh host\n.\u002Fscripts\u002Fbuild.sh\n.\u002Fscripts\u002Fflash.sh --kill-monitor \u002Fdev\u002Fcu.usbmodem1101\n.\u002Fscripts\u002Fprovision-dev.sh --port \u002Fdev\u002Fcu.usbmodem1101\n.\u002Fscripts\u002Fmonitor.sh \u002Fdev\u002Fcu.usbmodem1101\n```\n\nProfile setup once, then re-use:\n\n```bash\n.\u002Fscripts\u002Fprovision-dev.sh --write-template\n# edit ~\u002F.config\u002Fzclaw\u002Fdev.env\n.\u002Fscripts\u002Fprovision-dev.sh --show-config\n.\u002Fscripts\u002Fprovision-dev.sh\n\n# if Telegram keeps replaying stale updates:\n.\u002Fscripts\u002Ftelegram-clear-backlog.sh --show-config\n```\n\nMore details in the [Local Dev & Hacking guide](https:\u002F\u002Fzclaw.dev\u002Flocal-dev.html).\n\n### Other Useful Scripts\n\n\u003Cdetails>\n\u003Csummary>Show scripts\u003C\u002Fsummary>\n\n- `.\u002Fscripts\u002Fflash-secure.sh` - Flash with encryption\n- `.\u002Fscripts\u002Fprovision.sh` - Provision credentials to NVS\n- `.\u002Fscripts\u002Fprovision-dev.sh` - Local profile wrapper for repeat provisioning\n- `.\u002Fscripts\u002Ftelegram-clear-backlog.sh` - Clear queued Telegram updates\n- `.\u002Fscripts\u002Ferase.sh` - Erase NVS only (`--nvs`) or full flash (`--all`) with guardrails\n- `.\u002Fscripts\u002Fmonitor.sh` - Serial monitor\n- `.\u002Fscripts\u002Femulate.sh` - Run QEMU profile\n- `.\u002Fscripts\u002Fweb-relay.sh` - Hosted relay + mobile chat UI\n- `.\u002Fscripts\u002Fbenchmark.sh` - Benchmark relay\u002Fserial latency\n- `.\u002Fscripts\u002Ftest.sh` - Run host\u002Fdevice test flows\n- `.\u002Fscripts\u002Ftest-api.sh` - Run live provider API checks (manual\u002Flocal)\n\n\u003C\u002Fdetails>\n\n## Local Admin Console\n\nWhen 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.\n\n```bash\n.\u002Fscripts\u002Fmonitor.sh \u002Fdev\u002Fcu.usbmodem1101\n# then type:\n\u002Fwifi status\n\u002Fwifi scan\n\u002Fbootcount\n\u002Fgpio all\n\u002Freboot\n```\n\nAvailable local-only commands:\n\n- `\u002Fgpio [all|pin|pin high|pin low]`\n- `\u002Fdiag [scope] [verbose]`\n- `\u002Freboot`\n- `\u002Fwifi [status|scan]`\n- `\u002Fbootcount`\n- `\u002Ffactory-reset confirm` (destructive; wipes NVS and reboots)\n\nFull reference: [Local Admin Console](https:\u002F\u002Fzclaw.dev\u002Flocal-admin.html)\n\n## Size Breakdown\n\nCurrent default `esp32` breakdown (grouped image bytes from `idf.py -B build size-components`):\n\n| Segment | Bytes | Size | Share |\n| --- | ---: | ---: | ---: |\n| zclaw app logic (`libmain.a`) | `39276` | ~38.4 KiB | ~4.6% |\n| Wi-Fi + networking stack | `378624` | ~369.8 KiB | ~44.4% |\n| TLS\u002Fcrypto stack | `134923` | ~131.8 KiB | ~15.8% |\n| cert bundle + app metadata | `98425` | ~96.1 KiB | ~11.5% |\n| other ESP-IDF\u002Fruntime\u002Fdrivers\u002Flibc | `201786` | ~197.1 KiB | ~23.7% |\n\nTotal 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.\n\n## Latency Benchmarking\n\nRelay path benchmark (includes web relay processing + device round trip):\n\n```bash\n.\u002Fscripts\u002Fbenchmark.sh --mode relay --count 20 --message \"ping\"\n```\n\nDirect serial benchmark (host round trip + first response time). If firmware logs\n`METRIC request ...` lines, the report also includes device-side timing:\n\n```bash\n.\u002Fscripts\u002Fbenchmark.sh --mode serial --serial-port \u002Fdev\u002Fcu.usbmodem1101 --count 20 --message \"ping\"\n```\n\n## License\n\nMIT\n","zclaw 是一个专为ESP32设计的最小化个人AI助手，整个固件大小严格控制在888KiB以内。它支持定时任务、GPIO控制、持久内存以及通过自然语言处理自定义工具组合。项目使用C语言编写，结合了ESP-IDF\u002FFreeRTOS运行环境，Wi-Fi\u002F网络连接，TLS\u002F加密等功能，并且所有这些都在极其有限的空间内实现。zclaw适合需要轻量级智能控制的应用场景，如智能家居设备或小型物联网项目，既便于用户操作也方便开发者进行二次开发。",2,"2026-06-11 03:50:28","high_star"]