planeshiftdev/microd

This repository contains two small programs that connect a physical macropad called the Codex Micro to a desktop automation tool called herdr. The Codex Micro is a small keypad with six programmable keys, a dial, and a joystick, made by Work Louder in collaboration with OpenAI. The programs are written in Rust and run on macOS as background services. The first program, microd, talks directly to the macropad over USB or Bluetooth. It reads every button press, dial turn, and joystick movement from the device and sends those events out as structured text messages over a local communication channel called a Unix socket. Any program on the computer can connect to that socket and receive the events. On top of reporting raw button activity, microd recognizes higher-level gestures like taps, long presses, double taps, chords (holding one key while pressing another), and joystick flicks. It can also send commands back to the pad to control the RGB lighting on each key, with effects like solid colors, flashing, and a breathing fade. The second program, herdr-bridge, sits between microd and herdr. It maps the six physical keys on the macropad to up to six software agents running in herdr. Each key's light reflects the status of its corresponding agent: breathing blue when working, flashing amber when blocked, solid green when done. The keys, dial, and joystick let you switch between agents, approve or deny agent actions, jump to blocked agents, and navigate tabs and workspaces. A small menu bar app lets you switch ownership of the macropad between herdr and the ChatGPT desktop app, since only one program can control the lights at a time. The README includes detailed notes on the device's communication protocol, discovered through reverse engineering and live testing against the firmware. It also documents macOS permission requirements and known limitations, such as the vendor protocol being private and subject to change. The full README is longer than what was shown.