Codex-Micro

KO | EN

gitlite — search

#ai-agents #typescript #ai #dsh-plugin #deepseek-harness #cli #open-source #codex #ios #claude-code #developer-tools #python

★ 12 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Codex-Mirco

A virtual Codex Micro controller, built with Codex.

[English](README.md) · [繁體中文](README.zh-TW.md)

Repository: [Toolsai/Codex-Micro](https://github.com/Toolsai/Codex-Micro)

## The story

OpenAI and Work Louder introduced the physical [Codex Micro](https://openai.com/supply/co-lab/work-louder/), a beautifully tactile command center for agentic work—with a US$230 price tag. I loved the idea, but it made me wonder: what if the controller were already in your pocket? So I used Codex to build **Codex-Mirco**, a virtual controller that recreates the physical controller’s core experience and adds customizable layers, button mappings, project and conversation switching, voice control, and more.

Inspiration does not always wait until you are sitting at your Mac. You may have stepped away with only an iPhone in hand, but still want to check whether Codex has finished, switch conversations, or respond to an approval. Codex-Mirco lets the Mac keep working while the essential controls stay in your hand.

> [!WARNING]
> Codex-Mirco is a Beta for trusted private Wi-Fi or a personal hotspot only. Do not use it on hotel, cafe, airport, or other public/shared networks. Never expose its ports through port forwarding, DMZ, a public tunnel, or a cloud relay. The local connection is not end-to-end encrypted.

## See it in action

After setup, open the local controller on your iPhone or iPad, pair it with the six-digit code, then tap the mapped controls to operate Codex on your Mac.

Tap on iPhone or iPad, and watch Codex respond on the Mac in real time.

<table>
 <tr>
 <td width="38%" align="center" valign="top">
 <img src="docs/media/codex-mirco-iphone.jpg" alt="Codex-Mirco interface on iPhone" width="360"> 
 iPhone Compact controller view
 </td>
 <td width="62%" align="center" valign="top">
 <img src="docs/media/codex-mirco-ipad.jpg" alt="Codex-Mirco interface on iPad" width="760"> 
 iPad Expanded controller view
 </td>
 </tr>
</table>

## Install with Codex

Open Codex and paste this request:

```text
Install Codex-Mirco from https://github.com/Toolsai/Codex-Micro. Use the bundled Codex Skill, run its preflight first, and guide me through the installation, required shortcuts, and macOS permissions. Do not overwrite an existing installation or install missing system dependencies without asking me first. Finish by showing the local URL, pairing code, and QR Code.
```

Codex will inspect the bundled Skill, install the runtime, guide you through the few settings that require personal approval, and generate the QR Code for your iPhone or iPad.

## System requirements

- Apple Silicon Mac (`arm64`)
- Codex desktop app
- Node.js 22.13.0 or newer, with npm
- Apple Command Line Tools, including `/usr/bin/clang`
- iPhone or iPad on the same trusted private Wi-Fi or personal hotspot as the Mac

## What the installer does

- Runs a preflight before making changes
- Installs an isolated runtime in `~/Library/Application Support/Codex Micro`
- Installs lockfile-pinned npm dependencies and creates a production build
- Compiles the bundled local macOS keyboard-control helper
- Starts the Controller and Companion background service
- Guides you through Codex shortcuts and macOS Accessibility permission
- Generates the local URL, six-digit pairing code, and QR Code

It does not modify the Codex app bundle or Codex internal settings, and it does not create a public network tunnel.

## Security boundary

- Companion accepts only loopback or private-network clients and checks the same-host Origin.
- New devices must provide a cryptographically generated six-digit pairing code.
- Repeated distinct pairing failures temporarily block the source address.
- Controller messages resolve to allow-listed actions, while normal Codex approval prompts remain enabled.
- Pairing can be reset if a code is exposed or a device is lost.

These are basic protections for a trusted local network—not a security boundary for the public internet or a hostile network.

## Beta limitations

- Apple Silicon Macs only
- Codex desktop UI, shortcut, or app-server changes may require compatibility updates
- Voice uses the Mac’s Codex recording device, not the iPhone or iPad microphone
- Not designed for public-network access, internet remote control, or shared multi-user environments

## License and attribution

Codex-Mirco is open source under the [MIT License](LICENSE). If you use, modify, or redistribute this project, retain the license and identify the original source:

- **Original creator:** Prompt Case
- **Original project:** [Toolsai/Codex-Micro](https://github.com/Toolsai/Codex-Micro)

## Creator

**Prompt Case** — [threads.com/@prompt_case](https://www.threads.com/@prompt_case)

Codex-Micro

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README