Raspberry Pi Zero 2 W users: the Whisplay HAT + Waveshare Servo Driver HAT port is documented in docs/raspberry-pi-zero-2w.md.
Give your AI coding agent a body.
Tiny Engineer is an open-source, 3D-printable desktop robot that physically acts out what an AI coding agent is doing: reading, thinking, coding, finishing tasks (with a audio cue). It runs on an ESP32 over Wi-Fi and exposes a simple REST API, so any tool that can make an HTTP request can drive it.
Watch the demo · Build your own · How it works · API
AI coding agents increasingly spend long stretches working on their own. I wanted to see what mine was doing without staring at the IDE.
So I built a slightly ridiculous desk robot: instead of another spinner or status line, there is a tiny teammate sitting next to me, visibly reading, thinking, and typing while the agent works.
An AI agent works; an integration turns that into events; the robot’s REST API on your LAN receives them; the hardware moves and reacts.
How it connects
- Cursor — Cursor Agent → Cursor hooks →
tiny-engineer-cursorscript → HTTP over Wi-Fi - Antigravity CLI — Antigravity Agent → lifecycle hooks →
tiny-engineer-antigravityscript → HTTP over Wi-Fi - Claude Code — Claude Code → project hooks →
tiny-engineer-claude-codescript → HTTP over Wi-Fi - Bring your own — Codex or any other agent → your script/plugin/app → HTTP REST
All hit the same Tiny Engineer REST API (/anim). The ESP32-C3 runs that API, robot logic, and animations, then drives (and plays audio):
| Hardware | Role |
|---|---|
| PCA9685 → 5× servos | Head / neck, hands / body |
| Waveshare 0.91inch OLED (SSD1306) | Status, face, info |
| MAX98357A → speaker | Audio |
Cursor is one example client, not the architecture. Details: Cursor hooks · any integration · HTTP API
Start here: docs/getting-started.md — thin checklist (shop → print → wire → flash → assemble → wizard → prove → agent).
New to hardware? Optional skim of From Code to Circuits — then return to the checklist.
Major pieces (exact models and counts in the BOM):
| Role | Part | Qty |
|---|---|---|
| Main Controller | Waveshare ESP32-C3-Zero | 1 |
| Servo Controller PWM | Adafruit PCA9685 | 1 |
| Actuators | Analog micro servos — Tower Pro SG90 recommended; Feetech FS0307 for a compact build; Parametrically designed for any standard micro servos | 5 |
| Display | Waveshare 0.91inch OLED Module (SSD1306, 128×32, I2C) | 1 |
| Audio | MAX98357A + 8 Ω / 1 W speaker | 1 + 1 |
| USB / power | Adafruit 5993 USB-C breakout; 5 V / ≥2 A supply | 1 |
| Structure | 3D-printed parts | — |
Complete inventory and limits: docs/hardware/components.md. What to buy (cart + which servo): docs/shopping.md.
Interested in an assembled Main Board?
An integrated PCB that replaces most of the separate electronics modules and wiring is in development. If you'd be interested in getting a fully assembled board, let me know in the community interest check.
Firmware is Arduino on PlatformIO. From the project root:
pio run # build
pio run -t upload # flash firmware + LittleFS
pio device monitor # serial (115200)If servos move but audio is silent, run pio run -t uploadfs once.
Wi-Fi (first boot): join TinyEngineer-XXXX, open http://192.168.4.1/config. Wizard: servos, screen orientation, RGB LED, speaker, then a 2.4 GHz network. OLED shows the join-AP steps.
Web UI: http://tiny-engineer.local/ (or the IP on the OLED) — settings, hardware tests, animations.
Make it move:
curl -X POST "http://tiny-engineer.local/anim?name=ring"Full route list: docs/api.md. Settings: docs/settings.md.
Anything that can POST over HTTP can drive the robot:
curl -X POST "http://tiny-engineer.local/anim?name=typing"Useful name values: typing, reading, thinking, ring, welcome, wakeup, sleep, attention, error, abort, dead, none.
Cursor projects can map agent events to poses via hooks — docs/hooks.md. Broader patterns and examples: docs/integration.md. Optional extra: sleep/wake when you lock or unlock a Mac — docs/macos-lock-unlock.md.
| Goal | Doc |
|---|---|
| Build end-to-end | docs/getting-started.md |
| Flash firmware | docs/flash.md |
| Parts / cart | docs/shopping.md |
| Wiring / power | docs/hardware/README.md |
| Printable parts | 3d_models/README.md |
| Assemble printed parts | docs/3d/assembly.md |
| Resize CAD for another servo | docs/3d/parametric-design.md |
| Servo axes / safe ranges | docs/robot-movement.md |
| HTTP API | docs/api.md |
| Settings | docs/settings.md |
| Cursor hooks | docs/hooks.md |
| Any IDE / REST | docs/integration.md |
| Firmware / package tests | docs/testing.md |
| Full index | docs/README.md |
Print it, wire it, change the CAD, swap animations, or hook up a different agent. Issues and PRs welcome — especially new integrations. See CONTRIBUTING.md. Vulnerabilities: SECURITY.md. Conduct: CODE_OF_CONDUCT.md.
- Software (firmware, integrations, scripts, documentation) — MIT
- Hardware designs (CAD source and
.3mfprintables in3d_models/; KiCad PCBs inhardware/) — CERN-OHL-S-2.0
See LICENSING.md for scope and effective date. The Tiny Engineer name and logo are not licensed — see TRADEMARK.md.