Agent Micro is a local native macOS 14+ app for configuring and using a supported six-key CH552/CH57x macro pad with Codex and Claude desktop sessions. It is an independent open-source project and is not affiliated with or endorsed by OpenAI, Anthropic, SinLoon, Amazon, or Apple.
This repository contains the macOS app. Custom device firmware lives in
agent-micro-firmware.
The commercial pad's PCB, enclosure, factory firmware, and product images are
not part of either open-source project.
- Detects the verified factory USB device
0x1189:0x8890. - Configures six keys and encoder left/press/right using the vendored,
MIT-licensed
ch57x-keyboard-tool. - Supports keyboard chords, short sequences, media controls, mouse actions, German ISO, US, and UK layouts.
- Supports Agent Micro Raw HID protocol v2 firmware, including nine live bindings, real press/release actions, firmware status, emergency release-all, and six independent RGB LEDs.
- Assigns physical controls to existing Codex or Claude desktop sessions.
- Observes local agent states and drives optional per-key status lighting.
- Stores profiles and assignments locally; no project-operated cloud service, analytics, telemetry, or automatic updater is included.
See PRIVACY.md for the exact local files and permissions used.
The only custom-firmware target verified by this project is the SinLoon
SL2024502 sold under Amazon ASIN
B0DN9T9J75: six mechanical keys, one
rotary encoder, USB-C, and six addressable LEDs.
Visually identical pads can contain different controllers or pinouts. Never flash a device based on appearance alone. Check the factory VID/PID and follow the firmware repository's preflight procedure.
| USB identity | Support |
|---|---|
1189:8890 |
Verified factory CH57x configuration path |
4249:4287 |
Legacy experimental Agent Micro firmware |
1209:pending |
Reserved in the app design; enabled only after pid.codes allocation |
The legacy ID remains detectable for migration, but it is not a publicly allocated USB identity and must not be reused by new firmware releases.
Agent Micro does not publish an unsigned downloadable .app. Without a paid
Apple Developer account, the supported installation path is a local build:
xcode-select --install
brew install rust
git clone https://github.com/Krypt0ph0ne/agent-micro.git
cd agent-micro
./script/test.sh
./script/build_and_run.sh --verifyThe build script:
- verifies the vendored helper provenance marker and required license files;
- builds the Rust helper from source;
- builds the SwiftPM executable;
- creates
dist/Agent Micro.app; - uses a local Apple Development identity when available, otherwise ad-hoc signing.
Ad-hoc signing is suitable for a locally built app, but rebuilding can cause macOS to request Input Monitoring or Accessibility permission again.
For a local Universal 2 package, install the official rustup toolchain and
run:
./script/build_universal.shThis builds both the app and Rust helper for Apple Silicon and Intel. CI also compiles both architectures, but it does not publish the unsigned artifact.
./script/test.sh
swift run AgentMicroHIDProbe 90The live hardware test is opt-in:
AGENT_MICRO_HARDWARE_TEST=1 swift testEnable it only on a Mac connected to the exact verified test device.
- Input Monitoring receives private hardware triggers.
- Accessibility emits shortcuts selected by the user.
- Login Item is optional and keeps the menu-bar controller available.
Agent Micro can observe local approval requests. It never answers one automatically. Approve or decline is sent only if the user explicitly assigns that action to a hardware control and physically activates it.
Profiles and assignments are stored under:
~/Library/Application Support/Agent Micro
The first open-source build migrates data from the legacy
Application Support/CodexPad directory and matching CodexPad.*
preferences when the new destination does not already exist.
Codex and Claude integrations depend on local interfaces exposed by installed desktop/CLI versions. Changes in those applications can temporarily break session discovery or navigation without affecting basic macro-pad configuration.
The action catalogs were last verified against Codex desktop
26.715.21425 and Claude Desktop 1.22209.3 (catalog compatibility label
1.22+). These are verification baselines, not guarantees for future private
interfaces. See the verifiedAgainst fields in Resources/CodexActions.json
and Resources/ClaudeActions.json.
Build, preflight, flash, recovery, hardware limits, and the Raw HID wire format are documented in the separate firmware repository:
https://github.com/Krypt0ph0ne/agent-micro-firmware
The original factory application firmware could not be read back. Installing custom firmware therefore does not currently include a guaranteed return to the exact factory state.
Agent Micro is available under the MIT License. Bundled third-party components retain their own licenses as described in THIRD_PARTY_NOTICES.md.