<p align="center"><img src="https://raw.githubusercontent.com/stephenleo/OpenMicro/HEAD/assets/open-micro-banner.png" alt="OpenMicro가 게임 컨트롤러를 Claude Code 및 Codex CLI에 연결합니다." width="100%"></p>
하나의 컨트롤러로, 당신의 에이전트 워크플로우를 완성하세요.
Codex Micro를 모든 게임 컨트롤러 및 코딩 장치에 연결합니다.
60초 만에 시작하기
macOS, Node.js 22 이상, Claude Code 또는 Codex CLI, 그리고 연결된 컨트롤러가 필요합니다. OpenMicro는 macOS를 우선으로 개발되었으며, 다른 플랫폼은 아직 테스트되지 않았습니다.
npm i -g openmicro
openmicro claude
...
openmicro codex-app은 터미널 CLI 대신 Codex 데스크톱 앱을 구동합니다: 새 채팅 및 프롬프트 미리 채우기는 codex:// 딥 링크를 사용하며 (권한 불필요), 제출(Enter), 거부(Esc), 받아쓰기(Ctrl+Shift+D), D-패드 화살표, 그리고 Ctrl+U는 키 입력을 전송하며 터미널에 접근성 권한이 필요합니다. 스틱을 휘두르는 동작(stick-flick)으로 프롬프트를 미리 채우고, 제출 버튼을 눌러 전송합니다. 앱은 자동으로 실행되며 터미널에는 실시간 상태(컨트롤러, 액션, 에이전트 상태)가 표시됩니다.
사고 깊이 다이얼(오른쪽 스틱 휘두르기)은 일회성 설정이 필요합니다: 앱에는 "추론 노력 증가 (Increase reasoning effort)" 및 "추론 노력 감소 (Decrease reasoning effort)" 단축키가 할당되지 않은 상태로 제공되며, 이 할당은 계정 동기화되므로 OpenMicro가 대신 설정할 수 없습니다. Codex 앱에서 설정(Settings) → 키보드 단축키(Keyboard shortcuts)를 열고 "effort"를 검색한 다음, Increase는 ⌃⌥= (Control+Option+=, Windows에서는 Ctrl+Alt)에, Decrease는 ⌃⌥-에 할당하세요. 오른쪽 스틱을 휘두르면 작성기의 추론 노력이 단계적으로 변경됩니다. 이 조합은 앱의 Ctrl/Cmd +/-확대 단축키를 피합니다. 참고로, 앱 자체의 Decrease 단축키는 가장 낮은 노력 수준보다 한 단계 위에서 멈춥니다 (물리적으로 누를 때도 마찬가지). 이 경우 모델 선택기(model picker)를 사용하세요. 선택적으로 "모델 선택기 열기 (Open model picker)"도⌃⇧M에 할당할 수 있습니다. 오른쪽 스틱을 클릭하면 선택기가 열려 노력 변화를 관찰할 수 있습니다. 다른 조합을 할당했나요? OpenMicro 설정에서 thinking_depth를 일치하는 keys` 바인딩으로 재매핑하세요.
OpenMicro는 라이프사이클 후크(lifecycle hooks)를 자동으로 설치합니다. 만약 Codex가 후크 변경을 보고하면, Codex에서 /hooks를 열고 OpenMicro의 후크를 신뢰하십시오.
컨트롤러 지원은 정확한 장치와 연결 방식에 따라 달라집니다. 시작하기 전에 컨트롤러 호환성 가이드를 확인하거나 openmicro doctor를 실행하여 컨트롤러를 테스트하십시오.
기본 컨트롤 (Default controls)
| DualSense | GameSir G7 Pro |
|---|
| Default OpenMicro DualSense controls | Default OpenMicro GameSir G7 Pro controls |
텍스트 제어 참조 (Text control reference)
| Control | Action |
|---|
| south (✕ / A) | Submit or confirm |
| ... | |
Stick flicks fire after returning to center. Rotation gestures (rstick_cw/rstick_ccw, one step per quarter-turn) remain available for remapping. 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.
Claude Code에서 푸시 투 토크 설정하기 (Set up push-to-talk in Claude Code)
북쪽 버튼(△ / Y)은 Claude Code 받아쓰기를 시작하고 중지합니다. 이 기능에는 두 가지 설정이 필요합니다:
-
/voice로 음성 기능을 켭니다.
-
음성 모드를 tap으로 설정합니다. 기본 모드인 hold는 컨트롤러와 작동하지 않습니다. /config 화면에는 이 설정이 표시되지 않으므로, 직접 ~/.claude/settings.json에 추가해야 합니다:
"voice": { "enabled": true, "mode": "tap" }
그리고 Claude Code를 재시작합니다.
탭(tap) 모드에서는 $ riangle$ / Y 버튼을 한 번 눌러 듣기를 시작하고 다시 눌러 중지할 수 있습니다. '홀드(hold)' 모드에서는 키보드가 키를 누르고 있는 동안 보내는 반복적인 키 입력을 통해 Claude Code가 눌린 스페이스바(Space)를 감지합니다. 컨트롤러는 누를 때마다 하나의 스페이스를 전송하므로, Claude Code는 공백을 입력할 뿐 듣기 모드를 시작하지 않습니다.
작동 모습 보기
여섯 가지 핵심 상호작용에 대한 애니메이션 데모(녹화된 것이 아닌 렌더링된 것):
| |
|---|
| Lightbar status colors follow the focused session<br>상태 표시줄 (Status lightbar) — 실행 중, 대기 중, 완료, 오류 | Face buttons submit, interrupt, dictate, and start a new chat<br>명령 키 (Command keys) — ✕ ○ △ □ |
| ... | |
Xbox 360 컨트롤러 (유선)
유선 Xbox 360 컨트롤러에서도 동일한 상호작용이 가능합니다. 페이스 버튼은 위치별로 매핑됩니다(A = ✕, B = ○, Y = △, X = □). LB는 L1을 대체하며, 가이드(Guide) 버튼이 터치패드 역할을 수행합니다. OpenMicro는 360의 링 오브 라이트(Ring of Light)를 구동할 수 없기 때문에 세션 상태는 터미널에만 표시되며 상태 표시줄 데모는 없습니다.
⚠️ Xbox 360 face buttons submit, interrupt, dictate, and start a new chat<br>명령 키(Command keys) — A B Y X
Xbox 360 left-stick flick launches a workflow prompt<br>워크플로우 플릭(Workflow flick) — 스틱 업 = PR 검토
주요 기능 (What it gives you)
- 터미널 탭을 뒤지느라 에이전트에 응답할 필요가 없습니다.
- 스틱 플릭(stick flick)만으로 검토(review), 디버그(debug), 리팩터링(refactor), 테스트 워크플로우를 실행합니다.
- 하나의 컨트롤러에서 활성 세션 간 전환이 가능합니다.
- DualSense에서 포커스 세션 상태를 확인할 수 있습니다.
- 프로젝트별 워크플로우를 위해 6개 레이어를 재매핑(remap)할 수 있습니다.
- 최고 수준의 herdr 지원: 세션이 herdr 작업 공간 개요에 나타나며, 컨트롤러가 herdr 공간 및 에이전트를 구동합니다.
OpenMicro 기능 동등성 (OpenMicro feature parity)
✅ 지원됨 · ⚠️ 설정 필요 또는 최선 노력(best-effort) · — 검증된 등가물 없음
| Capability | Claude Code | Codex CLI |
|---|
| Launch and forward CLI arguments | ✅ openmicro claude | ✅ openmicro codex |
| ... | | |
레이어(Layers), 워크플로우, 탐색(navigation), 세션 전환은 OpenMicro 자체에서 처리합니다. 추측된 키 입력을 보내는 대신, Harness 고유의 누락 부분은 매핑되지 않은 상태로 남겨둡니다. 'Stop' 이벤트는 에이전트가 중지되었음을 의미하며, 성공을 보장하지는 않습니다.
OpenMicro는 첫 실행 시 ~/.openmicro/config.json 파일을 생성합니다. 이곳에서 바인딩(bindings), 레이어 색상, 워크플로우 프롬프트 텍스트를 편집할 수 있습니다. 유효하지 않은 설정은 파일 내용을 덮어쓰지 않고 시작을 중단시킵니다.
바인딩 키는 south나 dpad_up과 같은 버튼 또는 lstick_up, rstick_cw와 같은 제스처일 수 있습니다. 액션에는 accept, reject, push_to_talk, new_chat, thinking_depth, workflow, prompt, focus_session, layer, herdr_space, 그리고 원시(raw) keys가 포함됩니다.
세션 및 상태 (Sessions and status)
첫 번째 OpenMicro 프로세스가 컨트롤러를 소유하고 호스트(host) 역할을 합니다. 이후의 프로세스들은 클라이언트(client)로 등록하여, 하나의 컨트롤러로 여러 터미널 세션을 구동할 수 있습니다. 지원되는 패드에서는 기본적으로 터치패드 클릭이 포커스를 순환합니다.
DualSense의 경우, 라이트바는 포커스된 세션을 따라갑니다: 실행 중일 때는 파란색(blue), 대기 중일 때는 호박색(amber), 정지했을 때는 녹색(green), 오류가 감지되면 빨간색(red)을 띠며, 유휴 상태일 때는 어두운 흰색(dim white)입니다. 다섯 개의 플레이어 LED는 점유된 세션 슬롯을 표시합니다.
Herdr 통합 (Herdr integration)
OpenMicro는 herdr를 일급 환경(first-class environment)으로 취급합니다. 아래의 모든 기능은 herdr 외부 또는 herdr CLI가 없을 때는 자동적으로 비활성화(no-op)됩니다.
- 상태 보고 (State reporting). herdr 관리 패널 내에서 실행되는 래핑된 세션은 자신의 상태(작업 중/차단됨/유휴)를 herdr에 보고하므로, herdr 에이전트 패널에 표시됩니다. OpenMicro는 시작 시 해당 패널을 점유하고 종료 시 해제합니다.
- 공간 전환 (Space switching). L2 버튼은 herdr 워크스페이스(
이 진단 확인 도구는 컨트롤러 입력을 검사하며, DualSense의 경우 라이트바(lightbar)/플레이어-LED 출력도 처리합니다. 이 도구는 <vid>-<pid>-<transport>.json 보고서를 작성하며, 이는 test/fixtures/controllers/에 변경 없이 추가될 수 있습니다. 이후 CI 환경에서 캡처된 입력을 회귀 테스트(regression test)로 재실행합니다. 기여 단계에 대한 자세한 내용은 CONTROLLERS.md를 참조하십시오.
하드웨어 참고 사항 (Hardware notes)
- DualSense는 라이트바와 플레이어-LED 출력을 가진 유일한 컨트롤러입니다. DS4, Xbox, GameSir 컨트롤러는 입력 전용(input-only)이며, 일반적인 HID 입력은 보고서 레이아웃이 다양하기 때문에 최선의 노력(best-effort)에 의존합니다.
- DualSense는 5개의 플레이어 LED를 가지고 있으므로, 피드백은 최대 5개의 활성 세션 슬롯을 나타냅니다.
다른 하네스 추가 (Add another harness)
공개된 openmicro/harness API는 Harness 계약(contract)과 registerHarness()를 노출합니다. 이 계약을 구현하고, 검증된 CLI 등가물이 없는 액션에 대해서는 null을 반환한 다음, OpenMicro가 하네스를 해결하기 전에 이를 등록해야 합니다.
import { registerHarness } from 'openmicro/harness'
import type { Harness } from 'openmicro/harness'
...
현재 바이너리는 설정 파일에서 하네스 플러그인을 로드하지 않기 때문에, 서드파티 등록은 현재 작은 사용자 정의 진입점(custom entry point)이 필요합니다.
openmicro/controller API는 CLI를 시작하거나, 훅을 설치하거나, 구성을 생성하거나, PTY를 열거나, 서버에 바인딩하는 과정 없이 CLI가 사용하는 것과 동일한 컨트롤러 관리자(controller manager)를 노출합니다.
import { HidManager } from 'openmicro/controller'
import type { ControllerEvent } from 'openmicro/controller'
...
start()는 지원되는 장치를 검색하고 검증한 다음, connected 이벤트를 방출하고, 그 후 중복이 제거된(deduplicated) button 및 axis 상태 변경을 방출합니다. 스틱 축은 -1..1을 사용하며, 트리거는 0..1을 사용합니다. disconnected 이벤트가 발생하면 자동 재연결 폴링(automatic reconnect polling)이 이어집니다. start()와 stop()은 반복 호출해도 동일한 결과를 보장하는(idempotent) 함수입니다. 리소스를 해제하고 폴링 및 장치 소유권을 놓으려면 소비자가 종료될 때 stop()을 호출하십시오.
GUI 상태 로그 임베딩 (Embed GUI status logs)
부작용이 없는(side-effect-free) openmicro/logging API는 OpenMicro GUI CLI와 동일한 안전한 상태 메시지를 노출합니다:
import { actionStatus, agentStatus, controllerStatus } from 'openmicro/logging'
const lifecycle = controllerStatus(controllerEvent)
...
각 함수는 { message, tone } 또는 null을 반환하며, 에이전트 상태는 다음 중복 제거 호출(deduplication call)을 위해 stateKey도 반환합니다. 프롬프트 텍스트와 알 수 없는 원시 키 바이트는 절대 포함되지 않습니다. 출력, ANSI 스타일링, 성공적인 액션 확인, 그리고 반복/해제 억제(repeat/release suppression)는 임베딩 애플리케이션이 담당합니다.