One controller. Your agent workflow.

Bring Codex Micro to any gaming controller and coding harness

Start in 60 seconds

You need macOS, Node.js 22 or newer, Claude Code or Codex CLI, and a connected controller. OpenMicro is macOS-first; other platforms are not yet tested.

npm i -g openmicro

openmicro claude # or just: openmicro
openmicro codex

OpenMicro installs its lifecycle hooks automatically. If Codex reports that its hooks changed, open /hooks in Codex and trust the OpenMicro hooks.

Controller support depends on the exact device and connection. Check the controller compatibility guide before you start, or run openmicro doctor to test your controller.

Default DualSense controls

Text control reference

Stick flicks fire after returning to center; each quarter-turn steps thinking depth once. Hold L1 with south, east, west, north, d-pad up, or d-pad down to select one of six layers. The first layer ships with these defaults; the other five start empty. Other controls are unbound by default and remappable.

Voice and thinking-depth support varies by harness; see OpenMicro feature parity.

What it gives you

• Respond to agents without hunting through terminal tabs.
• Launch review, debug, refactor, and test workflows with a stick flick.
• Switch among active sessions from one controller.
• See focused-session state on DualSense.
• Remap six layers for project-specific workflows.
• First-class herdr support: sessions appear in the herdr workspace overview, and the controller drives herdr spaces and agents.

OpenMicro feature parity

✅ supported · ⚠️ setup required or best-effort · — no verified equivalent

Layers, workflows, navigation, and session switching are handled by OpenMicro itself. Harness-specific gaps are left unmapped instead of sending guessed keystrokes. A Stop event means the agent stopped; it does not guarantee success.

Configure controls and workflows

OpenMicro creates ~/.openmicro/config.json on first run. Edit bindings, layer colors, and workflow prompt text there. Invalid configuration stops startup without overwriting the file.

{
  "layers": [
    {
      "name": "Layer 1",
      "color": { "r": 255, "g": 255, "b": 255 },
      "bindings": {
        "south": { "type": "accept" },
        "lstick_up": { "type": "workflow", "presetId": "review-pr" },
        "rstick_cw": { "type": "thinking_depth", "delta": 1 }
      }
    },
    { "name": "Layer 2", "color": { "r": 160, "g": 32, "b": 240 }, "bindings": {} },
    { "name": "Layer 3", "color": { "r": 0, "g": 255, "b": 255 }, "bindings": {} },
    { "name": "Layer 4", "color": { "r": 255, "g": 140, "b": 0 }, "bindings": {} },
    { "name": "Layer 5", "color": { "r": 255, "g": 20, "b": 147 }, "bindings": {} },
    { "name": "Layer 6", "color": { "r": 255, "g": 255, "b": 0 }, "bindings": {} }
  ],
  "workflows": {
    "review-pr": "Review this PR for correctness, security, and style issues."
  }
}

Binding keys can be buttons such as south and dpad_up, or gestures such as lstick_up and rstick_cw. Actions include accept, reject, push_to_talk, new_chat, thinking_depth, workflow, prompt, focus_session, layer, herdr_space, and raw keys.

Sessions and status

The first OpenMicro process owns the controller and becomes the host. Later processes register as clients, so one controller can drive several terminal sessions. On supported pads, touchpad click cycles focus by default.

On DualSense, the lightbar follows the focused session: blue while executing, amber while waiting, green when stopped, red on a detected error, and dim white while idle. The five player LEDs show occupied session slots.

Herdr integration

OpenMicro treats herdr as a first-class environment. Everything below is automatic and a no-op outside herdr or when the herdr CLI is absent.

• State reporting. A wrapped session running inside a herdr-managed pane reports its state (working/blocked/idle) to herdr, so it shows up in the herdr agents panel. OpenMicro claims the pane at startup and releases it on exit.
• Space switching. L2 cycles through herdr workspaces ("spaces") and back to local mode.
• Agent cycling. While a space is selected, the touchpad cycles focus across that space's agents instead of local sessions.
• Focus follows herdr. Voice and keystrokes retarget to the agent focused in herdr — switching spaces or agents never spills input into a session in another space.

Test or contribute a controller

openmicro doctor

The diagnostic checks controller input and, on DualSense, lightbar/player-LED output. It writes a <vid>-<pid>-<transport>.json report that can be added unchanged to test/fixtures/controllers/; CI then replays the captured inputs as a regression test. See CONTROLLERS.md for supported devices, connection-specific notes, and contribution steps.

Hardware notes

• DualSense is the only controller with lightbar and player-LED output. DS4 and Xbox controllers are input-only; generic HID input is best-effort because report layouts vary.
• DualSense has five player LEDs, so feedback represents at most five active session slots.
• Xbox parsing currently supports its wired USB report layout, not Bluetooth.

Add another harness

The public openmicro/harness API exposes the Harness contract and registerHarness(). Implement the contract, return null for actions without a verified CLI equivalent, and register it before OpenMicro resolves the harness.

import { registerHarness } from 'openmicro/harness'
import type { Harness } from 'openmicro/harness'

const myHarness: Harness = {
  kind: 'my-cli',
  command: 'my-cli',
  buildArgs: (args) => args,
  installHooks: () => ({ changed: false, trustNotice: null }),
  stateForHookEvent: () => null,
  resolveAction: (action) => {
    if (action.type === 'accept') return { bytes: '\r' }
    if (action.type === 'reject') return { bytes: '\x1b' }
    if (action.type === 'prompt') return { bytes: `${action.text}\r` }
    if (action.type === 'keys') return { bytes: action.bytes }
    return null
  },
}

registerHarness(myHarness)

The binary does not load harness plugins from configuration yet, so a third-party registration currently needs a small custom entry point.

Troubleshooting

Controller is connected but OpenMicro cannot ope