feat(integrations): tiny engineer client CLI

.agents/hooks.json

@@ -2,7 +2,7 @@
   "tiny-engineer": {
     "PreInvocation": [
       {
-        "command": "tiny-engineer-antigravity PreInvocation",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook antigravity PreInvocation",
         "timeout": 3
       }
     ],
@@ -11,7 +11,7 @@
         "matcher": "*",
         "hooks": [
           {
-            "command": "tiny-engineer-antigravity PreToolUse",
+            "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook antigravity PreToolUse",
             "timeout": 3
           }
         ]
@@ -22,15 +22,15 @@
         "matcher": "*",
         "hooks": [
           {
-            "command": "tiny-engineer-antigravity PostToolUse",
+            "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook antigravity PostToolUse",
             "timeout": 3
           }
         ]
       }
     ],
     "Stop": [
       {
-        "command": "tiny-engineer-antigravity Stop",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook antigravity Stop",
         "timeout": 3
       }
     ]

.claude/settings.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -27,7 +27,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -38,7 +38,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -49,7 +49,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -60,7 +60,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -71,7 +71,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -82,7 +82,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -93,7 +93,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -104,7 +104,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -115,7 +115,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -126,7 +126,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]
@@ -137,7 +137,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js\"",
+            "command": "node \"$CLAUDE_PROJECT_DIR/packages/tiny-engineer-cli/bin/tiny-engineer.js\" hook claude-code",
             "async": true
           }
         ]

.cursor/hooks.json

