Codex Mobile

Codex Mobile turns a local Codex setup into something you can monitor and drive from a phone, while keeping the same project available as a static web app and as an Android WebView shell.

Korean summary

로컬 PC에서 돌고 있는 Codex를 모바일에서 확인하고 관리할 수 있게 만든 프로젝트입니다.
같은 UI를 정적 웹으로 배포할 수 있고, android-app/ 아래에서는 Android WebView 앱으로도 감쌀 수 있습니다.

Screenshots

Web connect screen

Historical sessions view

Active thread view

Architecture

flowchart LR
    A["Phone Browser or Android App"] -->|"HTTP"| B["FastAPI Relay<br/>codex_relay.py"]
    B -->|"read-only history"| C["CODEX_HOME/sessions"]
    B -->|"live execution"| D["Codex SDK + local codex CLI"]
    E["Static Web UI<br/>index.html / app.js / styles.css"] --> A
    F["Android WebView Shell<br/>android-app/"] --> A

Loading

What It Does

Component	Purpose
codex_relay.py	Exposes local Codex sessions, active threads, and prompt execution over HTTP.
index.html, app.js, styles.css	Deployable static web client for mobile and desktop browsers.
android-app/	Android shell that loads the same UI from bundled assets in a WebView.
tests/	Regression coverage for relay helpers and mobile selection logic.

Key Behaviors

• Historical sessions are read-only so you can inspect old work safely.
• Historical desktop sessions can be attached into live mobile-manageable threads with one tap.
• Only active threads accept new prompts.
• Active thread lists now show only the latest message preview instead of full mirrored history.
• Mobile input is treated as append-only delivery to the selected active thread.
• The relay now supports async Codex SDK thread execution on Windows.
• On Windows, the relay prefers the npm codex.cmd shim to avoid the inaccessible WindowsApps binary path.
• The web client remembers the last relay URL, selected session/thread, and pending working directory.
• The static app accepts launch query parameters such as relay, autoconnect=1, and tab=threads, which also makes scripted screenshots easy.

Quick Start

1. Run the relay on your PC

pip install fastapi uvicorn openai-codex-sdk
python codex_relay.py

The default relay address is:

http://0.0.0.0:8321

2. Run the web client locally

python -m http.server 8090

Open:

http://localhost:8090

Then connect the UI to your relay, for example:

http://<your-pc-ip>:8321

3. Build the Android shell

cd android-app
./gradlew assembleDebug

The Android app loads the same UI from:

android-app/app/src/main/assets/

Mobile Test Result

This repo was tested on the host machine with:

• Relay health check responding on http://127.0.0.1:8321/health
• Static web app responding on http://127.0.0.1:8090/
• Active thread creation succeeding through POST /threads
• Live prompt execution succeeding through POST /threads/{id}/run

The most recent verified live execution returned:

{
  "response": "OK"
}

If your phone is on the same network, the current machine-local addresses are:

Web UI:   http://172.30.1.49:8090
Relay:    http://172.30.1.49:8321

If those addresses do not open on mobile, the next thing to check is the Windows firewall for inbound access on ports 8090 and 8321.

Verification

python -m unittest tests.test_codex_relay -v
node --test tests/codex-mobile-utils.test.mjs
python -m py_compile codex_relay.py
node --check app.js

Repository Notes

• Public repo: sinmb79/codex-mobile
• Static hosting is ready from the repo root.
• Android packaging is scaffolded, but Gradle build verification still depends on an installed local Gradle or wrapper setup on the target machine.

Korean usage notes

빠른 사용 메모

• 릴레이 실행: python codex_relay.py
• 웹 실행: python -m http.server 8090
• 모바일 접속 주소
  • 웹 UI: http://172.30.1.49:8090
  • 릴레이: http://172.30.1.49:8321
• 안드로이드 앱 빌드: cd android-app && ./gradlew assembleDebug

확인된 상태

• 세션 조회 가능
• 활성 스레드 생성 가능
• 모바일용 웹 UI 연결 가능
• 실제 프롬프트 실행 결과 OK 확인