Tiny Engineer: a 3D-printable ESP32 desk robot driven by your AI coding agent
A small desktop robot that brings an AI coding assistant to life, physically acting out when it reads files, thinks, writes code, and finishes work.
At a glance
- What is it?
- Tiny Engineer turns agent events into physical motion on a five-servo ESP32 robot. The REST API is simple; the build is not, and the BOM and 3D printing are the real gate.
- Who is it for?
- Adopt Tiny Engineer if you already have an agent emitting lifecycle events and you are willing to print, wire and flash an ESP32-C3 robot; the integration surface is one HTTP POST, so the software side is cheap to try. Do not adopt it if you want a status display without a soldering iron, a 5 V / 2 A supply and a 2.4 GHz network, or if your agent cannot fire hooks at all.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 18, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Tiny Engineer solves, and for whom
Long agent runs are invisible. The README states the motivation directly: agents "increasingly spend long stretches working on their own", and the author wanted to see what the agent was doing "without staring at the IDE". Tiny Engineer answers that with a desk robot that reads, thinks, types and finishes in poses instead of a spinner.
The audience is narrower than the tagline suggests. You need an agent that can emit lifecycle events, a machine on the same LAN, and the willingness to build hardware. The README points newcomers at docs/hardware-for-software-engineers/README.md, which is telling: the project expects software people who have never wired a servo. If that is you, the electronics are the project. The robot is the reward.
How an agent event becomes servo motion
The data flow is short by design. An agent works, an integration turns that into events, and the robot's REST API on your LAN receives them. The README describes three connection paths: Cursor Agent through Cursor hooks into tiny-engineer-cursor, Antigravity CLI through lifecycle hooks into tiny-engineer-antigravity, and a bring-your-own path where any script, plugin or app posts to the same endpoint.
All three converge on one route, /anim. The ESP32-C3 runs that API, the robot logic and the animations, then drives three buses. I2C carries the PCA9685 servo driver for five servos (head and neck, hands and body) and a Waveshare 0.91 inch SSD1306 OLED for status and the face. I2S carries a MAX98357A into an 8 ohm, 1 W speaker for audio.
That split is the strongest part of the design. Because the contract is HTTP rather than a plugin API, the robot does not care which agent is talking. The README is explicit that Cursor is "one, sample, client, not the architecture". The cost is that pose selection lives in your integration: the firmware exposes named animations, and something outside the robot has to decide which name matches which agent state.
Flashing the firmware and making it move
Firmware is Arduino on PlatformIO, and the README's quick start assumes you run it from the project root. Build and flash first:
pio run # build
pio run -t upload # flash firmware + LittleFS
pio device monitor # serial (115200)The monitor opens the serial console at 115200 baud. The README adds one specific failure note: if the servos move but audio is silent, run `pio run -t uploadfs` once, which re-uploads the LittleFS image that holds audio assets.
On first boot the board starts its own access point. Join `TinyEngineer-XXXX` and open `http://192.168.4.1/config` in a browser. The wizard walks through servos, screen orientation, RGB LED and speaker, then asks for a 2.4 GHz network. The OLED shows the join-AP steps while you do it.
Once the robot is on your network, the web UI is at `http://tiny-engineer.local/` (or the IP shown on the OLED), with settings, hardware tests and animations. To prove the whole chain works, post an animation name:
curl -X POST "http://tiny-engineer.local/anim?name=ring"The README lists the useful `name` values as `typing`, `reading`, `thinking`, `ring`, `welcome`, `wakeup`, `sleep`, `attention`, `error`, `abort`, `dead` and `none`. Any agent integration is a mapping from your agent's states onto that list.
The build is the real barrier, not the software
The BOM is small but not trivial: a Waveshare ESP32-C3-Zero, an Adafruit PCA9685, five analog micro servos, a Waveshare 0.91 inch OLED module, a MAX98357A, an 8 ohm speaker, an Adafruit 5993 USB-C breakout, 3D-printed parts and a 5 V supply rated at 2 A or more. Five servos moving at once is why the supply matters; the README puts the current requirement in bold rather than burying it.
Servo choice is a genuine fork. The README recommends Tower Pro SG90, names Feetech FS0307 for a compact build, and says PowerHD HD-1370A is still supported. Those are different physical sizes, so the printed parts change with the servo. The README points at docs/3d/parametric-design.md for resizing the CAD, which means the models are parametric rather than fixed. Decide the servo before you print.
The honest limitation is that this is a hardware project with a software wrapper, not the reverse. Nothing in the README suggests a kit, a pre-assembled unit or a hosted service. If you cannot flash an ESP32 and wire I2C, the robot will not exist for you, and no amount of agent configuration will change that. The README also does not document rollback or recovery for a bad flash.
Where a plain status indicator wins
The obvious alternative is a status line, a notification, or a tray icon that reports agent state without hardware. That comparison is not close on effort: a status line needs no BOM, no 2.4 GHz network and no calibration, and it works when you are away from the desk.
Tiny Engineer wins on a different axis. It is glanceable from across the room and it does not compete with the IDE for screen space, which is the stated reason it exists. The trade-off is that the information bandwidth is low. A robot pose tells you roughly what phase the agent is in; it cannot tell you which file or which error.
There is also a practical constraint the README implies rather than solves: the robot is on your LAN and driven by HTTP, so the agent integration has to be able to reach it. If your agent runs in a sandbox or a remote container without LAN access, the integration path described here does not apply and you are back to a local status indicator.
Licence split and what it means for a build
The repository separates software from hardware. Firmware, integrations, scripts and documentation are MIT. The CAD source, the .3mf printables in 3d_models/ and the KiCad PCBs in hardware/ are CERN-OHL-S-2.0. LICENSING.md is cited for scope and effective date.
The practical consequence is that printing and modifying the physical design carries a different licence than forking the firmware, and CERN-OHL-S-2.0 is a reciprocal hardware licence rather than a permissive one. The name and logo are handled separately: TRADEMARK.md states they are not licensed, so a modified build is not automatically free to ship under the Tiny Engineer name. This is a description of what the files say, not legal advice; read LICENSING.md and TRADEMARK.md before distributing anything.
Maintenance is worth noting too. The last push was on 2026-09-14, and the only release so far is v0.1.0, tagged "First Working Prototype" on 2026-08-30. That is an early project, and the version number should set expectations about API stability.
Editorial conclusion
Adopt Tiny Engineer if you already have an agent emitting lifecycle events and you are willing to print, wire and flash an ESP32-C3 robot; the integration surface is one HTTP POST, so the software side is cheap to try. Do not adopt it if you want a status display without a soldering iron, a 5 V / 2 A supply and a 2.4 GHz network, or if your agent cannot fire hooks at all. Before buying parts, verify three things in the repository: the servo choice against docs/3d/parametric-design.md, the pin and power assumptions in docs/hardware/wiring.md, and whether your agent can map events to the pose names listed in docs/api.md.
Frequently asked questions
What hardware does Tiny Engineer need?
A Waveshare ESP32-C3-Zero, an Adafruit PCA9685, five analog micro servos, a Waveshare 0.91 inch OLED module, a MAX98357A with an 8 ohm speaker, an Adafruit 5993 USB-C breakout, 3D-printed parts and a 5 V supply rated at 2 A or more. The README recommends Tower Pro SG90 servos, with Feetech FS0307 for a compact build.
How do I make the Tiny Engineer robot move from the command line?
Post an animation name to the /anim route. The README gives the example `curl -X POST "http://tiny-engineer.local/anim?name=ring"`, and lists names including typing, reading, thinking, welcome, sleep and error.
Which AI coding agents can drive Tiny Engineer?
The README describes Cursor through Cursor hooks and the tiny-engineer-cursor CLI, Antigravity CLI through lifecycle hooks and tiny-engineer-antigravity, and a bring-your-own path for Claude, Codex or any other agent that can send an HTTP request to the REST API.
Community notes