tiny-engineer README

The project's README from github.com/jamro/tiny-engineer. As one markdown file: README.md.

Tiny Engineer

Give your AI coding agent a body.

Tiny Engineer demo

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. 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

Why?

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.

How it works

How Tiny Engineer 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

Both hit the same Tiny Engineer REST API (/anim). The ESP32-C3 runs that API, robot logic, and animations, then drives:

Bus Hardware Role
I2C PCA9685 → 5× servos Head / neck, hands / body
I2C SSD1306 OLED Status, face, info
I2S MAX98357A → speaker Audio

Cursor is one, sample, client, not the architecture. Details: Cursor hooks · any integration · HTTP API

Build your own

End-to-end path (details live in the linked docs):

New to hardware? Start with From Code to Circuits — hardware and electronics for software engineers; Tiny Engineer is the worked example.

  1. Get the electronics — hardware inventory
  2. 3D print the parts — printables
  3. Assemble the mechanics — fit the five servos — 3D models, servo axes
  4. Wire the electronics — wiring, hardware overview
  5. Flash the ESP32 firmware — getting started → Flash
  6. Configure Wi-Fi — getting started → Wi-Fi
  7. Test the robot — web UI + a curl — getting started → Prove it
  8. Connect your coding agent — Cursor hooks or any IDE / REST

Full walkthrough: docs/getting-started.md.

Hardware overview

Major pieces (exact models and counts in the BOM):

Role Part Qty
Controller Waveshare ESP32-C3-Zero 1
Servo PWM Adafruit PCA9685 1
Actuators PowerHD HD-1370A micro servos 5
Display 0.91" 128×32 SSD1306 OLED (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.

Quick start

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: servo calibration, 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.

AI integrations

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.

Documentation

Goal Doc
Build end-to-end docs/getting-started.md
Parts / BOM docs/hardware/components.md
Wiring / power docs/hardware/README.md
Printable parts 3d_models/README.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

Build one, break one, share it

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.

Tiny Engineer

License

See LICENSING.md for scope and effective date. The Tiny Engineer name and logo are not licensed — see TRADEMARK.md.

tiny-engineer (jamro/tiny-engineer)

Searching Database…

Что это?Tiny Engineer — открытый настольный робот, печатаемый на 3D-принтере, который физически изображает, чем занят ваш AI-агент кодинга: читает, думает, пишет код и завершает задачи.
Как собрать и запустить его?Следуйте восьми шагам: добудьте электронику, распечатайте детали на 3D-принтере, соберите пять сервоприводов, соедините всё проводами, прошейте прошивку ESP32-C3 через PlatformIO, подключитесь к его Wi-Fi-точке доступа для настройки сети, проверьте через веб-интерфейс или curl, затем подключите своего кодинг-агента.
Какое железо нужно купить?Список сборки: Waveshare ESP32-C3-Zero, серводрайвер Adafruit PCA9685, пять микросервоприводов PowerHD HD-1370A, OLED 0.91' 128x32 SSD1306, усилитель MAX98357A с динамиком 8ohm, плата питания USB-C и конструктивные детали с 3D-печати.
Есть ли подводные камни при установке?Если сервоприводы двигаются, а звук молчит, нужно один раз выполнить загрузку файловой системы (pio run -t uploadfs), чтобы залить звуковые файлы на плату.
Какие кодинг-агенты могут управлять роботом?Cursor подключается через Cursor hooks, Antigravity CLI — через его lifecycle hooks, а любой другой агент, включая Claude или Codex, может управлять им обычными HTTP POST-запросами к тому же REST-эндпоинту.
Какие позы или анимации робот реально умеет?Он поддерживает именованные состояния вроде typing, reading, thinking, ring, welcome, wakeup, sleep, attention, error, abort, dead и none, вызываемые через REST-эндпоинт /anim.
Зачем автор сделал физического робота, а не просто индикатор статуса?Создатель хотел осязаемый способ видеть, чем занят долгоживущий автономный AI-агент кодинга, вместо того чтобы просто смотреть на спиннер или строку статуса в IDE, поэтому он собрал небольшого робота на стол, который наглядно реагирует на активность агента.
Может ли он реагировать на что-то помимо событий кодинг-агента?Да, есть опциональная интеграция с macOS, из-за которой робот засыпает и просыпается автоматически, когда вы блокируете или разблокируете свой Mac.
Creator
jamro
Size
415.4 MB
Stars
695
Age
1mo
Commits · 90 Days