{"slug": "show-hn-codex-micro-on-your-phone", "title": "Show HN: Codex Micro on Your Phone", "summary": "An unofficial open-source project lets users control the Codex Micro feature of the Codex desktop app on Mac from a phone over private Wi-Fi or Tailscale. The project, hosted on GitHub by maxxspotter, offers two methods: a Native Shim that emulates the real Codex Micro hardware for full feature parity, and a Standard Bridge for normal Codex launch with limited controls. It requires macOS 13+, Codex desktop, Node 20+, Swift 6, and a phone browser, and is not affiliated with OpenAI or Work Louder.", "body_md": "Important\n\nUnofficial project. Not affiliated with, endorsed by, or supported by OpenAI or Work Louder.\n\nUse your phone to **experience the Codex Micro feature** with the **Codex\ndesktop app on Mac**. This is an attempt to resemble the controls, lighting,\nand feel of the real\n[OpenAI × Work Louder Codex Micro](https://worklouder.cc/codex-micro).\n\n**For the Codex desktop app—not Codex CLI.** Everything runs between your Mac\nand phone over private Wi-Fi or Tailscale.\n\n## CodexMicroAppDemo.mp4\n\nWarning\n\nTested with **Codex desktop 26.715.52143 (build 5591)** on **macOS 26.5.1\n(build 25F80)** and one iPhone using Chrome. Other versions and setups are\nunverified.\nThe built-in diagnostics are designed to give an AI coding agent enough\ninformation to fix small machine-specific issues.\n\n**After a Codex update:** rerun `make setup`\n\n. The adapters fail visibly if\nCodex changed an integration point; an AI coding agent can follow the short\n[update repair playbook](/maxxspotter/codex-micro-app/blob/main/docs/AGENT_SETUP.md#after-a-codex-desktop-update).\n\n**You need:** macOS 13+, Codex desktop, Node 20+, Swift 6, and a phone browser.\n\n```\nmake setup\n```\n\n**That is the only project command you need.** It explains both connection\nmethods, checks prerequisites and permissions, builds the app, starts the Mac\nside, and opens a QR code. Scan it with your phone.\n\nKeep the Terminal window open while using the controller. The first clean build can take about 45 seconds.\n\nTip\n\nPrefer an AI agent? Give it this repository and say:\n\n**“Download https://github.com/maxxspotter/codex-micro-app, run the guided\nsetup, explain both connection methods and every permission, then help me\nverify the phone controller. Keep everything local.”**\n\nThe phone UI is the same either way. The difference is how the Mac delivers its inputs to Codex.\n\nThe **Native Shim** method adapts Marcel Pociot’s MIT-licensed\n[Codex Micro Stream Deck emulator](https://github.com/mpociot/codex-micro-stream-deck-emulator).\n\n| Method | How it works | One-line tradeoff |\n|---|---|---|\nNative Shim — recommended(detected inside Codex) |\nCodex itself shows a connected Codex Micro, as if the real device were attached. Phone inputs and lights use Codex’s native hardware channel. | Best feature parity, but Codex must launch through the shim. A Codex update may need a small compatibility fix that an AI coding agent can usually make from the built-in diagnostics. |\nStandard Bridge(not detected as Micro hardware) |\nCodex does not show a connected Micro. A separate local Mac helper reads Codex state and operates supported controls for the phone. | Normal Codex launch, but some controls are more limited and UI changes can affect them. |\n\nA phone webpage cannot present itself to a Mac as a USB/HID device. Without a device, Codex does not open its native Codex Micro input and lighting channel.\n\nThe Native Shim presents a **local synthetic Codex Micro** to the Codex process.\nThat lets Codex handle task-key colors, the configurable knob, joystick, MIC,\nand command keys like real hardware. It does not patch the installed Codex\napplication or task data on disk.\n\nIts original license is preserved in\n[ apps/micro-shim/THIRD_PARTY_LICENSE.txt](/maxxspotter/codex-micro-app/blob/main/apps/micro-shim/THIRD_PARTY_LICENSE.txt).\n\nNote\n\n**If Codex is already open:** Native Shim asks Codex to quit, waits, and\nrelaunches it once with the shim attached. Save or send unfinished composer\ntext first. Pressing `Control-C`\n\nstops the shim-launched Codex; reopen Codex\nnormally from the Dock to leave shim mode. Standard Bridge does not restart\nCodex.\n\nYou do not need these for first setup. They are shortcuts for repeat runs or AI agents:\n\n| Command | Result |\n|---|---|\n`make serve-shim` |\nStart the recommended Native Shim |\n`make serve` |\nStart the Standard Bridge |\n`make stop-shim` |\nStop only this repository’s shim processes |\n`make stop` |\nStop only this repository’s standard bridge |\n\nAfter the first Mac state arrives, the PWA header and **OPTIONS** screen say\n**Native Shim**, **Standard Bridge**, or **Demo**, so the active method is not\nimplicit.\n\n**Easiest:** Mac and phone on the same private Wi-Fi.**Different networks:** put both devices on the same private Tailscale tailnet. Never use Funnel or a public tunnel.- Keep the Mac awake, unlocked, and connected while controlling Codex.\n\nWant to explore without touching Codex? Run `make demo`\n\nand add `?demo=1`\n\nto\nthe shown URL.\n\nNote\n\n**Native Shim lets Codex own the mappings.** The table shows the current\nnative layout. Open **Codex → Settings → Codex Micro** to choose **Agent\nkeys** and **Knob** behavior; the phone follows those settings automatically.\nThe other phone keys mirror the native layout shown there. Standard Bridge\nperforms the listed actions through the Mac helper.\n\nTip\n\n**Turn up the phone volume for the mechanical clicks. Browser haptics are\nused only when the phone exposes them.**\n\n| Off | White | Blue | Green | Amber | Red |\n|---|---|---|---|---|---|\n| Unassigned | Idle | Working | Finished, unread | Needs input | Failed |\n\nThe selected task pulses. The frame follows its color. Native Shim receives these colors from Codex’s hardware-lighting channel; Standard Bridge derives them from verified Codex task state.\n\n| Prompt | Native Shim | Standard Bridge | Why |\n|---|---|---|---|\nMac incoming connections |\n✓ | ✓ | Phone reaches the private local bridge on port `48321` |\nChrome Local Network |\n✓ | ✓ | Phone reaches the Mac |\nCodex microphone |\nOptional | Optional | MIC uses Codex’s Mac microphone—not the phone webpage |\nMac Accessibility |\n— | ✓ | Standard Bridge uses named controls and verified key events—never screen coordinates |\nTerminal Automation |\nSometimes | — | macOS may ask before Terminal can quit and relaunch Codex for shim mode |\n\nNative Shim injects into Codex’s local `node-hid`\n\nlayer, so Codex’s physical\n**Input Monitoring** indicator may remain “Not granted.” That permission is for\na real USB/HID device and is not required by this shim path.\n\nIt should **never** ask for your OpenAI password, API key, Full Disk Access,\nscreen recording, contacts, photos, or phone microphone.\n\nFor Standard Bridge, setup checks the exact **Codex Micro Phone Bridge** app\nbefore starting. If Accessibility is missing, it opens the correct macOS page\nand waits for you to enable it. A source-code rebuild can require one new grant;\nordinary restarts of the same build reuse it.\n\nNative Shim sends hardware events and follows **Codex → Settings → Codex\nMicro**. Standard Bridge expects these Codex defaults:\n\n| Phone control | Codex shortcut |\n|---|---|\n| Dial tap | `Control-Shift-M` |\n| Joystick ↓ | `Command-B` |\n| Joystick ← / → | `Command-[` / `Command-]` |\n\nIf you changed them, restore the defaults shown in **Codex → Settings →\nKeyboard shortcuts**. `make diagnose`\n\nreports incompatibilities.\n\nOn the tested setup, Native Shim connects as a Codex Micro and carries task lighting plus phone inputs through Codex’s hardware path. Standard Bridge remains available when users do not want process-level hardware emulation.\n\nThere is room to improve feature parity—for example, configurable buttons—and smooth out rough edges. Further work will depend on whether people find it useful.\n\n- Mac only; Codex desktop updates can break either internal adapter.\n- Update breakage is detected on a best-effort basis; compatibility code is never rewritten automatically or allowed to guess against a changed Codex UI.\n- Native Shim depends on Codex’s current Electron/\n`node-hid`\n\nloading behavior. - Split and approval variants need broader real-world testing.\n- Browser PWA installation, haptics, and background reconnect vary.\n- Local traffic is authenticated HTTP, not TLS. Use trusted Wi-Fi or private Tailscale—never expose the port publicly.\n\n- No analytics, ads, hosted backend, or cloud relay.\n- Phone traffic stays between your phone and Mac.\n- The phone receives six generic slots and controller state—not task titles, prompts, responses, internal IDs, raw Codex events, or credentials.\n- Pairing sessions expire after 30 days.\n- Native Shim changes only the Codex process it launches; no Codex files are patched on disk.\n\n[Privacy details](/maxxspotter/codex-micro-app/blob/main/PRIVACY.md) · [Security model](/maxxspotter/codex-micro-app/blob/main/SECURITY.md)\n\n``` php\nflowchart LR\n    PHONE[\"Phone PWA\"] <-->|\"Private Wi-Fi or Tailscale<br/>paired local session\"| MAC[\"Mac Swift companion\"]\n    MAC --> SAFE[\"Small privacy-safe<br/>state projection\"]\n    SAFE --> PHONE\n    MAC --> CHOICE{\"Connection method\"}\n    CHOICE -->|\"Native Shim\"| SOCKET[\"Private Unix sockets\"]\n    SOCKET <--> HID[\"Synthetic Codex Micro<br/>node-hid shim\"]\n    HID <--> CODEX[\"Codex desktop\"]\n    CODEX -->|\"Native task lighting\"| HID\n    CHOICE -->|\"Standard Bridge\"| ADAPTER[\"Verified Codex adapter\"]\n    ADAPTER <--> IPC[\"Codex local IPC<br/>live state + settings\"]\n    ADAPTER <--> SERVER[\"Codex app-server<br/>supported task operations\"]\n    ADAPTER --> META[\"Read-only local metadata<br/>pins + verification\"]\n    ADAPTER --> AX[\"macOS Accessibility<br/>named controls only\"]\n    IPC <--> CODEX\n    SERVER <--> CODEX\n    META --> CODEX\n    AX --> CODEX\n```\n\nThe phone never talks directly to Codex. It sends only allowlisted actions to the Mac companion. Both methods return the same small, versioned phone state. Native Shim gets hardware input and lighting from Codex’s Micro channel; Standard Bridge performs one action and reports success only after observing the expected result.\n\n``` php\nflowchart LR\n    PRE[\"Read real state\"] --> ACT[\"Perform one<br/>allowlisted action\"]\n    ACT --> CHECK{\"Expected result<br/>observed?\"}\n    CHECK -->|Yes| OK[\"Verified success\"]\n    CHECK -->|No| FAIL[\"Visible failure<br/>state stays honest\"]\n```\n\nTechnical details: [Architecture](/maxxspotter/codex-micro-app/blob/main/docs/ARCHITECTURE.md) ·\n[Protocol](/maxxspotter/codex-micro-app/blob/main/docs/PROTOCOL.md) · [AI-agent setup](/maxxspotter/codex-micro-app/blob/main/docs/AGENT_SETUP.md)\n\n| Command | Purpose |\n|---|---|\n`make setup` |\nGuided method choice, build, and start |\n`make diagnose` |\nRead-only Standard Bridge compatibility checks |\n`make demo` |\nOffline scripted controller |\n`make shim-test` |\nHardware-free shim protocol test |\n`make check` |\nLint, tests, browser checks, and release build |\n\nFull credit for the original Codex Micro concept, hardware, software behavior,\nand product design goes to **OpenAI and Work Louder**:\n[official OpenAI guide](https://learn.chatgpt.com/docs/features/codex-micro) ·\n[official Work Louder product page](https://worklouder.cc/codex-micro).\n\nNative hardware-emulation work is adapted from\n[Marcel Pociot’s Codex Micro Stream Deck emulator](https://github.com/mpociot/codex-micro-stream-deck-emulator)\nunder the MIT License.\n\nCode is provided under the [MIT License](/maxxspotter/codex-micro-app/blob/main/LICENSE). **Codex, Stream Deck, Work\nLouder, Codex Micro, OpenAI, ChatGPT, and related names and marks are trademarks\nof their respective owners.** This license does not grant rights to third-party\nmarks, product designs, trade dress, or official imagery.\n\nSee [NOTICE.md](/maxxspotter/codex-micro-app/blob/main/NOTICE.md).", "url": "https://wpnews.pro/news/show-hn-codex-micro-on-your-phone", "canonical_source": "https://github.com/maxxspotter/codex-micro-app", "published_at": "2026-07-20 20:53:35+00:00", "updated_at": "2026-07-20 21:23:45.553169+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools"], "entities": ["OpenAI", "Work Louder", "Codex Micro", "Codex desktop", "maxxspotter", "Marcel Pociot", "GitHub", "Tailscale"], "alternates": {"html": "https://wpnews.pro/news/show-hn-codex-micro-on-your-phone", "markdown": "https://wpnews.pro/news/show-hn-codex-micro-on-your-phone.md", "text": "https://wpnews.pro/news/show-hn-codex-micro-on-your-phone.txt", "jsonld": "https://wpnews.pro/news/show-hn-codex-micro-on-your-phone.jsonld"}}