<p align="right"> <b>Language</b>: <a href="#english">English</a> | <a href="#chinese">中文</a> </p>

---

<a id="english"></a>

<details open> <summary><b>🇺🇸 English Documentation</b>（click to collapse）</summary> <br>

OpenCodex

Run an AI coding assistant on your iPhone — real-time chat, terminal access, file browsing, and command approval in one app.

If OpenCodex helps your workflow, please click Watch to receive release notifications.

Watch Releases · Star Repository · Join Discussions

Overview

OpenCodex is an iOS client + local Node.js Worker backend development platform. Connect your iPhone to a Worker service running on your Mac to engage in multi-turn conversations with Claude / Codex, view execution logs, approve high-risk commands, browse and edit project files, and operate a remote terminal.

Why OpenCodex

AI agents can run coding tasks for 10-20 minutes continuously. In that window, human work is mostly supervision: review, approval, and direction decisions.

OpenCodex is built to decouple supervision from desk location while keeping local control:

• Local-first workflow on your own Mac
• Observable execution through file browsing and logs
• Deterministic fallback through direct terminal passthrough
• Approval gates for high-risk operations

Key Features

| Feature | Description | |---------|-------------| | 💬 Multi-thread Chat | Independent context per thread, with archive & switch support | | ⚡ Real-time Streaming | SSE event stream with batch processing to prevent UI lag (24 events / 80ms) | | ✅ Command Approval | Pauses dangerous commands for approve / reject / modify review | | 🖥️ Split-screen Terminal | WebSocket terminal with auto-reconnect and PTY resize | | 📁 File Browser | Tree view, full-text search, code viewing & editing | | 🔗 Message Links | Tap path:line references in messages to jump directly to the file |

Screenshots

Architecture Overview

iPhone App (SwiftUI + TCA)
├── AppFeature          ← Global lifecycle & connection management
├── ThreadsFeature      ← Thread list
├── ChatFeature         ← Real-time chat (SSE)
├── TerminalFeature     ← Split-screen terminal (WebSocket)
├── FileBrowserFeature  ← File tree & search
├── ApprovalFeature     ← Approval sheet
└── SettingsFeature     ← Connection configuration

Mac Worker (Node.js)
└── codex-worker-mvp    ← REST + SSE + WebSocket → codex app-server

Communication Protocols

| Use Case | Protocol | Notes | |----------|----------|-------| | Thread / job management | REST HTTP | Standard CRUD | | Real-time message stream | SSE | Cursor-based, auto-recovery on disconnect | | Terminal interaction | WebSocket | Frame sequence numbers, ping/pong keepalive |

Repository Layout

OpenCodex/
├── CodexWorkerApp/          # Xcode wrapper project (App entry point)
├── codex-worker-ios/        # Swift Package (business logic & UI)
│   └── Sources/CodexWorker/
│       ├── App/             # Root app entry
│       ├── Features/        # TCA Reducer feature modules
│       ├── Models/          # Data models
│       ├── Dependencies/    # TCA dependencies (API/SSE/Terminal/Store)
│       └── Services/        # Markdown rendering, message pipeline, etc.
├── codex-worker-mvp/        # Node.js Worker backend
├── codex-sessions-tool/     # Session backup / restore CLI tool
└── docs/                    # Design docs & architecture decisions

Prerequisites

• macOS — to run the Worker backend and Xcode
• Xcode 16+ — to build the iOS App (Swift 6 required)
• Node.js ≥ 22 — to run the Worker backend
• codex CLI — Worker calls codex app-server internally (API Key must be configured)
• iPhone or iOS Simulator (iOS 17+)

Runtime Dependency Boundary

• This repository fully includes:
  • codex-worker-ios (iOS package)
  • codex-worker-mvp (Node.js worker)
  • codex-sessions-tool (session utility)
• This repository does not include codex app-server implementation.
  • Runtime depends on local codex CLI availability and account permission.
  • Without codex app-server access, contributors can still run unit tests, static checks, and submit UI/state-machine/documentation improvements.

Non-Goals

