reachy-mini-cli

Agent and CLI for operating the Reachy Mini expressive robot — device setup, app management, and live runtime ops.

# Real mode (local robot: daemon binary + SDK):
uv tool install 'reachy-mini-cli[daemon]'
reachy-mini-cli quickstart      # copy-paste install + bring-up sequence
reachy-mini-cli daemon start    # bring the daemon up (wakes the robot)
reachy-mini-cli behavior engine run   # the presence runtime (Ctrl-C to stop)

The installed command is reachy-mini-cli (short alias: reachy). New here? Read the Operating Reachy Mini guide — it covers bring-up, verification, and the one model you must understand before running two behaviors at once.

What Reachy Mini can do

Reachy Mini is an expressive desk robot — a movable head, two antennas, a rotating body, a USB mic array (with direction-of-arrival), a camera, and a speaker. reachy-mini-cli exposes each capability as a noun you run from a shell or an agent loop: hold the hardware (daemon), feel alive when idle (demo-mode), orient to sight (vision), speak in a TTS or offline harmonic voice (say), bench-check a head pat (pat), and park itself when left alone (sleep). The symbolic runtime (behavior engine run) is where the senses come together: one deterministic 50 Hz presence that hears words, feels pats, leans its antennas toward sound and answers out loud, and that an AI agent attaches to (agent attach) rather than replaces. The embodiment layer (agent embody) is the optional other half — ears, a voice and a cue-triggered mind running beside that runtime, switched on and off like a peripheral. service makes one presence mode survive a reboot.

Noun map

The complete robot surface. Every noun supports --json; run reachy-mini-cli explain <noun> for the full flag reference.

⚠️ Before you run two behaviors at once, read the single-SDK-owner model. The robot serves one in-process SDK client and one motion queue, each a single resource: the behavior runtime, sleep, vision, and pat are mutually exclusive on the sdk transport — and pat run / sleep run refuse outright to start beside a live engine rather than starve. This trips up humans and agents repeatedly. The conflict matrix and the two correct ways to compose behaviors anyway are in the guide.

Install

reachy-mini is an extra, not a base dep (its pycairo/gstreamer/pyaudio stack needs system libraries a bare box lacks). Running the sdk transport on a bare install exits 2 with a hint to install [sdk] — never a traceback. See Install profiles for the full rationale. reachy-cli remains a transitional alias that pulls in reachy-mini-cli.

