Skip to content
Back to search

mimiclaw

MimiClaw: Personal Agent on a $5 chip. No OS(Linux). No Node.js. No Mac mini. No Raspberry Pi. No VPS. Hardware agents OS.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/memovai--mimiclaw/badge.svg)](/listings/memovai--mimiclaw)

HTML

<a href="/listings/memovai--mimiclaw"><img src="/api/listings/memovai--mimiclaw/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

What You Need

- An **ESP32-S3 dev board** with 16 MB flash and 8 MB PSRAM (e.g. Xiaozhi AI board, ~$10) - A **USB Type-C cable** - A **Telegram bot token** — talk to [@BotFather](https://t.me/BotFather) on Telegram to create one - An **Anthropic API key** — from [console.anthropic.com](https://console.anthropic.com), or an **OpenAI API key** — from [platform.openai.com](https://platform.openai.com)

Install

# You need ESP-IDF v5.5+ installed first:
# https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/

git clone https://github.com/memovai/mimiclaw.git
cd mimiclaw

idf.py set-target esp32s3

<details> <summary>Ubuntu Install</summary>

Recommended baseline:

- Ubuntu 22.04/24.04 - Python >= 3.10 - CMake >= 3.16 - Ninja >= 1.10 - Git >= 2.34 - flex >= 2.6 - bison >= 3.8 - gperf >= 3.1 - dfu-util >= 0.11 - `libusb-1.0-0`, `libffi-dev`, `libssl-dev`

Install and build on Ubuntu:

sudo apt-get update
sudo apt-get install -y git wget flex bison gperf python3 python3-pip python3-venv \
  cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

./scripts/setup_idf_ubuntu.sh
./scripts/build_ubuntu.sh

</details>

<details> <summary>macOS Install</summary>

Recommended baseline:

- macOS 12/13/14 - Xcode Command Line Tools - Homebrew - Python >= 3.10 - CMake >= 3.16 - Ninja >= 1.10 - Git >= 2.34 - flex >= 2.6 - bison >= 3.8 - gperf >= 3.1 - dfu-util >= 0.11 - `libusb`, `libffi`, `openssl`

Install and build on macOS:

xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

./scripts/setup_idf_macos.sh
./scripts/build_macos.sh

</details>

Configure

MimiClaw uses a **two-layer config** system: build-time defaults in `mimi_secrets.h`, with runtime overrides via the serial CLI. CLI values are stored in NVS flash and take priority over build-time values.

cp main/mimi_secrets.h.example main/mimi_secrets.h

Edit `main/mimi_secrets.h`:

#define MIMI_SECRET_WIFI_SSID       "YourWiFiName"
#define MIMI_SECRET_WIFI_PASS       "YourWiFiPassword"
#define MIMI_SECRET_TG_TOKEN        "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
#define MIMI_SECRET_API_KEY         "sk-ant-api03-xxxxx"
#define MIMI_SECRET_MODEL_PROVIDER  "anthropic"     // "anthropic" or "openai"
#define MIMI_SECRET_SEARCH_KEY      ""              // optional: Brave Search API key
#define MIMI_SECRET_TAVILY_KEY      ""              // optional: Tavily API key (preferred)
#define MIMI_SECRET_PROXY_HOST      ""              // optional: e.g. "10.0.0.1"
#define MIMI_SECRET_PROXY_PORT      ""              // optional: e.g. "7897"

Then build and flash:

# Clean build (required after any mimi_secrets.h change)
idf.py fullclean && idf.py build

# Find your serial port
ls /dev/cu.usb*          # macOS
ls /dev/ttyACM*          # Linux

# Flash and monitor (replace PORT with your port)
# USB adapter: likely /dev/cu.usbmodem11401 (macOS) or /dev/ttyACM0 (Linux)
idf.py -p PORT flash monitor

> **Important: Plug into the correct USB port!** Most ESP32-S3 boards have two USB-C ports. You must use the one labeled **USB** (native USB Serial/JTAG), **not** the one labeled **COM** (external UART bridge). Plugging into the wrong port will cause flash/monitor failures. > > <details> > <summary>Show reference photo</summary> > > <img src="assets/esp32s3-usb-port.jpg" alt="Plug into the USB port, not COM" width="480" /> > > </details>

CLI Commands (via UART/COM port)

Connect via serial to configure or debug. **Config commands** let you change settings without recompiling — just plug in a USB cable anywhere.

**Runtime config** (saved to NVS, overrides build-time defaults):

mimi> wifi_set MySSID MyPassword   # change WiFi network
mimi> set_tg_token 123456:ABC...   # change Telegram bot token
mimi> set_api_key sk-ant-api03-... # change API key (Anthropic or OpenAI)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 325 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MimiClaw: Pocket AI Assistant on a $5 Chip
  2. <p align="center">
  3. <img src="assets/banner.png" alt="MimiClaw" width="500" />
  4. </p>
  5. <p align="center">
  6. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  7. <a href="https://deepwiki.com/memovai/mimiclaw"><img src="https://img.shields.io/badge/DeepWiki-mimiclaw-blue.svg" alt="DeepWiki"></a>
  8. <a href="https://discord.gg/r8ZxSvB8Yr"><img src="https://img.shields.io/badge/Discord-mimiclaw-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
  9. <a href="https://x.com/ssslvky"><img src="https://img.shields.io/badge/X-@ssslvky-black?logo=x" alt="X"></a>
  10. </p>
  11. <p align="center">
  12. <strong><a href="README.md">English</a> | <a href="README_CN.md">中文</a> | <a href="README_JA.md">日本語</a></strong>
  13. </p>
  14. **The world's first AI assistant(OpenClaw) on a $5 chip. No Linux. No Node.js. Just pure C**
  15. MimiClaw turns a tiny ESP32-S3 board into a personal AI assistant. Plug it into USB power, connect to WiFi, and talk to it through Telegram — it handles any task you throw at it and evolves over time with local memory — all on a chip the size of a thumb.
  16. ## Meet MimiClaw
  17. - **Tiny** — No Linux, no Node.js, no bloat — just pure C
  18. - **Handy** — Message it from Telegram, it handles the rest
  19. - **Loyal** — Learns from memory, remembers across reboots
  20. - **Energetic** — USB power, 0.5 W, runs 24/7
  21. - **Lovable** — One ESP32-S3 board, $5, nothing else
  22. ## How It Works
  23. ![](assets/mimiclaw.png)
  24. You send a message on Telegram. The ESP32-S3 picks it up over WiFi, feeds it into an agent loop — the LLM thinks, calls tools, reads memory — and sends the reply back. Supports both **Anthropic (Claude)** and **OpenAI (GPT)** as providers, switchable at runtime. Everything runs on a single $5 chip with all your data stored locally on flash.
  25. ## Quick Start
  26. ### What You Need
  27. - An **ESP32-S3 dev board** with 16 MB flash and 8 MB PSRAM (e.g. Xiaozhi AI board, ~$10)
  28. - A **USB Type-C cable**
  29. - A **Telegram bot token** — talk to [@BotFather](https://t.me/BotFather) on Telegram to create one
  30. - An **Anthropic API key** — from [console.anthropic.com](https://console.anthropic.com), or an **OpenAI API key** — from [platform.openai.com](https://platform.openai.com)
  31. ### Install
  32. ```bash
  33. # You need ESP-IDF v5.5+ installed first:
  34. # https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/
  35. git clone https://github.com/memovai/mimiclaw.git
  36. cd mimiclaw
  37. idf.py set-target esp32s3
  38. ```
  39. <details>
  40. <summary>Ubuntu Install</summary>
  41. Recommended baseline:
  42. - Ubuntu 22.04/24.04
  43. - Python >= 3.10
  44. - CMake >= 3.16
  45. - Ninja >= 1.10
  46. - Git >= 2.34
  47. - flex >= 2.6
  48. - bison >= 3.8
  49. - gperf >= 3.1
  50. - dfu-util >= 0.11
  51. - `libusb-1.0-0`, `libffi-dev`, `libssl-dev`
  52. Install and build on Ubuntu:
  53. ```bash
  54. sudo apt-get update
  55. sudo apt-get install -y git wget flex bison gperf python3 python3-pip python3-venv \
  56. cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
  57. ./scripts/setup_idf_ubuntu.sh
  58. ./scripts/build_ubuntu.sh
  59. ```
  60. </details>
  61. <details>
  62. <summary>macOS Install</summary>
  63. Recommended baseline:
  64. - macOS 12/13/14
  65. - Xcode Command Line Tools
  66. - Homebrew
  67. - Python >= 3.10
  68. - CMake >= 3.16
  69. - Ninja >= 1.10
  70. - Git >= 2.34
  71. - flex >= 2.6
  72. - bison >= 3.8
  73. - gperf >= 3.1
  74. - dfu-util >= 0.11
  75. - `libusb`, `libffi`, `openssl`
  76. Install and build on macOS:
  77. ```bash
  78. xcode-select --install
  79. /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  80. ./scripts/setup_idf_macos.sh
  81. ./scripts/build_macos.sh
  82. ```
  83. </details>
  84. ### Configure
  85. MimiClaw uses a **two-layer config** system: build-time defaults in `mimi_secrets.h`, with runtime overrides via the serial CLI. CLI values are stored in NVS flash and take priority over build-time values.
  86. ```bash
  87. cp main/mimi_secrets.h.example main/mimi_secrets.h
  88. ```
  89. Edit `main/mimi_secrets.h`:
  90. ```c
  91. #define MIMI_SECRET_WIFI_SSID "YourWiFiName"
  92. #define MIMI_SECRET_WIFI_PASS "YourWiFiPassword"
  93. #define MIMI_SECRET_TG_TOKEN "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
  94. #define MIMI_SECRET_API_KEY "sk-ant-api03-xxxxx"
  95. #define MIMI_SECRET_MODEL_PROVIDER "anthropic" // "anthropic" or "openai"
  96. #define MIMI_SECRET_SEARCH_KEY "" // optional: Brave Search API key
  97. #define MIMI_SECRET_TAVILY_KEY "" // optional: Tavily API key (preferred)
  98. #define MIMI_SECRET_PROXY_HOST "" // optional: e.g. "10.0.0.1"
  99. #define MIMI_SECRET_PROXY_PORT "" // optional: e.g. "7897"
  100. ```
  101. Then build and flash:
  102. ```bash
  103. # Clean build (required after any mimi_secrets.h change)
  104. idf.py fullclean && idf.py build
  105. # Find your serial port
  106. ls /dev/cu.usb* # macOS
  107. ls /dev/ttyACM* # Linux
  108. # Flash and monitor (replace PORT with your port)
  109. # USB adapter: likely /dev/cu.usbmodem11401 (macOS) or /dev/ttyACM0 (Linux)
  110. idf.py -p PORT flash monitor
  111. ```
  112. > **Important: Plug into the correct USB port!** Most ESP32-S3 boards have two USB-C ports. You must use the one labeled **USB** (native USB Serial/JTAG), **not** the one labeled **COM** (external UART bridge). Plugging into the wrong port will cause flash/monitor failures.
  113. >
  114. > <details>
  115. > <summary>Show reference photo</summary>
  116. >
  117. > <img src="assets/esp32s3-usb-port.jpg" alt="Plug into the USB port, not COM" width="480" />
  118. >
  119. > </details>
  120. ### CLI Commands (via UART/COM port)
  121. Connect via serial to configure or debug. **Config commands** let you change settings without recompiling — just plug in a USB cable anywhere.
  122. **Runtime config** (saved to NVS, overrides build-time defaults):
  123. ```
  124. mimi> wifi_set MySSID MyPassword # change WiFi network
  125. mimi> set_tg_token 123456:ABC... # change Telegram bot token
  126. mimi> set_api_key sk-ant-api03-... # change API key (Anthropic or OpenAI)
  127. mimi> set_model_provider openai # switch provider (anthropic|openai)
  128. mimi> set_model gpt-4o # change LLM model
  129. mimi> set_proxy 127.0.0.1 7897 # set HTTP proxy
  130. mimi> clear_proxy # remove proxy
  131. mimi> set_search_key BSA... # set Brave Search API key
  132. mimi> set_tavily_key tvly-... # set Tavily API key (preferred)
  133. mimi> config_show # show all config (masked)
  134. mimi> config_reset # clear NVS, revert to build-time defaults
  135. ```
  136. **Debug & maintenance:**
  137. ```
  138. mimi> wifi_status # am I connected?
  139. mimi> memory_read # see what the bot remembers
  140. mimi> memory_write "content" # write to MEMORY.md
  141. mimi> heap_info # how much RAM is free?
  142. mimi> session_list # list all chat sessions
  143. mimi> session_clear 12345 # wipe a conversation
  144. mimi> heartbeat_trigger # manually trigger a heartbeat check
  145. mimi> cron_start # start cron scheduler now
  146. mimi> restart # reboot
  147. ```
  148. ### USB (JTAG) vs UART: Which Port for What
  149. Most ESP32-S3 dev boards expose **two USB-C ports**:
  150. | Port | Use for |
  151. |------|---------|
  152. | **USB** (JTAG) | `idf.py flash`, JTAG debugging |
  153. | **COM** (UART) | **REPL CLI**, serial console |
  154. > **REPL requires the UART (COM) port.** The USB (JTAG) port does not support interactive REPL input.
  155. <details>
  156. <summary>Port details & recommended workflow</summary>
  157. | Port | Label | Protocol |
  158. |------|-------|----------|
  159. | **USB** | USB / JTAG | Native USB Serial/JTAG |
  160. | **COM** | UART / COM | External UART bridge (CP2102/CH340) |
  161. The ESP-IDF console/REPL is configured to use UART by default (`CONFIG_ESP_CONSOLE_UART_DEFAULT=y`).
  162. **If you have both ports connected simultaneously:**
  163. - USB (JTAG) handles flash/download and provides secondary serial output
  164. - UART (COM) provides the primary interactive console for the REPL
  165. - macOS: both appear as `/dev/cu.usbmodem*` or `/dev/cu.usbserial-*` — run `ls /dev/cu.usb*` to identify
  166. - Linux: USB (JTAG) → `/dev/ttyACM0`, UART → `/dev/ttyUSB0`
  167. **Recommended workflow:**
  168. ```bash
  169. # Flash via USB (JTAG) port
  170. idf.py -p /dev/cu.usbmodem11401 flash
  171. # Open REPL via UART (COM) port
  172. idf.py -p /dev/cu.usbserial-110 monitor
  173. # or use any serial terminal: screen, minicom, PuTTY at 115200 baud
  174. ```
  175. </details>
  176. ## Memory
  177. MimiClaw stores everything as plain text files you can read and edit:
  178. | File | What it is |
  179. |------|------------|
  180. | `SOUL.md` | The bot's personality — edit this to change how it behaves |
  181. | `USER.md` | Info about you — name, preferences, language |
  182. | `MEMORY.md` | Long-term memory — things the bot should always remember |
  183. | `HEARTBEAT.md` | Task list the bot checks periodically and acts on autonomously |
  184. | `cron.json` | Scheduled jobs — recurring or one-shot tasks created by the AI |
  185. | `2026-02-05.md` | Daily notes — what happened today |
  186. | `tg_12345.jsonl` | Chat history — your conversation with the bot |
  187. ## Tools
  188. MimiClaw supports tool calling for both Anthropic and OpenAI — the LLM can call tools during a conversation and loop until the task is done (ReAct pattern).
  189. | Tool | Description |
  190. |------|-------------|
  191. | `web_search` | Search the web via Tavily (preferred) or Brave for current information |
  192. | `get_current_time` | Fetch current date/time via HTTP and set the system clock |
  193. | `cron_add` | Schedule a recurring or one-shot task (the LLM creates cron jobs on its own) |
  194. | `cron_list` | List all scheduled cron jobs |
  195. | `cron_remove` | Remove a cron job by ID |
  196. To enable web search, set a [Tavily API key](https://app.tavily.com/home) via `MIMI_SECRET_TAVILY_KEY` (preferred), or a [Brave Search API key](https://brave.com/search/api/) via `MIMI_SECRET_SEARCH_KEY` in `mimi_secrets.h`.
  197. ## Cron Tasks
  198. MimiClaw has a built-in cron scheduler that lets the AI schedule its own tasks. The LLM can create recurring jobs ("every N seconds") or one-shot jobs ("at unix timestamp") via the `cron_add` tool. When a job fires, its message is injected into the agent loop — so the AI wakes up, processes the task, and responds.
  199. Jobs are persisted to SPIFFS (`cron.json`) and survive reboots. Example use cases: daily summaries, periodic reminders, scheduled check-ins.
  200. ## Heartbeat
  201. The heartbeat service periodically reads `HEARTBEAT.md` from SPIFFS and checks for actionable tasks. If uncompleted items are found (anything that isn't an empty line, a header, or a checked `- [x]` box), it sends a prompt to the agent loop so the AI can act on them autonomously.
  202. This turns MimiClaw into a proactive assistant — write tasks to `HEARTBEAT.md` and the bot will pick them up on the next heartbeat cycle (default: every 30 minutes).
  203. ## Also Included
  204. - **WebSocket gateway** on port 18789 — connect from your LAN with any WebSocket client
  205. - **OTA updates** — flash new firmware over WiFi, no USB needed
  206. - **Dual-core** — network I/O and AI processing run on separate CPU cores
  207. - **HTTP proxy** — CONNECT tunnel support for restricted networks
  208. - **Multi-provider** — supports both Anthropic (Claude) and OpenAI (GPT), switchable at runtime
  209. - **Cron scheduler** — the AI can schedule its own recurring and one-shot tasks, persisted across reboots
  210. - **Heartbeat** — periodically checks a task file and prompts the AI to act autonomously
  211. - **Tool use** — ReAct agent loop with tool calling for both providers
  212. ## For Developers
  213. Technical details live in the `docs/` folder:
  214. - **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — system design, module map, task layout, memory budget, protocols, flash partitions
  215. - **[docs/TODO.md](docs/TODO.md)** — feature gap tracker and roadmap
  216. - **[docs/WIFI_ONBOARDING_AP.md](docs/WIFI_ONBOARDING_AP.md)** — how the local `MimiClaw-XXXX` onboarding/admin AP flow works
  217. - **[docs/tool-setup/](docs/tool-setup/README.md)** — configuration guides for external service integrations (Tavily, etc.)
  218. ## Contributing
  219. Please read **[CONTRIBUTING.md](CONTRIBUTING.md)** before opening issues or pull requests.
  220. ## Contributors
  221. Thanks to everyone who has contributed to MimiClaw.
  222. <a href="https://github.com/memovai/mimiclaw/graphs/contributors">
  223. <img src="https://contrib.rocks/image?repo=memovai/mimiclaw" alt="MimiClaw contributors" />
  224. </a>
  225. ## License
  226. MIT
  227. ## Acknowledgments
  228. Inspired by [OpenClaw](https://github.com/openclaw/openclaw) and [Nanobot](https://github.com/HKUDS/nanobot). MimiClaw reimplements the core AI agent architecture for embedded hardware — no Linux, no server, just a $5 chip.
  229. ## Star History
  230. <a href="https://www.star-history.com/?repos=memovai%2Fmimiclaw&type=date&legend=top-left">
  231. <picture>
  232. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=memovai/mimiclaw&type=date&theme=dark&legend=top-left" />
  233. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=memovai/mimiclaw&type=date&legend=top-left" />
  234. <img alt="Star History Chart" src="https://api.star-history.com/image?repos=memovai/mimiclaw&type=date&legend=top-left" />
  235. </picture>
  236. </a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.