Orca Micro

An experimental Work Louder Codex Micro integration for Orca, by Jason Brashear / Web Dev Today.

Use the touch-selected layers on one macropad for different applications: ChatGPT on layer 1, Orca on layer 2, and a spare layer for whatever comes next.

Built on FreeMicro by Eli Benveniste. This is an MIT-licensed derivative, not a driver written from scratch. FreeMicro provides the device transport, lighting, input bridge, slot resolver, and most of this codebase. See credits and provenance.

Status: experimental, not plug-and-play yet

The profile imports into Work Louder Input and the Orca layer is editable. The command-line helper has successfully selected a live Orca terminal. However, the physical-button-to-Orca workflow and live RGB on the editable Orca layer have not been verified end to end. Do not treat passing unit tests as hardware certification.

Capability	Evidence / limitation
Three-layer profile import	Visually confirmed in Input 0.18.3
Device status over Bluetooth LE	Round trip confirmed on firmware 0.6.2
Orca workspace and terminal discovery	Confirmed against Orca 1.4.190
Exact terminal focus from a shell	Confirmed
Physical Smart Action buttons	Still needs validation; command consent and GUI PATH are known obstacles
Live agent RGB on the ordinary Orca layer	Implemented, not visually verified
Automatic login service and ChatGPT coexistence	Not yet acceptance-tested; keep lighting off initially

How it works

Buttons: keyboard → Work Louder Input Smart Action → freemicro orca-focus → Orca
Lights:  Orca CLI → background FreeMicro bridge → keyboard HID lighting

The importable JSON is configuration, not a running application. Input must be running to execute its command Smart Actions. The separate bridge is needed for experimental live status lighting, not for the six focus commands.

Only layer 1 uses KV_OAI_* keycodes. Input treats those as ChatGPT-managed and locks the layer. Layer 2 uses editable Smart Actions and ordinary keycodes. The touch sensor's normal layer cycling is separate from its long-hold communications mode for selecting a Bluetooth host or USB.

Requirements

• macOS; this integration has not been validated on Windows or Linux.
• Work Louder Codex Micro / compatible Creator Micro 2 hardware. The tested device reports VID:PID 303a:8360, firmware 0.6.2, over Bluetooth LE.
• Work Louder Input, Orca with its CLI installed, Python, Git, and pipx.
• Input's explicit consent to run command Smart Actions.
• Input Monitoring for direct HID access. Inherited synthetic-key features also require Accessibility. Permissions for a login daemon need separate verification.

Install this repository

The Python package and executable keep the upstream name freemicro for compatibility. Do not use pipx install freemicro to install Orca Micro; that installs the original PyPI package, not this derivative.

If you already use FreeMicro, back up its configuration and choose which installation should own the freemicro command before proceeding. Do not run two lighting bridges against the same device.

git clone https://github.com/webdevtodayjason/orca-micro.git
cd orca-micro
pipx install --editable .
freemicro --version
orca status --json

Install the checkout in a persistent development directory, not a temporary folder. Editable installs depend on that checkout staying in place.

Import and try the profile

1. Export your existing Work Louder profile as a backup.
2. Import ChatGPT-Orca-profile.json in Input, then select ChatGPT + Orca v2.
3. Verify the physical device is using that profile and its second layer; selecting a layer in an editor is not proof it is active on the device.
4. Review the six command Smart Actions and enable Input's command-execution consent only if you trust them.
5. With Orca open, test freemicro orca-focus 1 in a terminal, then press the corresponding physical key. Compare both results.

The six buttons choose stable workspace slots, not six permanently hardcoded terminal IDs. The dial and joystick are currently basic navigation controls; several lower keys are deliberately unassigned. Some basic keycode mappings still need physical validation. They are not a finished Orca command layout.

If the shell works but a physical button does nothing

First check Input's command permission and the active device profile. Next, run command -v orca and command -v freemicro. GUI apps often lack the shell's PATH. In each Smart Action, use the actual absolute paths, for example:

FREEMICRO_ORCA_COMMAND="/usr/local/bin/orca" "$HOME/.local/bin/freemicro" orca-focus 1

Those are examples, not universal paths. Repeat with slot numbers 1–6. An exported profile cannot know another person's installation paths. Simply starting the lighting daemon does not fix blocked or unresolved commands.

Lighting and automatic startup

Start with a bounded diagnostic run:

freemicro run --orca --dry-run --seconds 15

--dry-run suppresses FreeMicro key delivery, not configured lighting or Input's independent Smart Actions. Leave lighting disabled while checking the connection. See the detailed setup guide for the optional lighting and login-service procedure, caveats, and rollback.

AppSense linking is optional: in Input, link the Orca layer to the Orca app. Application links use local IDs and are not portable in the supplied export.

Known limitations / next work

• End-to-end physical input and live RGB validation are still outstanding.
• GUI command lookup currently needs an explicit path in some installations.
• The bridge polls the layer; this is not instantaneous or exclusive device ownership. Profile-index fencing, stale status handling, and shutdown/held-key behavior need more work before coexistence can be promised.
• State polling runs Orca CLI processes. Latency and larger workspace fleets have not been characterized.
• Focus commands do not yet report asynchronous switch failures reliably.
• Do not use the pad as an unattended approval mechanism. Generic Enter/Escape act on whatever currently has keyboard focus.
• Many inherited documents describe upstream FreeMicro's Claude Code workflow, not a verified Orca workflow. This README and docs/ORCA.md are the starting points for this project.

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q
.venv/bin/ruff check .

Tests disable hardware access. CI tests logic and packaging, not physical LEDs, Bluetooth reliability, macOS permissions, or Input's consent UI. See CONTRIBUTING.md and SECURITY.md.

For source updates, use git pull --ff-only in a clean checkout and reinstall the checkout if package metadata changed. Do not replace this install with the upstream PyPI distribution. No Orca Micro package is being published to PyPI.

Credits and license

• Eli Benveniste / FreeMicro: original application, protocol research, hardware transport, lighting, input, state engine, tests, and documentation.
• Jason Brashear / Web Dev Today: this Orca-focused derivative, integration, importable profile, and setup work.
• Stably / Orca contributors: the IDE and its public CLI/runtime interfaces.
• Work Louder: hardware, firmware, and the Input configuration application.
• OpenAI: the Codex Micro collaboration and original Codex experience.

MIT license; original notices are retained. This community project is not affiliated with or endorsed by Work Louder, OpenAI, or Stably.