• Not a cloud execution platform
• Not a fully autonomous no-review coding system
• Not a replacement for architecture and product decisions
• Not a generic remote desktop tool

Quick Start

Option A — Docker (Recommended)

# 1. Clone and configure
git clone https://github.com/mjmkk/opencodex.git && cd opencodex
cp codex-worker-mvp/worker.config.example.json codex-worker-mvp/worker.config.json
# Edit worker.config.json — add your Codex/Claude API key

# 2. Start the backend
make docker-up          # builds image and starts in background

# 3. Verify
curl http://localhost:3000/v1/health
# → {"status":"ok"}

Option B — Node.js (Development)

cd codex-worker-mvp
cp ../codex-worker-mvp/worker.config.example.json worker.config.json
npm install
npm start               # listens on http://127.0.0.1:3000

Step 2: Run the iOS App

1. Open CodexWorkerApp/CodexWorkerApp/CodexWorkerApp.xcodeproj in Xcode
2. Select the CodexWorkerApp scheme → choose a simulator or your iPhone → Run
3. In the App Settings, set the connection URL:
   • Simulator: http://127.0.0.1:3000
   • Physical iPhone: http://<Mac-LAN-IP>:3000 (same Wi-Fi network required)

Full deployment guide → docs/deployment.md

Common Commands

Backend Tests

cd codex-worker-mvp && npm test

iOS Package Unit Tests

cd codex-worker-ios
xcodebuild -scheme CodexWorker \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test

iOS App Build Verification

cd CodexWorkerApp/CodexWorkerApp
xcodebuild -project CodexWorkerApp.xcodeproj \
  -scheme CodexWorkerApp \
  -configuration Debug \
  -destination 'generic/platform=iOS Simulator' \
  -skipMacroValidation \
  build

Session Backup & Restore

cd codex-sessions-tool
npm install

# Backup
node bin/backup.js --output ./backup.tar.gz

# Restore
node bin/restore.js --input ./backup.tar.gz

# Verify
node bin/verify.js --input ./backup.tar.gz

# Health check
node bin/doctor.js

Configuration Reference

| Item | Location | Notes | |------|----------|-------| | iOS connection config | App Settings → UserDefaults | Base URL, Token, model preference | | Worker port | PORT env var | Default 8787 | | Worker auth token | WORKER_TOKEN env var | Leave empty to disable auth | | SQLite database | codex-worker-mvp/data/worker.db | Created automatically |

For full backend configuration options, see codex-worker-mvp/README.md.

FAQ

Do I need codex app-server?

Yes. OpenCodex integrates with a locally running codex app-server via codex-worker-mvp.

Why local-first instead of cloud agents?

Local-first keeps full control over environment, tools, history, and debugging paths.

Does my repository leave my Mac?

By default, repository operations run against your local environment through your own worker service.

Why keep terminal passthrough if chat already exists?

Chat is flexible, while terminal passthrough is deterministic for direct commands and fast recovery.

How does remote access work without renting servers?

Recommended path is Tailscale peer-to-peer networking between iPhone and Mac.

Tech Stack

iOS Frontend

| Library | Purpose | |---------|---------| | ComposableArchitecture | State management (TCA) | | ExyteChat | Chat UI component | | GRDB | SQLite ORM (local cache) | | SwiftTerm | Terminal rendering | | Runestone | Code editor | | MarkdownUI | Markdown rendering | | EventSource | SSE client |

Node.js Backend

| Technology | Purpose | |------------|---------| | Express | HTTP server framework | | SQLite (better-sqlite3) | Data persistence | | WebSocket (ws) | Terminal stream transport | | SSE | Message event push |

License

This repository is licensed under the Apache License 2.0.

• See NOTICE for attribution notice.
• Vendored third-party code keeps its original license (for example, swift-composable-architecture/ has its own LICENSE).

Development Guidelines

• Before committing, run at minimum: backend npm test and iOS xcodebuild ... build
• Swift code uses StrictConcurrency — all async code must be concurrency-safe
• All network-layer logging uses OSLog Logger (with per-module categories), never print()
• TCA `