Build your own USB macro pad for coding agents: 13 keys, joystick, encoder, RGB status, and CircuitPython firmware for Raspberry Pi Pico / RP2040.
13 keys · joystick · encoder · touch · USB HID · no cloud
Build it · See the wiring · Read the firmware · Share an idea
Languages: English · العربية · 简体中文 · Español
Open Codex Micro is a compact, repairable macro pad for agentic coding workflows. Give repeated actions a physical place: start a task, pause it, approve a change, move between sessions, show a diff, or return focus to the terminal.
It is a weekend-buildable alternative for people who want the feeling of a dedicated coding control surface without a closed device, vendor daemon, or subscription.
This is an independent open-source project. It is not made by, endorsed by, or affiliated with OpenAI or Work Louder. “Codex” is used here to describe a workflow and the project does not reproduce proprietary firmware, software, or industrial design.
| I want to… | Start here |
|---|---|
| Build one this weekend | hardware/README.md |
| Flash the reference firmware | firmware/circuitpython/README.md |
| Change the shortcuts | firmware/circuitpython/config.py |
| Pick a layout | docs/PROFILES.md |
| Understand the design | docs/design.md |
| Report a problem | Open an issue |
- 13 hot-swappable or soldered macro keys
- A two-axis joystick for navigation and a press action
- A rotary encoder with push switch
- A capacitive touch input for a second layer
- Per-key or strip RGB status lighting
- USB HID output, so it works without a special driver
- A plain-text configuration that can be edited without recompiling
- Optional serial events for a desktop companion or your own integration
| Small enough for a corner of your desk | Open enough to repair | Flexible enough to keep |
|---|---|---|
| RP2040 + USB-C power | Through-hole or hand-wired prototype | Shortcuts live in one editable file |
| 13 direct GPIO buttons | No account or telemetry | Works with terminals, editors, and browsers |
| One bright status pixel | Common, replaceable parts | Add your own layout profiles |
What happens when you press a control?
Each button sends a normal USB keyboard shortcut. The encoder sends a previous
or next action, the joystick sends controlled directional repeats, and the
optional touch input changes the visual state. Nothing needs an account or a
network connection. Your shortcut choices live in one readable file:
config.py.
Safety gate before the first plug-in
Start with the 13 buttons only. Confirm USB HID works, then add the encoder, joystick, touch input, and NeoPixel one at a time. Use 3.3 V-safe analog output, keep the joystick centered during boot, and never connect 5 V to an RP2040 GPIO.
The reference firmware targets a Raspberry Pi Pico or another RP2040 board running CircuitPython. The design is deliberately simple enough to adapt to an Arduino-compatible board, a Pi Zero running Linux, or a custom PCB.
- Gather the parts listed in
hardware/README.md. - Install CircuitPython on a Raspberry Pi Pico and copy the libraries in the
CircuitPython bundle:
adafruit_hid,neopixel, and the built-in modules used by the firmware. - Copy
firmware/circuitpython/code.pyandconfig.pyto the board'sCIRCUITPYdrive. - Wire the controls according to the pin table in the hardware guide.
- Edit
config.pyto change shortcuts and LED colors. - Plug the board into USB. It appears as a normal keyboard and works with your terminal, editor, browser, or Codex client.
The default layout uses ordinary keyboard shortcuts rather than a private API.
That keeps the pad useful with a terminal, editor, browser, or Codex client.
The complete first-build checklist is in docs/BUILD-CHECKLIST.md.
The reference profile gives each key a job without pretending that every software client has the same commands:
[ new task ] [ send ] [ pause ] [ approve ] [ reject ]
[ retry ] [ stop ] [ next ] [ previous ] [ show diff ]
[ terminal ] [ focus ] [ help ] ◉ encoder ◎ joystick
Treat these as labels, not fixed product behavior. Map them to shortcuts that already exist in your own tools.
| Path | Purpose |
|---|---|
firmware/circuitpython/ |
Ready-to-copy RP2040 firmware |
hardware/ |
Wiring, bill of materials, and enclosure notes |
host/ |
Optional serial companion utilities |
docs/ |
Design decisions and extension points |
examples/ |
Starter profiles for different workflows |
.github/ |
Issue forms that make bug reports easier to reproduce |
This repository is authored by Qusai Al Bahri with help from AI tools for brainstorming, drafting, and review. Human testing, hardware safety checks, and the final choice of shortcuts remain the builder's responsibility.
Project home and author: albahri.org
The aim is practical openness: readable code, ordinary components, no account, no telemetry, and no claim that a DIY build is an exact copy of a commercial device. Build one, improve it, and share your layout.
This is a reference prototype, not a finished consumer product. The firmware has been syntax-checked but needs physical testing on the builder's exact board, switches, joystick, encoder, and CircuitPython version. The default shortcuts are intentionally generic and should be reviewed before mapping any destructive action.
- RP2040/CircuitPython reference firmware
- Hardware pinout and first-build checklist
- Safer joystick calibration and repeat handling
- Printable case and switch plate
- Per-key RGB expansion
- Community layout gallery
Code and documentation are released under the MIT License. Hardware files are
released under CERN-OHL-S-2.0 where applicable; see LICENSE and
hardware/README.md for the boundary between software and hardware material.
open-source macro pad, Raspberry Pi Pico macro pad, RP2040 keyboard, CircuitPython HID, agent workflow controller, coding assistant keyboard, programmable keypad, open Codex Micro alternative, DIY developer tool, Qusai Al Bahri, albahri.org