Codex Command Center Adapters

An open-source, vendor-neutral hardware control surface adapter connecting AI Coding Agents to programmable tactile hardware on macOS. Seamlessly monitor live agent tasks, perform tactile approvals, inject draft thoughts, and dictate voice prompts across physical decks like Elgato Stream Deck MK.2, Logitech MX Creative Console, and TourBox.

中文说明 (README_CN.md) | 日本語 (README_JP.md) | Roadmap | Contributing

---

Live Surface & Hub Preview

Left: Multi-Agent Hub & Launchpad (Default Profile launching Codex, Google AGY, DeepSeek/DSH, Claude, OpenCode, Ghostty, Obsidian).
Right: Active 5×3 Command Center Surface (Multi-project monitoring XVK_PM & AIM_PM, dynamic state badges, and contextual action keys).

---

Supported & Planned Ecosystem

1. AI Coding Agent Providers

Agent CLI / Runtime	Status	Target Milestone	Capabilities Supported
OpenAI Codex (app-server / CLI)	Production	v0.1	Multi-project oversight, task slots, approval routing, voice dictation
Google AGY (Antigravity CLI)	In Progress	v0.2	Active thread mapping, tool call approvals, background run states
Anthropic Claude (Claude Code CLI)	Planned	v0.3	Session streaming, terminal tool approvals, in-place prompt injection
OpenCode (OpenCode Interpreter CLI)	Planned	v0.4	Repository workspace slots, execution lifecycle, task archiving
DeepSeek Harness (DeepSeek / DSH)	Planned	v0.5	Reasoning stream monitor, token progression, fast interrupt & approve

2. Physical Hardware Surfaces

Hardware Console	Status	Key Layout & Controls	Driver Transport
Elgato Stream Deck MK.2	Production	5×3 15-key LCD grid (2 project rows + 1 action row)	Stream Deck Plugin API (@elgato/streamdeck)
Logitech MX Creative Console	Planned (v0.6)	3×3 LCD Keypad + Analog Dial Console	Logitech Options+ Plugin / macOS Native
TourBox (Elite / Neo)	Planned (v0.7)	Tactile Knobs, Scroll Wheels & Custom Action Switches	TourBox Console API / Direct HID

---

Inspiration & Mission: Bridging to OpenAI Codex Micro

This project is inspired by and benchmarked against OpenAI Codex Micro — OpenAI's official hardware control interface for monitoring autonomous Codex agents.

Why this project exists

While Codex Micro demonstrates the ideal tactile companion for AI-assisted software engineering, broad developer access requires bringing those exact high-fidelity capabilities to widely-available third-party physical hardware:

• 🎛️ Universal Mental Model: Multi-project oversight, 4-task concurrent visibility per project, instant glanceable state colors (IDLE, WORKING, REVIEW, APPROVAL, DONE), and single-tap human-in-the-loop interventions.
• ⚡️ Native-Speed Responsiveness: Direct local JSON-RPC streaming and zero-latency state transitions.
• 🔓 Open & Multi-Agent: Vendor-neutral architecture connecting any programmable physical surface on macOS to OpenAI Codex, Google AGY, Anthropic Claude, OpenCode, and DeepSeek.

---

5×3 Stream Deck MK.2 Grid Layout

Key	Coordinate	Function / Action	Visual Indicator
A1	[0, 0]	Project 1 (XVK_PM) — Click to create new task	Teal card + NEW badge
A2–A5	[0, 1]..[0, 4]	Tasks 1–4 of Project 1 — Click to switch focus	Dark card + IDLE / WORKING / DONE / REVIEW
B1	[1, 0]	Project 2 (AIM_PM) — Click to create new task	Teal card + NEW badge
B2–B5	[1, 1]..[1, 4]	Tasks 1–4 of Project 2 — Click to switch focus	Dark card + IDLE / WORKING / DONE / REVIEW
C1	[2, 0]	Plan Mode — Focus app and toggle /plan	Solid Indigo + Plan glyph + Plan Mode
C2	[2, 1]	Dynamic Action (Approve / Go On)	Solid Green + Checkmark/Play + Approve/Go On
C3	[2, 2]	Dynamic Action (Reject / No Wait / Stop)	Solid Amber/Red + Pause/Stop/Cross + No Wait/Stop/Reject
C4	[2, 3]	Voice Input — Push-to-Talk & Hands-Free Toggle	Solid Purple/Red + Mic glyph + Voice/Listening
C5	[2, 4]	Back / Profile Switch — Exit to default profile	Solid Dark + Exit glyph + Back

---

