Codex Remote Hub

Codex Remote Hub is a React + Node app that mirrors a Codex-native workflow from your phone.

It is designed as a wrapper around terminal Codex:

• choose a project folder,
• automatically start/switch Codex in that folder,
• resume the latest project chat (or create one if missing),
• continue the conversation with clean message bubbles.

Core User Flow

1. Open the web app on phone or desktop.
2. Pick a project from the configured parent folder (/Users/adeelaziz/Documents/GitHub by default).
3. The backend automatically:
   • starts Codex in that project (or restarts/switches from the previous project),
   • starts a stable Codex session in that project (codex resume --last || codex by default),
   • maps the project to its stored thread history.
4. Existing messages for that project are loaded immediately.
   • On app load, the client re-selects the active project and re-hydrates that thread directly from the API to avoid stale or missing history.
5. New messages are sent with automatic submit (Enter) and streamed back in a clean chat format.
6. Assistant replies are persisted server-side from terminal output so history remains consistent across devices.
7. If Codex asks to run a command, the app captures that prompt and shows an inline approval card so you can approve/reject from phone.

What This App Can Do

• Authenticated mobile/desktop web UI with realtime updates.
• Project picker driven by filesystem directories under a configurable root.
• Automatic terminal lifecycle per selected project.
• Project-scoped chat history restore and persistence.
• Message-style UI (You right, Codex left) with typing indicator and context-left status.
• Native-style Codex slash-command shortcuts:
  • /status, /model, /permissions, /review, /diff, /plan, /compact, /help.
• Realtime command approval flow:
  • terminal approval prompts are parsed server-side and pushed to clients,
  • approve/reject actions are sent back to terminal as the expected numeric confirmation input.
  • rate-limit model-switch prompts are also surfaced as approvals so chat does not appear stuck behind hidden terminal dialogs.
• Optional approval and git snapshot APIs remain available.
• Bridge CLI for desktop automation (scripts/bridge-client.mjs).

Architecture

• apps/server (Node.js + Express + Socket.IO)
  • token-authenticated REST API
  • project discovery and session selection endpoints
  • terminal bridge orchestration and switching per project
  • JSON persistence (apps/server/data/state.json)
• apps/web (React + Vite + TypeScript)
  • project-first interface
  • realtime sync + REST fallbacks
  • chat rendering/parsing for terminal Codex output
• scripts
  • helper CLI and smoke tests

Quick Start

1) Install dependencies

npm install

2) Configure environment

cp apps/server/.env.example apps/server/.env

Set at least:

• ACCESS_TOKEN: shared auth token for app + phone.
• TERMINAL_BRIDGE_ENABLED=true
• TERMINAL_BRIDGE_COMMAND=codex resume --last || codex
• PROJECTS_ROOT=/Users/adeelaziz/Documents/GitHub

Optional:

• TERMINAL_BRIDGE_AUTOSTART=false (recommended for project-first flow)
• ALLOWED_ORIGIN=http://localhost:5173

3) Run the app

npm run dev

• Web UI: http://localhost:5173
• API: http://localhost:8787

4) Connect from phone

On first screen:

• Server URL: http://<YOUR_DESKTOP_IP>:8787
• Token: ACCESS_TOKEN

Ensure phone + desktop are on same network (or VPN/Tailscale) and firewall allows inbound 5173 and 8787.

Tests and Verification

Run everything:

npm run typecheck
npm run test
npm run build

Server-only e2e API tests:

npm run test:e2e

Long chat smoke test:

npm run smoke:chat

Bridge CLI Examples

Send assistant message from desktop script:

node scripts/bridge-client.mjs send-message \
  --url http://localhost:8787 \
  --token YOUR_TOKEN \
  --text "Build completed" \
  --role assistant \
  --source desktop

Capture git snapshot:

node scripts/bridge-client.mjs capture-changes \
  --url http://localhost:8787 \
  --token YOUR_TOKEN \
  --label "Pre-release check" \
  --max-diff-lines 800

Production Notes

• Prefer HTTPS reverse proxy or Tailscale/Zero Trust tunnel for remote access.
• Use long random tokens and restricted CORS origins.
• Treat apps/server/data/state.json as sensitive user/session data.

More deployment patterns: docs/DEPLOYMENT.md.

Directory Guide

Each major folder includes a local README.md explaining ownership and contents.