Show any LLM coding agent's live status on the RGB keys of a QMK macropad — a real Codex Micro, a Work Louder Micro, a DOIO, or a 3D-printed DIY build — on Linux, from the terminal/CLI.
The device's keys (accept, reject, push-to-talk, …) already work with any app, because they are ordinary USB-HID keystrokes. The one thing that is locked down is the status lights: on the real device they only light up via the ChatGPT desktop app, and every open clone so far copies that same limitation — desktop app only, macOS/Windows only, Codex only. This project is the missing piece: an open, Linux, any-LLM path to those lights.
Not a reverse-engineering of the closed desktop protocol, and not a kernel driver. It's a small user-space bridge plus open QMK firmware you flash yourself — so it works over SSH, in a headless box, and with whatever agent you run.
agent runner ──hook──► codexmicro-notify <agent> <status>
│ (unix socket)
▼
codexmicrod ──32-byte report──► /dev/hidraw* ──► QMK raw_hid_receive() ──► RGB
Three independent components, joined by one shared contract
(codexmicro_wire.h — the status vocabulary + report
format):
- Firmware — a ~30-line QMK handler you flash onto the pad.
- Daemon —
codexmicrod, a user-space C program that turns status into device reports overhidraw. - Adapters — per-LLM shims that report status by running
codexmicro-notify.
| Piece | State |
|---|---|
Wire protocol (codexmicro_wire.h) |
✅ done |
| Daemon + notify client | ✅ done (loopback, sim, hidraw backends) |
| QMK firmware handler + flashing guide | ✅ done |
| Install / device-setup tooling | ✅ done (install.sh, codexmicro-doctor, codexmicro-flash) |
Adapters: Claude Code, Codex CLI, generic (codexmicro-run) |
✅ done |
| Connect-your-LLM guide | ✅ done (adapters/README.md) |
| More first-class adapters (Ollama, aider…), real-hardware bring-up | ⏳ see ROADMAP |
The whole pipeline is testable with no hardware — loopback (text) or
sim (a live colored panel of the six keys).
Requirements: Linux, gcc + make (for the daemon); the
QMK CLI only for flashing (step 2).
# 1. build + install the daemon and tools (systemd user service)
./install.sh
# 2. flash your pad, then grant it access
codexmicro-flash # generates a keymap from the board default + flashes
sudo codexmicro-doctor # auto-detects the pad and writes its udev rule
# 3. connect your LLM (example: Claude Code)
# merge adapters/claude-code/hooks.json into ~/.claude/settings.json
# 4. start it
systemctl --user enable --now codexmicrodTry it with no hardware first:
make
./codexmicrod --backend loopback & # prints each report; or run
# ./codexmicrod --backend sim --label 0=frontend # a live colored panel + legend
codexmicro-notify 0 thinking
codexmicro-notify 1 doneThe daemon and protocol are provider-neutral; the only place an LLM is named is the adapter. Three tiers cover everything:
- First-class adapters for runners with a hook system (Claude Code ✅,
Codex CLI ✅) — a tiny config maps lifecycle events to
codexmicro-notify. - Generic path — any tool or script calls
codexmicro-notify 0 thinkingdirectly. One line makes any LLM work. - Wrapper —
codexmicro-run <cmd>for tools with no hooks.
→ Connect your LLM in ~2 minutes
| Path | Role |
|---|---|
codexmicro_wire.h |
Shared contract: status vocabulary, colors, report format |
codexmicrod.c |
Daemon: socket intake → color → device backend |
codexmicro_notify.c |
One-shot client adapters call to report status |
firmware/ |
QMK raw_hid_receive handler + flashing guide |
adapters/claude-code, adapters/codex-cli |
First-class hook adapters |
adapters/generic |
The universal path for any other LLM/tool |
codexmicro-run |
Wrapper that reports status for a hook-less tool |
codexmicro-flash |
Generate a keymap from the board default and flash |
codexmicro-doctor |
Auto-detect the pad and write its udev rule |
install.sh, systemd/, udev/ |
User-service install + device access |
MIT © Manisha Chand.