Usage & Key Workflows

1. Read / Unread State Lifecycle (DONE vs IDLE)

• 🟢 DONE (Unread Completion): When a background task completes a turn and produces new output, the slot highlights in vibrant green with a checkmark badge.
• ⚪️ IDLE (Read & Ready): Tapping the slot marks the task as read, instantly returning it to neutral gray IDLE.
• Persistent Memory: Read timestamps are stored in ~/.codex/task_read_state.json.

2. Contextual Dynamic Action Keys (C2 / C3)

• During REVIEW / APPROVAL:
  • C2 Approve: Short press triggers native NSAlert confirmation modal; long press ($\ge 600\text{ms}$) executes immediately.
  • C3 Reject: Rejects execution or requests plan revision.
• During WORKING (Execution):
  • C2 Go On: Pre-fills "我觉得不错，请继续。" without hitting Enter so thoughts can be queued.
  • C3 Stop: Interrupts current generation.
• During IDLE (Idle Session):
  • C2 Go On: Pre-fills "我觉得不错，请继续。" in-place.
  • C3 No Wait: Pre-fills "我觉得有问题，请等一下。" in-place.

3. In-Place Draft Pre-fill & Anti-Jump Pattern

• Go On and No Wait paste directly into the active foreground window.
• Zero thread jumps: Never redirects URLs or refreshes the viewport.
• Safety buffer: Retains cursor at the end without sending Enter.

4. Machine-Readable State Protocol Example

{
  "project": "XVK_PM",
  "slotIndex": 0,
  "threadId": "thr_01J7K8M9N0PQR",
  "status": "REVIEW",
  "unread": true,
  "actionRouting": {
    "c2": { "action": "approve", "label": "Approve", "color": "#10B981" },
    "c3": { "action": "reject", "label": "Reject", "color": "#EF4444" }
  },
  "updatedAt": "2026-08-27T13:30:00Z"
}

---

Security, Privacy & Local Execution Boundary

• 🔒 100% Local IPC: All communications between Stream Deck, background adapters, and agent CLIs occur strictly over local loopback (127.0.0.1) or UNIX domain sockets. Zero telemetry or agent prompt data is sent to third-party cloud servers.
• 🛡️ macOS Accessibility Permissions: Voice dictation and window focusing use macOS Accessibility API (AXUIElement) locally. No keystroke loggers or background key interceptors are installed.
• 🛑 Human-in-the-Loop Safety: Dangerous command executions require physical button hold ($\ge 600\text{ms}$) or explicit native confirmation dialogs.

---

Quick Start & Local Setup

Prerequisites

• macOS 12+
• Node.js 20+
• Elgato Stream Deck app (v6.6+) & Stream Deck MK.2 hardware

Installation

# 1. Clone repository
git clone https://github.com/xxvk/codex-command-center-adapters.git
cd codex-command-center-adapters

# 2. Install dependencies
npm install

# 3. Build & bundle plugin
npm run plugin:bundle

# 4. Link plugin to Stream Deck
ln -s "$(pwd)/com.xxvk.codex-command-center.sdPlugin" "$HOME/Library/Application Support/com.elgato.StreamDeck/Plugins/"

# 5. Import profile (Double-click or import via Stream Deck Preferences)
open "com.xxvk.codex-command-center.sdPlugin/profiles/Codex Command Center.streamDeckProfile"

---

Troubleshooting & FAQ

Q1: Stream Deck buttons remain blank after installation

1. Ensure the Stream Deck Desktop app is running and permissions are granted.
2. Restart Stream Deck application: killall "Stream Deck" && open -a "Stream Deck".
3. Check plugin bundle build: npm run plugin:bundle.

Q2: Voice dictation (C4) does not trigger ChatGPT or Codex

Ensure Accessibility permissions are enabled for Stream Deck in System Settings > Privacy & Security > Accessibility.

---

Quality & Governance Standards

• 132 Automated Unit Tests: Run npm test.
• Strict Line-Count Limit: All handwritten source files strictly $\le 200$ lines (0 warnings, 0 hard cap violations). Run npm run check:lines.
• Pre-commit Gate: Run npm run check.

---

Documentation & Community

• 📖 Architecture Overview | Codex Protocol Boundary
• 🗺️ Roadmap | 中文路线图 (ROADMAP_CN.md)
• 🤝 Contributing Guidelines | Code of Conduct | Development Guide
• 🛡️ Security Policy | Threat Model
• 📜 Changelog | 中文更新日志 (CHANGELOG_CN.md)

---

License

Licensed under the Apache License, Version 2.0.