The Physical AI Agent

MicroClaw transforms a $2 ESP32 into a general-purpose AI agent that reasons, remembers, and controls real hardware through natural language.

⚡ Quick Start

Follow these steps to get your agent running in minutes.

1. Install Dependencies

Requires Python 3.10+. We recommend uv for speed.

uv pip install -r tools/requirements.txt

2. Launch the MicroClaw Manager

The Manager handles configuration, firmware flashing, and serial monitoring.

python main.py
# or with uv:
uv run main.py

Open http://localhost:8000 in your browser.

3. Setup & Flash

In the Manager web UI:

• Go to the Setup Tab and enter your WiFi credentials + API keys (Gemini or Groq).
• Click Build & Flash to compile and upload firmware to your ESP32.
• Switch to the Monitor Tab to see serial logs and chat with your AI agent.

🔌 Hardware

MicroClaw runs on any ESP32 development board. No additional wiring is required for basic AI features.

Connect external components (LEDs, relays, sensors) to any available GPIO pin and control them via natural language.

🧠 AI Capabilities

MicroClaw uses a recursive reasoning loop: the AI calls a tool, receives the hardware result, then generates a human-friendly summary in a second LLM call.

Available Tools

• gpio_control({pin: int, mode: "input"|"output", state: 0|1}) — Control any GPIO pin.
• get_system_stats() — Read free heap, CPU frequency, flash size, and uptime.
• wifi_scan() — Scan for nearby WiFi networks and return SSIDs, signal strength, and encryption.
• ble_scan() — Scan for nearby Bluetooth Low Energy devices.
• memory_write({content: "..."}) — Save facts to persistent LittleFS storage.
• memory_read() — Retrieve long-term memory contents.

Example Prompt Interactions

"Scan for WiFi networks" → Calls wifi_scan(), then summarizes results in plain English.

"How much memory do you have?" → Calls get_system_stats(), reports free heap and CPU info.

"Turn on the LED on pin 2" → Calls gpio_control(2, "output", 1).

"Remember that my name is Abhimanyu" → Calls memory_write(), persists across reboots.

📡 API Reference

The ESP32 hosts a web server. You can interact with it programmatically.

{
  "text": "Scan for WiFi networks",
  "history": []  // optional, last N messages
}

{
  "reply": "I found 5 networks nearby...",
  "thought": "User wants WiFi info",
  "tool": "wifi_scan",
  "tool_result": "{...raw scan data...}"
}