Optional extras on top, all lazy-imported (absent → the feature goes quiet after one named warning, never a crash): [vision] (OpenCV — face recognition, scene description, the rolling video clip), [cpu] (on-box openwakeword), and [bench] (sounddevice, needed only for the embodiment layer's bench media profile — the deployed robot path uses a unix socket and urllib, both stdlib).

Operating Reachy live

The full operating guide is docs/operating-reachy.md:

• Bring Reachy up live — install → daemon → verify → behavior
• The single-SDK-owner model — the conflict matrix + how to compose behaviors
• Transports — sdk vs http
• Boot persistence — make one presence (demo/runtime) survive a reboot via service
• The symbolic runtime — a deterministic, model-free presence (behavior + rules.toml) an AI agent can attach to (reachy-mini-cli agent attach) instead of replace
• The embodiment layer — the optional conversational mind (reachy-mini-cli agent embody) that runs beside it
• Verify it's working
• The ~/.asoundrc mic-array gotcha — the most common silent failure
• Environment variables — every REACHY_* var in one table
• Troubleshooting — symptoms → fixes, exit codes
• Noun reference — each noun's sense, motion, and transport

Common commands

reachy-mini-cli daemon start                                   # bring the daemon up (wakes the robot)
reachy-mini-cli device status                                  # verify it answers
reachy-mini-cli move goto --z 10 --pitch -5 --duration 2       # one motion command
reachy-mini-cli demo-mode start                                # feel-alive idle loop (background)
reachy-mini-cli behavior engine run                            # ALL senses in one loop (the symbolic runtime presence)
reachy-mini-cli vision run                                     # orient to motion/light (sdk)
reachy-mini-cli say run "Hello from Reachy"                    # text-to-speech
reachy-mini-cli pat run                                        # bench check: feel a head pat and lean in
reachy-mini-cli sleep run                                      # park the robot; wake when addressed
reachy-mini-cli daemon stop                                    # put it back down

The background nouns (demo-mode, vision, sleep) also expose start / stop / restart / status, and behavior engine exposes start / stop / status; pat and sleep also expose demo (no robot needed). pat run and sleep run refuse to start beside a live engine — one owner per head. See reachy-mini-cli explain <noun>.

The runtime presence and boot persistence

behavior engine run is the symbolic runtime — a deterministic 50 Hz loop that composes every sense (proprioceptive pat, loudness, transcribed words, faces, camera-frame availability) and drives the head through one arbitrated motion channel. It is the supported way to run all the senses at once (one media owner; see the single-SDK-owner model below). An AI agent attaches to it over its JSONL feed and intent spool (agent attach) rather than replacing it.

Its decision loop is symbolic and model-free, and CI enforces that. An AST import-boundary suite proves the engine, rule engine, rules, intents, arbitration, goto lane and pat sense reach nothing in the speech, vision or forge stacks. The runtime does own a voice and ears — deliberately ported capabilities — so it imports speech synthesis, playback and transcription, none of which is a language model. Exactly one language-model call survives inside the runtime: the engagement gate's optional single-shot "is this addressed to me?" classifier. It runs on the transcript worker thread rather than the 20 ms tick, fails open to a pure-difflib heuristic, gates only whether heard words enter the sense snapshot — and REACHY_ENGAGE_HEURISTIC=1 removes it entirely, giving a box a provably zero-LLM presence. See the zero-token rationale.

Mic audio streams continuously to the lobes /v1/realtime WebSocket session (REACHY_REALTIME_URL / REACHY_OPENAI_URL_BASE), whose server-side VAD decides where each utterance starts and stops; the resulting transcript reaches the rules as a transcript sense field, so a rule can react to what was said — not just that a sound came from the left. A self-mute window means the robot never transcribes its own voice, and a down session degrades to "no words" rather than stalling the loop — there is no local fallback endpointer. It is not a chat/turn-taking assistant — words are one more perception. One honest boundary: the shipped reaction to bare sound is an antenna lean only — the head does not turn (the turn path is implemented and reachable by configuration, just not defaulted on). See Hearing over the lobes realtime session for the design and Hearing — server-side VAD replaces local endpointing for what is and is not evidenced live today.

reachy-mini-cli behavior engine run                            # the deterministic presence
reachy-mini-cli agent attach --feed - --export -               # an AI agent alongside it

The runtime's voice (a rule's say: field) is the offline harmonic note-melody engine by default — fully in-process, deterministic, no external service to reach — so a box with nothing reachable still speaks. say run accepts --voice-engine {tts,harmonic} (default tts) to pick per invocation; tune the voice with REACHY_HARMONIC_IDENTITY / REACHY_HARMONIC_ARTICULATION. See The harmonic voice for the full picture.

reachy-mini-cli say run "Hello" --voice-engine harmonic        # offline note-melody voice

service makes one presence boot-persistent via systemd --user. Exactly one mode is enabled at a time — enabling one disables the siblings — and it auto-restarts on crash. The daemon is a boot dependency of every presence unit.

reachy-mini-cli service install                                # write the systemd units (enable nothing)
reachy-mini-cli service enable runtime                         # boot-persist the symbolic runtime
reachy-mini-cli service enable demo                            # switch to the idle demo loop
reachy-mini-cli service status --json                          # which mode is enabled + daemon health
reachy-mini-cli service disable                                # stop the presence (daemon stays up)

⚠️ Upgrading a box that ran the old live presence? reachy-live.service is retired: the next service enable / install / uninstall purges it (disable, unlink the unit, remove its .d/ drop-in directory) and reports the names it removed as retired_removed. That purge is destructive and irreversible — back up ~/.config/systemd/user/reachy-*.service* first.

A true machine-reboot check is manual: a systemctl --user service starts at boot only when the user has linger enabled (loginctl enable-linger $USER). See Boot persistence.

The embodiment layer — a conversational mind you can switch on

The runtime above is symbolic and mute in conversation: agent attach is turn-based, has no transcript cue, and composes its voice tools publish-only, so nothing in that process ever makes a sound. reachy-mini-cli agent embody is the optional other half. It runs as a separate process beside the runtime and gives the robot ears (one lobes /v1/realtime duplex session with server-side VAD, ungated — it hears every voice in the room), a real voice, and a cue-triggered mind that reacts in voice when the robot's own rules fire. It operates the robot only through a closed five-tool set — goto, run_behavior, speak, harmonics, create_rule — each wrapping a validator that already exists and already refuses fail-closed. There is no shell.

