hermes-bot/CLAUDE.md

Hermes robot

Desk robot giving Hermes Agent (on a NixOS or Omarchy host) a camera, microphones, speakers, a pan/tilt head and an oscilloscope-style face. Hardware: Raspberry Pi 4, Adafruit BrainCraft HAT, Arducam UC-346 (OV5647), two MG90S servos on GPIO12/13. Software: ROS 2 Jazzy on Ubuntu 24.04 on the Pi; on the hosts, ROS runs only in podman containers.

Start with HANDOFF.md. It is the implementation brief: hardware facts, what exists, the work packages in order, acceptance checks, and the list of unverified assumptions.

• pi/ and ros/ run on the robot; omarchy/ (to become host/) runs on the owner's machines.
• Package 0a (platform proof) comes before everything; start with host/check-pi-platform.sh.
• docs/face-prototype.html is the reference for the face renderer; port it, don't ship it.
• enclosure/ holds the OpenSCAD model and STLs. It was built from estimates; refine it from the owner's caliper measurements and test prints before anyone prints the large parts.
• README.md still describes the earlier Pi Zero build until package 7 rewrites it.
• The MCP server uses the MCP Python SDK 2.x (mcp.server.mcpserver.MCPServer), not 1.x FastMCP.
• Ask before rebooting the Pi, upgrading or holding kernel packages, or opening network ports.