Codex Companion

A local-first mobile companion for monitoring and steering Codex sessions from your phone.

Codex Companion lets you keep a local Codex desktop workflow moving from a mobile device. The Windows desktop host runs a local backend and bridge, the phone pairs over the same network, and live thread updates stream through REST and WebSocket APIs.

Why

Codex is strongest on a desktop with access to your local workspace. Codex Companion keeps that workflow reachable when you step away from the PC:

• Follow active Codex conversations from mobile.
• See assistant output, tool calls, file-change context, and thread state.
• Send messages or steer a live turn from the phone.
• Pair locally with a QR payload instead of hosted accounts.
• Package the Windows host for release builds.

Features

• Windows tray host for the local backend and bridge.
• Kotlin Multiplatform mobile app built with Compose Multiplatform.
• Ktor REST and WebSocket relay for pairing, thread sync, presence, and commands.
• Local bridge integration for the Codex app-server JSON-RPC/WebSocket endpoint.
• Realtime mobile timeline updates with selected-thread refresh.
• QR scanning on Android and iOS, plus manual payload paste fallback.
• In-memory MVP backend state with durable mobile session context on device.
• Release workflow for Windows ZIP/installer artifacts and an Android APK asset.

Architecture

flowchart LR
    Mobile["Mobile app"] -->|REST + WebSocket| Backend["Ktor relay"]
    Desktop["Windows tray host"] --> Backend
    Desktop --> Bridge["Local bridge"]
    Bridge -->|WebSocket| Backend
    Bridge -->|JSON-RPC / WebSocket| Codex["Local Codex app-server"]
    Backend --> State["In-memory relay state"]
    Mobile --> Store["On-device session store"]

Loading

Modules

Module	Purpose
desktop	Windows tray launcher, local backend host, release packaging target.
backend	Ktor API and WebSocket relay for mobile and bridge clients.
bridge	JVM bridge that adapts local Codex app-server events into shared protocol messages.
mobile/composeApp	Kotlin Multiplatform Compose app for Android and iOS targets.
shared-protocol	Shared DTOs, commands, realtime events, and serialization config.
wiki	Local Obsidian vault junction with complete project documentation.
scripts	Local helper scripts for development workflows.

Quick Start

Requirements

• Windows desktop for the tray host.
• JDK 21.
• Android Studio or IntelliJ IDEA.
• Android device or emulator for the current mobile workflow.
• Local Codex app-server available to the bridge when using the real provider.

Run The Desktop Host

.\gradlew.bat :desktop:run

The desktop host starts the backend, starts the bridge, and exposes a local pairing page. Open the URL printed at startup from the phone, or use the advertised LAN URL shown by the tray app.

Run Backend And Bridge Separately

.\gradlew.bat :backend:run
.\gradlew.bat :bridge:run

Use this mode when debugging relay or bridge behavior independently.

Build The Android App

.\gradlew.bat :mobile:composeApp:assembleDebug

Debug APK output:

mobile/composeApp/build/outputs/apk/debug/composeApp-debug.apk

Pairing Flow

1. Start the desktop host.
2. Open the local pairing page on the PC or phone.
3. Scan the QR code from the mobile app, or paste the raw payload manually.
4. Select the paired PC agent.
5. Open a thread and follow live updates.

Pairing is local-first. The backend advertises a reachable LAN address by default, and optional UPnP port mapping can be enabled for networks that support it.

Testing

Run the main verification suite:

.\gradlew.bat --rerun-tasks :shared-protocol:test :bridge:test :backend:test :mobile:composeApp:testDebugUnitTest

Build the mobile debug APK:

.\gradlew.bat :mobile:composeApp:assembleDebug

Build the mobile release APK:

.\gradlew.bat :mobile:composeApp:assembleRelease

Build Windows release artifacts:

.\gradlew.bat :desktop:packageWindowsZip :desktop:packageWindowsExe

Configuration

The app works with sensible local defaults. Override environment values with module .env files when needed.

Common settings:

Variable	Purpose
RELAY_BASE_URL	Backend URL used by the bridge.
BRIDGE_SHARED_SECRET	Bootstrap secret for bridge authentication.
CODEX_ENDPOINT_URL	Local Codex app-server WebSocket endpoint.
BACKEND_PUBLIC_BASE_URL	Exact URL placed into pairing payloads.
BACKEND_PUBLIC_URL_MODE	Public URL resolver mode, such as LAN or public IP.
BACKEND_AUTO_PORT_FORWARD	Enables optional UPnP port mapping.

More details live in wiki/Operations/Local Development Workflow.md and wiki/Modules/Backend Relay.md.

Documentation

Complete project documentation lives in the local Obsidian wiki linked at wiki/Home.md.

The tracked docs/README.md file is only a pointer so there is one canonical documentation home.

Status

Codex Companion is an MVP with a local-first product shape. It is useful for development and testing, but some production concerns are intentionally still open:

• Backend state is currently in memory.
• Production token hardening and secret rotation are not complete.
• Hosted relay accounts are out of scope for the current architecture.
• Push notifications are not implemented.
• The official Codex desktop UI may not repaint mobile-origin turns live unless Codex itself exposes that refresh path.

Release

The included GitHub Actions workflow builds Windows release assets from version tags:

.github/workflows/release.yml

Push a tag like v0.1.0, or run the workflow manually with an existing tag. The workflow builds the backend tests, Android unit tests, Windows ZIP, Windows installer, and Android APK assets.

For Android release signing, configure these GitHub repository secrets before publishing:

Secret	Purpose
ANDROID_RELEASE_KEYSTORE_BASE64	Base64-encoded Android release keystore file.
ANDROID_RELEASE_KEYSTORE_PASSWORD	Password for the release keystore.
ANDROID_RELEASE_KEY_ALIAS	Alias of the release signing key.
ANDROID_RELEASE_KEY_PASSWORD	Password for the release signing key.

If those secrets are not configured, the workflow still publishes a debug-signed Android APK named with android-debug. That asset is useful for testing, but a properly signed release APK is recommended for public downloads.

iOS source is included in the Kotlin Multiplatform project, but iOS release builds are not published because I do not have access to a Mac for compiling and signing iOS artifacts.

Create a tagged release from the command line:

git tag -a v0.1.0 -m "v0.1.0"
git push origin v0.1.0

Run the same release workflow manually with the GitHub CLI:

gh workflow run release.yml -f tag=v0.1.0

License

Codex Companion is free and open source software released under the MIT License.