reachy-mini-cli behavior engine run --export - > /tmp/runtime.feed &   # the runtime
reachy-mini-cli agent embody --feed /tmp/runtime.feed --export -       # the layer
reachy-mini-cli agent embody start   # …or as a tracked background process
reachy-mini-cli agent embody stop

It is genuinely a peripheral, and that was checked rather than asserted: the whole arc's footprint inside reachy/behavior/ is 3 files, 6 diff hunks, 1486 inserted lines and 0 deleted lines — only two additive export legs (an audio tee and a rolling-clip rider), each measured at zero tick overruns on the deployed robot even with a wedged consumer. Stop the layer and the robot is exactly the symbolic presence above. Swapping the mind is configuration too: models are chosen per request from REACHY_EMBODY_WORKER_MODEL / REACHY_EMBODY_SENSES_MODEL.

One thing deliberately survives a stop: rules the layer authored (always embody- prefixed) persist in the overlay and keep running — the robot keeps what it was taught — and stay enumerable and removable by that prefix.

Honest status: on real hardware the layer heard, thought, spoke aloud and moved the robot (a rule fire became a spoken reaction; run_behavior and goto were admitted by the live engine). It has not yet held a sustained two-way conversation — the test box has one audio output, which blocked the browser-harness acceptance run — and harmonics, create_rule and the clip→worker-model leg are not yet exercised live. See What is proven live — and what is not.

Export feed

agent attach --export - streams a live newline-delimited JSON (NDJSON) feed of what the attached agent is thinking, proposing to say, and proposing to express — one object per line. agent attach composes its speech and pose tools publish-only, so a message block is what the agent proposed saying, not proof of sound; audible speech comes from a rule's say in the runtime and carries no block of its own. agent embody --export - publishes the same three block types from the embodiment layer, where the voice tools are real — there a message is an utterance dispatched to a live speaker, or one already spoken. behavior engine run --export - streams the complementary runtime feed (sense / rule / intent / motion). The renderer stays out of this repo by design (the export decoupling boundary): reachy-mini-cli emits a documented contract, a separate consumer renders it.

reachy-mini-cli behavior engine run --export - > runtime.jsonl &  # the runtime feed
reachy-mini-cli agent attach --feed runtime.jsonl --export -      # all cognition block types
reachy-mini-cli agent attach --feed runtime.jsonl --export - --export-blocks message,emotion
reachy-mini-cli agent attach --feed runtime.jsonl --export - | <your renderer>

Wire format: docs/export-schema.md. For the renderer boundary and the reference reterminal consumer, see Export feed & the external renderer.

What you get

• An agent-first CLI cited from teken (afi-cli).
• A mesh identity — culture.yaml (suffix + backend) and the matching prompt file (CLAUDE.md for backend: claude).
• A vendored skill kit under .claude/skills/ (18 skills — mostly from guildmaster, plus the devague chain and ask-colleague), cite-don't-import. See docs/skill-sources.md.
• A build + deploy baseline — pytest, lint, the agent-first rubric gate, and PyPI Trusted Publishing wired into GitHub Actions.

Developer quickstart

For working on the repo itself (an editable checkout, not an end-user install):

uv sync --extra daemon                # recommended — SDK + the reachy-mini-daemon binary
uv sync                               # bare — numpy only; HTTP remote profile (--transport http)
uv run pytest -n auto                 # run the test suite
uv run reachy whoami                  # identity from culture.yaml
uv run reachy learn                   # self-teaching prompt (add --json)
uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs

CLI (introspection)

The agent-first verbs that work with no robot attached:

Every command supports --json. Results go to stdout, errors/diagnostics to stderr (never mixed). Exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved.

Make it your own

1. Rename the package reachy/ and the reachy-mini-cli CLI/dist name throughout pyproject.toml, the package, tests/, and sonar-project.properties.
2. Edit culture.yaml with your suffix and backend.
3. Rewrite CLAUDE.md for your agent and run /init.
4. Re-vendor only the skills you need from guildmaster (see docs/skill-sources.md).

See CLAUDE.md for the full conventions (version-bump-every-PR, the cicd PR lane, deploy setup).

License

MIT — see LICENSE.