# microdex

> An iPhone app that remotely controls the Codex desktop app running on your Mac

- Repository: https://github.com/Kappaemme-git/microdex
- Category: Coding agents & dev tools
- Stars: 68 · Forks: 8 · Language: JavaScript · License: not stated
- Experience: Some experience
- Page: https://ir.adyog.com/repos/kappaemme-git/microdex/

Codex runs on your Mac, so you normally have to sit at it to watch tasks or approve actions. Microdex puts a control panel on your iPhone, modelled on the layout of the Codex Micro hardware: six task keys, six command keys, a joystick and a reasoning dial. It is an independent community project, not made by OpenAI or Work Louder.

It has two parts. A CLI called microdex-cli runs a bridge on the Mac. The bridge starts the Codex App Server that ships with the Codex app and talks to it over a local connection. The iPhone app pairs with the bridge by scanning a QR code. Traffic goes through a Cloudflare relay, so the phone works on Wi-Fi or mobile data and you open no router ports.

The README says commands and task state are encrypted between phone and Mac, so the relay only sees ciphertext. The bridge does not ask for your OpenAI credentials. An optional native mode makes Codex see a synthetic Micro device, for closer parity with the physical keyboard.

## What it does

- **Remote task control**: Reads your six most recent Codex tasks, sends or steers messages, follows live task state, and opens a task on the desktop.
- **Approvals and settings**: Resolve approval requests, fork conversations, and change Fast Mode and reasoning level for the selected task from the phone.
- **Encrypted pairing**: Each pairing creates a new 256-bit key carried in the QR URL fragment. The pairing code expires after 10 minutes, and `microdex revoke-all` resets every paired phone.
- **Background bridge on the Mac**: `microdex setup` installs a macOS LaunchAgent so the bridge starts at login and keeps the same relay address across restarts.
- **Explore without a Mac**: A local walkthrough with fictional tasks lets you try the interface before pairing. It contacts no Mac or server.

## What you could build

- Approve a Codex permission request from your phone while away from your desk.
- Send a follow-up instruction to a running Codex task from the couch or on the go.
- Switch Fast Mode or reasoning level on a task without going back to the Mac.
- Watch live status of your recent Codex tasks over mobile data.
- Emulate a Codex Micro with the optional native mode, with no hardware.

## Who it's for

Mac users who already have Codex installed and logged in, an iPhone, and some comfort with Node.js and the terminal.

## Get started

You need macOS, Node.js 20.19+, and Codex installed and logged in. Install the CLI and run setup, which shows a pairing QR. Then open the Microdex app on your iPhone, tap Pair Mac and scan the code.

```
npm install --global microdex-cli@latest
```
```
microdex setup
```

Tags: codex, ios, react-native, remote-control, mobile