# I Reverse-Engineered OpenAI's Codex Micro Keypad to Run Claude Code

- **Category:** AI
- **Date:** 2026-07-24
- **Read time:** 6 min

I bought an OpenAI Codex Micro Keypad, a six-key macro pad with RGB lights, a dial, and a thumbstick. It only talks to OpenAI's ChatGPT desktop app, and I only use Claude Code. So I had Claude Code reverse-engineer the device and open-sourced the result as FreeMicro (MIT): github.com/eliBenven/freemicro.

## The device

The Codex Micro Keypad presents as a vendor HID device (VID 0x303A, PID 0x8360). Its keys and LEDs do not emit standard scancodes, so without OpenAI's app it does nothing. Everything rides on a proprietary vendor channel.

## The approach

The vendor data rides on HID usage page 0xFF00, invisible to standard hidapi. On macOS that means IOKit for direct device access. Key presses came quickly; the LED protocols took longer. Synthetic keystrokes go back through the CGEvent framework. FreeMicro ships the first public reverse-engineered documentation of the protocol.

## What it does

Claude Code hooks feed a state engine (one state per project) that drives the lights. Each of the six agent keys maps to a project directory: blue means working, amber means waiting on you, green means done, dark means idle. Keys are pinned to the directory, not a session, so the mapping survives restarts.

## Beyond what OpenAI shipped

Once the lights and keystrokes were understood, I added features the official app lacks: project-aware key binding, eight action types, custom LED effects (snake, rainbow, breath, gradient), a coexistence mode to run alongside the ChatGPT app, a local visual editor with no npm or Electron, Bluetooth with battery reporting, and idle decay. Install on macOS with pipx (`pipx install git+https://github.com/eliBenven/freemicro` then `freemicro start`). macOS only for now (IOKit), tested on firmware v0.4.1.