@@ -3,7 +3,7 @@
   "hooks": {
     "sessionStart": [
       {
-        "command": "node packages/tiny-engineer-cursor/bin/tiny-engineer-cursor.js",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook cursor",
         "timeout": 2
       },
       {
@@ -13,7 +13,7 @@
     ],
     "beforeSubmitPrompt": [
       {
-        "command": "node packages/tiny-engineer-cursor/bin/tiny-engineer-cursor.js",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook cursor",
         "timeout": 2
       },
       {
@@ -23,7 +23,7 @@
     ],
     "afterAgentThought": [
       {
-        "command": "node packages/tiny-engineer-cursor/bin/tiny-engineer-cursor.js",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook cursor",
         "timeout": 2
       },
       {
@@ -33,7 +33,7 @@
     ],
     "preCompact": [
       {
-        "command": "node packages/tiny-engineer-cursor/bin/tiny-engineer-cursor.js",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook cursor",
         "timeout": 2
       },
       {
@@ -43,7 +43,7 @@
     ],
     "preToolUse": [
       {
-        "command": "node packages/tiny-engineer-cursor/bin/tiny-engineer-cursor.js",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook cursor",
         "timeout": 2
       },
       {
@@ -53,7 +53,7 @@
     ],
     "beforeReadFile": [
       {
-        "command": "node packages/tiny-engineer-cursor/bin/tiny-engineer-cursor.js",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook cursor",
         "timeout": 2
       },
       {
@@ -63,7 +63,7 @@
     ],
     "beforeShellExecution": [
       {
-        "command": "node packages/tiny-engineer-cursor/bin/tiny-engineer-cursor.js",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook cursor",
         "timeout": 2
       },
       {
@@ -73,7 +73,7 @@
     ],
     "subagentStart": [
       {
-        "command": "node packages/tiny-engineer-cursor/bin/tiny-engineer-cursor.js",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook cursor",
         "timeout": 2
       },
       {
@@ -83,7 +83,7 @@
     ],
     "afterFileEdit": [
       {
-        "command": "node packages/tiny-engineer-cursor/bin/tiny-engineer-cursor.js",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook cursor",
         "timeout": 2
       },
       {
@@ -93,7 +93,7 @@
     ],
     "stop": [
       {
-        "command": "node packages/tiny-engineer-cursor/bin/tiny-engineer-cursor.js",
+        "command": "node packages/tiny-engineer-cli/bin/tiny-engineer.js hook cursor",
         "timeout": 2
       },
       {

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,7 +7,7 @@
 - [ ] Title is `type(scope): summary`
 - [ ] Breaking HTTP / pins / NVS / servo defaults / hook CLI called out as `type!:` plus a `BREAKING CHANGE:` footer
 - [ ] Firmware: `pio run` and/or `pio test -e native` when that code changed
-- [ ] Packages: `npm test --prefix packages/tiny-engineer-cursor` / `…/tiny-engineer-antigravity` / `…/tiny-engineer-claude-code` when that package changed
+- [ ] Packages: `npm test --prefix packages/tiny-engineer-cli` / `…/tiny-engineer-cursor` / `…/tiny-engineer-antigravity` / `…/tiny-engineer-claude-code` when that package changed
 - [ ] HTTP: HTML index (`ui/index.html`) + `docs/api.md` (and README / `docs/hardware/testing.md` if the route list changed)
 - [ ] Settings: layers in `docs/settings.md`; no raw `access_token` in logs
 - [ ] CAD: `.f3d` + exported `.3mf`; CERN-OHL-S; `AiEmblem.3mf` not used as a branding swap

.github/workflows/ci.yml

@@ -78,6 +78,8 @@ jobs:
           npm ci --prefix ui
           npm run lint --prefix ui
           npm test --prefix ui
+      - name: Unified CLI package tests
+        run: npm test --prefix packages/tiny-engineer-cli
       - name: Cursor package tests
         run: npm test --prefix packages/tiny-engineer-cursor
       - name: Antigravity package tests

AGENTS.md

@@ -31,6 +31,7 @@ pio run -e expression-demo
 pio test -e native
 node scripts/expressions/generate.js --check
 node scripts/expressions/test-assets.js
+npm test --prefix packages/tiny-engineer-cli
 npm test --prefix packages/tiny-engineer-cursor
 npm test --prefix packages/tiny-engineer-antigravity
 npm test --prefix packages/tiny-engineer-claude-code

CONTRIBUTING.md

@@ -47,6 +47,7 @@ pio run -e expression-demo
 pio test -e native
 node scripts/expressions/generate.js --check
 node scripts/expressions/test-assets.js
+npm test --prefix packages/tiny-engineer-cli
 npm test --prefix packages/tiny-engineer-cursor
 npm test --prefix packages/tiny-engineer-antigravity
 npm test --prefix packages/tiny-engineer-claude-code
@@ -115,7 +116,7 @@ Robot builds bake `git describe --tags --always --dirty` into `FW_VERSION` via [
 - Dev build: `v0.1.0-<n>-g<sha>` (optional `-dirty`)
 - No git metadata: `unknown`
 
-A firmware tag does not bump the npm packages. CI (`.github/workflows/ci.yml`) builds with full git history and uploads `bootloader.bin`, `partitions.bin`, `firmware.bin`, and `littlefs.bin` as the `firmware-<sha>` Actions artifact on every PR and `main` push. Pushing a tag matching `v*` runs `.github/workflows/release.yml`, which attaches the same four bins as `tiny-engineer-<tag>-{bootloader,partitions,firmware,littlefs}.bin` plus a stable-name `manifest.json` (offsets from that tag’s `partitions.csv`). Pages deploy (`.github/workflows/pages.yml`) mirrors those assets via `scripts/build_flash_catalog.py` so the web flasher can install same-origin (Release CDN blocks browser CORS).
+A firmware tag does not bump the npm packages. Publish the host CLI (`tiny-engineer` on npm) with a separate SemVer and checklist: [docs/cli-release.md](docs/cli-release.md). CI (`.github/workflows/ci.yml`) builds with full git history and uploads `bootloader.bin`, `partitions.bin`, `firmware.bin`, and `littlefs.bin` as the `firmware-<sha>` Actions artifact on every PR and `main` push. Pushing a tag matching `v*` runs `.github/workflows/release.yml`, which attaches the same four bins as `tiny-engineer-<tag>-{bootloader,partitions,firmware,littlefs}.bin` plus a stable-name `manifest.json` (offsets from that tag’s `partitions.csv`). Pages deploy (`.github/workflows/pages.yml`) mirrors those assets via `scripts/build_flash_catalog.py` so the web flasher can install same-origin (Release CDN blocks browser CORS).
 
 Public site UI lives under [`web/`](web/) (GitHub Pages via `.github/workflows/pages.yml`). Follow [`web/STYLE.md`](web/STYLE.md) for visual changes.
 

README.md

@@ -17,7 +17,7 @@ A small robot on your desk. It moves, changes its face, and rings a bell as your
 
 Open source. Print the body, plug the ESP32, servos, OLED, and speaker into the [main control board](docs/hardware/main-control-board.md), flash it, and it joins your Wi-Fi.
 
-**Works with** [Claude Code](docs/integration.md#4-claude-code-dedicated-script) · [Cursor](docs/hooks.md) · [Antigravity](docs/integration.md#3-antigravity-cli-dedicated-script) — or Codex, Windsurf, and any script that can POST ([integration guide](docs/integration.md)), including speech through [`POST /play`](docs/api.md#post-play).
+**Works with** Claude Code · Cursor · Antigravity — via [`npx -y tiny-engineer setup`](docs/integration.md) — or Codex, Windsurf, and any script that can POST ([integration guide](docs/integration.md) · [HTTP API](docs/api.md)), including speech through [`POST /play`](docs/api.md#post-play).
 
 ## Build your own
 
@@ -63,10 +63,8 @@ Your agent (or a hook script) sends poses over HTTP. The **ESP32-C3** is a small
 
 **Clients**
 
-- **Cursor** - hooks → `tiny-engineer-cursor` → Wi-Fi
-- **Antigravity** - lifecycle hooks → `tiny-engineer-antigravity` → Wi-Fi
-- **Claude Code** - project hooks → `tiny-engineer-claude-code` → Wi-Fi
-- **Bring your own** - any tool that can `POST` to `/anim`
+- **Default** — [`npx -y tiny-engineer`](https://www.npmjs.com/package/tiny-engineer) (`setup` / `hook`) for Cursor, Claude Code, Antigravity → Wi-Fi
+- **Advanced** — any tool that can `POST` to `/anim` ([HTTP API](docs/api.md))
 
 Details: [Integrations](docs/integration.md) · [HTTP API](docs/api.md) · [Cursor hooks](docs/hooks.md)
 

docs/README.md

@@ -19,15 +19,16 @@ Pick a path. Depth lives in the linked pages.
 | **Adapt CAD to a different servo** | [3d/parametric-design.md](3d/parametric-design.md) |
 | **Add a new CAD / printable part** | [3d/adding-parts.md](3d/adding-parts.md) |
 | **Optional mods** | [../mods/README.md](../mods/README.md) |
-| **Use with an agent** (robot already on Wi-Fi) | [integration.md](integration.md) · Cursor: [hooks.md](hooks.md) |
+| **Use with an agent** (robot already on Wi-Fi) | [integration.md](integration.md) (`tiny-engineer` CLI or REST) · Cursor: [hooks.md](hooks.md) |
 
 ### Reference and contribute
 
 | You want to… | Start here |
 | --- | --- |
 | **Contribute a PCB** (KiCad) | [pcb.md](pcb.md) → [`hardware/`](../hardware/README.md) |
 | **HTTP API / settings** | [api.md](api.md); add a setting: [settings.md](settings.md) |
-| **Any IDE / scripts** | [integration.md](integration.md) |
+| **CLI setup / REST for any IDE** | [integration.md](integration.md) |
+| **Publish npm CLI** (`tiny-engineer`) | [cli-release.md](cli-release.md) |
 | **Firmware / package tests** | [testing.md](testing.md) |
 | **AI coding agents (repo rules)** | [AGENTS.md](../AGENTS.md) |
 | **Contribute / report a vuln** | [CONTRIBUTING.md](../CONTRIBUTING.md); [SECURITY.md](../SECURITY.md) |

docs/api.md

@@ -565,7 +565,7 @@ curl -X POST http://tiny-engineer.local/play/thinking -H 'Content-Type: audio/wa
 { "ok": true, "played_ms": 3000 }
 ```
 
-The Claude Code CLI wraps this for agents: `tiny-engineer-claude-code play clip.wav [--name thinking]` ([integration.md](integration.md#4-claude-code-dedicated-script)).
+The unified CLI wraps this for agents: `tiny-engineer play clip.wav [--name thinking]` ([integration.md](integration.md#1-unified-cli-default)).
 
 Errors arrive before any audio plays: