Codex Android App

Use Codex from your Android phone while your actual work stays on your Mac.

Codex Android App pairs an Android app with a local Mac runtime. The phone lets you follow Codex, send messages, resume chats, and run workspace actions without moving your repositories, credentials, files, or git operations off your computer.

This is an unofficial companion project.

Download: latest GitHub Release

Release artifact status: the Android APK and AAB in the latest GitHub Release are signed with the project's Android upload key. The APK still requires Android sideloading permission because it is distributed through GitHub, not the Play Store. The macOS DMG is not Developer ID signed or notarized, so macOS Gatekeeper may block the app until you explicitly allow it.

INSTALL

For most people, start with the latest GitHub Release:

1. Download the Android asset named like CodexAndroidApp-...-android-release-signed.apk from Releases. For Play Console upload, use the signed AAB from the same release. Do not use assets marked unsigned unless you are signing them yourself.
2. On Android, allow installs from the browser or file manager you used to download the APK, then open the APK to install it.
3. Download the Mac asset named like CodexAndroidApp-...-macos-arm64-unsigned-not-notarized.dmg from the same release.
4. Open the DMG and move Codex Android App to Applications. If macOS blocks launch because the app is from an unidentified developer, use Control-click > Open, or approve it in System Settings > Privacy & Security.
5. Open the Mac companion and let it start the local runtime.
6. Open Codex Android App on Android.
7. Scan the QR code shown by the Mac companion.

After pairing, the Android app should reconnect to the trusted Mac on later launches without scanning every time.

The Basic Idea

• Your Mac runs Codex.
• Your Android phone becomes the remote control.
• A QR code pairs the phone to your Mac.
• The Mac runtime starts a local relay and bridge for the phone to reach.
• Your workspace and git operations stay on the Mac.

After the first successful pairing, the app can reconnect to the trusted Mac without scanning the QR code every time.

Why Use It

• Check Codex work from your phone.
• Send a follow-up without going back to your desk.
• Keep local projects local.
• Use one Mac as the trusted Codex runtime.
• Use local LAN or a private network such as Tailscale when your phone needs a stable route to the Mac.

What Works Today

• QR pairing between Android and a Mac.
• Android chat timeline for assistant output, reasoning, tool activity, approvals, and completion state.
• Start new Codex chats from Android.
• Resume existing local threads.
• Open or create work in local repositories through the paired Mac.
• Use git, branch, worktree, and workspace actions through the Mac.
• Trusted reconnect after first pairing.
• Message image preview and save/export behavior.
• macOS menu bar companion for local runtime control.

Current Status

Codex Android App is usable today through GitHub Releases or from source. It is still pre-store-release software, so expect a rougher setup than a normal Play Store app.

Not finished yet:

• Play Store listing and distribution
• fully polished first-run installer flow
• signed and notarized Mac distribution, unless a specific release says otherwise
• final clean-device release QA

Desktop-to-phone live following is stronger than phone-to-desktop live following, so if you start a run from Android, follow it in Android first.

What You Need

• A Mac with Codex installed and signed in.
• An Android device running Android 9 or newer.
• The latest Android APK and Mac app or DMG from GitHub Releases, or the tools listed below if you are building from source.

Quick Start From Source

Use this path if you want to build the app yourself or test the current branch.

You need Git, Android Studio or the Android SDK, and Xcode command line tools if you want to build the macOS companion.

Clone the repo:

git clone https://github.com/maxaitel/codex-android-app.git
cd codex-android-app

Start the local Mac runtime:

./run-local-codex-android-relay.sh

Install the Android debug app on a connected device:

./gradlew :android:app:installDebug

Open Codex Android App on Android, scan the QR code printed by the local runtime or shown by the macOS companion, then start or open a chat.

If your phone cannot reach the Mac address printed in the QR, pass a reachable LAN or Tailscale address:

./run-local-codex-android-relay.sh --hostname 192.168.1.10

Tailscale does not change what runs where; it only gives the phone a stable private address for the Mac runtime.

A Few Source-User Notes

installDebug requires USB debugging to be enabled on the Android device. If you only want to build the APK first, run:

./gradlew :android:app:assembleDebug

The debug APK is written to:

android/app/build/outputs/apk/debug/app-debug.apk

To build the local macOS companion app:

cd macos
./Scripts/build-app.sh

The macOS companion is the intended normal runtime controller. It starts and stops the local runtime, shows the QR code, manages host selection, and can reset pairing.

How It Works

Codex Android App has four parts:

• android/ is the Android app.
• macos/ is the native macOS menu bar companion.
• bridge/ is the local Mac bridge that talks to codex app-server.
• relay/ is a WebSocket transport that connects Android to the bridge.

The relay is only a transport hop. Codex, git, and workspace operations still run on the paired Mac. After secure pairing, application payloads are encrypted between Android and the Mac bridge.

Privacy Basics

• Codex runs on the paired Mac.
• Git commands run on the paired Mac.
• Workspace files stay on the paired Mac unless you explicitly send attachments through the app.
• Pairing and cached Android messages are encrypted using Android Keystore-backed keys.
• There is no Codex Android App account system or cloud chat database in the source build.

Read Legal/PRIVACY_POLICY.md for the current data handling notice.

Contributor Docs

Goal	Read
Contribute code or run test checks	Docs/contributing.md
Track release/distribution work	Docs/release-checklist.md
Inspect the relay protocol boundary	relay/README.md
Build the macOS companion app	macos/README.md
Read legal terms	Legal/TERMS_OF_USE.md

License And Contact

Codex Android App is licensed under MIT. See LICENSE for the full license text and notices.

• Email: maxaitel@gmail.com
• GitHub: github.com/maxaitel/codex-android-app