remcodex 0.1.0-beta.3 → 0.1.0-beta.5

package/README.md

@@ -1,81 +1,103 @@
-# RemCodex
-
-> Control Codex from anywhere. Even on your phone.
-
-RemCodex is a local-first web UI for running, reviewing, approving, and resuming Codex sessions from your browser.
-
-It is built for the real workflow: long-running sessions, mobile check-ins, approval prompts, imported rollout history, and timeline-style execution flow.
-
-```mermaid
-flowchart LR
-  subgraph D[Your devices]
-    P[Phone]
-    B[Browser]
-  end
-
-  subgraph M[Your work machine]
-    subgraph R[RemCodex]
-      UI[Web UI]
-      S[Server]
-      T[Timeline + approvals + sync]
-    end
-
-    subgraph C[Local Codex runtime]
-      X[Codex CLI / app-server]
-      F[Workspace files]
-      H[~/.codex sessions]
-    end
-  end
-
-  P --> UI
-  B --> UI
-  UI --> S
-  S --> T
-  S --> X
-  X --> F
-  X --> H
-  H --> S
-  T --> UI
-```
+# 🚀 RemCodex
+
+> Control your AI coding agent from anywhere.  
+> Built for Codex. Ready for more.
+
+Run Codex once on your computer.  
+Watch, approve, and control it from any device.
+
+> Not a wrapper. Not a proxy.  
+> A real-time control layer for AI execution.  
+> Turns AI execution into a controllable system.
+
+![RemCodex hero cover](docs/assets/hero-cover.png)
+
+---
+
+## ✨ What is RemCodex?
+
+RemCodex is a **local-first control layer for Codex**.
+
+It turns AI execution into a **controllable system** —  
+visible, interruptible, and continuous.
+
+- 👀 See what the AI is doing — in real time
+- ✅ Approve or reject actions before execution
+- ⏹ Interrupt or stop at any moment
+- 📱 Access your session from any device
+- 🔄 Sessions don’t break — they resume
+
+> One session. Any device.
+
+---
+
+## 🎬 A real workflow
+
+You start a long Codex session on your machine.
+
+Then you leave your desk.
+
+On your phone:
+
+- you see progress in real time
+- you receive an approval request
+- you approve it
+
+The session continues instantly.
+
+> Everything else can disconnect — your session won’t.
 
-- Watch live Codex runs without staying in the terminal
-- Approve sensitive actions from a cleaner UI
-- Pick up the same session again after refresh, sleep, or reconnect
+---
 
-## Status
+## 🔥 Why RemCodex exists
 
-This project is currently a **beta / developer preview**.
+AI coding agents are powerful.  
+But today, they run like a black box.
 
-MIT licensed — free for personal and commercial use.
+You either:
 
-Cloud version coming soon.
+- trust everything blindly
+- or sit in front of your terminal watching it
 
-It is already usable for local and internal workflows, but it is not yet packaged as a one-click desktop app.
+RemCodex fixes that.
 
-## Why People Use It
+> AI is no longer a black box.
 
-Codex is powerful in the terminal, but many real workflows need a better control surface:
+---
 
-- checking progress from your phone
-- watching a long run without babysitting a terminal window
-- approving writes from a cleaner interface
-- reopening a session after refresh, sleep, or reconnect
-- reviewing imported rollout history next to native sessions
+## ⚡ What it does
 
-RemCodex turns Codex's event stream into a browser-based workspace that is easier to follow, easier to resume, and easier to operate.
+- Real-time execution timeline (messages, commands, approvals)
+- Human-in-the-loop command approval
+- Multi-device access to the same live session
+- Resume after refresh, sleep, or reconnect
+- Browser-based UI — **no extra client required**
+- Works with Codex CLI
 
-## What It Does
+> No extra client install. Just open a browser.  
+> Your code never leaves your machine.
 
-- Run Codex sessions from a browser
-- View sessions in a single-page workspace with a sidebar and execution timeline
-- Follow streaming assistant output, commands, patches, and approvals
-- Approve or reject file-system actions from the UI
-- Import existing Codex rollout sessions from `~/.codex/sessions/...`
-- Keep imported sessions in sync while they are still active
-- Resume stale sessions after the page comes back from background
-- Work well on desktop and on mobile
+---
 
-## Screenshots
+## 🚀 Quick start
+
+```bash
+npx remcodex
+```
+
+Then open:
+
+http://127.0.0.1:18840
+
+Access from another device:
+
+http://<your-ip>:18840
+
+> Runs entirely on your local machine. No cloud, no data upload.
+
+---
+
+## 🖥 Screenshots
 
 ![RemCodex desktop workspace](docs/assets/hero-desktop.png)
 
@@ -91,121 +113,114 @@ RemCodex turns Codex's event stream into a browser-based workspace that is easie
 
 ![RemCodex imported Codex session](docs/assets/imported-session.png)
 
-> Bring imported Codex rollouts into the same workspace and keep them easy to review.
+> Bring imported Codex rollouts into the same workspace.
+
+---
+
+## 🧠 What it actually is
 
-## Who It Is For
+RemCodex is a **browser-based workspace for Codex sessions**.
 
-- developers who already use Codex locally
-- people who want a browser-based control surface instead of raw terminal watching
-- teams who want to review or monitor runs from another device on the same network
-- anyone who wants approvals, timeline view, and imported rollout history in one place
+It is built for real workflows:
 
-## Screens It Aims To Replace
+- long-running sessions
+- mobile check-ins
+- approval prompts
+- imported rollout history
+- timeline-style execution flow
 
-- terminal-only session watching
-- ad-hoc mobile remote desktop checks
-- raw log scrolling for approvals and command progress
-- fragmented session history between local and imported rollouts
+Instead of raw terminal logs, you get a structured, visual timeline you can follow and control.
 
-## Current Product Shape
+---
+
+## 🧩 Current product shape
 
 - Single-page workspace UI
 - Left sidebar for session navigation
-- Right-side timeline / execution flow for the active session
-- Fixed composer at the bottom
+- Right-side execution timeline
+- Fixed input composer
 - Semantic timeline rendering for:
-  - user messages
-  - assistant commentary / final messages
-  - thinking
-  - commands
-  - patches
-  - approvals
-  - system events
+    - user messages
+    - assistant output
+    - thinking
+    - commands
+    - patches
+    - approvals
+    - system events
 
-## Tech Stack
+---
 
-- Backend: Node.js + TypeScript + Express + WebSocket
-- Database: SQLite via `better-sqlite3`
-- Terminal/runtime integration: `node-pty` + Codex app-server
-- Frontend: zero-build static web app (`web/`)
-- Markdown rendering: `markdown-it`
+## ⚙️ Key behaviors
 
-## Requirements
+### Approvals
 
-Before running this project, you should have:
+- Writes inside working area → auto allowed
+- Writes outside → require approval
+- `Allow once` / `Allow for this turn` supported
+- Approval history stays visible in timeline
 
-- Node.js installed
-- Codex CLI installed and already working locally
-- A machine where this app can access your local Codex data and working directories
+---
 
-On Linux, the first install may need a native build toolchain for `better-sqlite3` and `node-pty`:
+### Timeline
 
-- `python3`
-- `make`
-- `g++`
+- Semantic rendering (not raw logs)
+- Commands grouped into readable activity blocks
+- Running / failed states clearly visible
+- Smooth streaming + recovery after refresh
 
-This project is currently developed primarily around a local macOS workflow.
+---
 
-## Quick Start
+### Imported sessions
 
-For the current beta, the fastest way to try RemCodex is:
+- Import from `~/.codex/sessions/...`
+- Keep syncing if still active
+- Unified view with native sessions
 
-```bash
-npx remcodex
-```
+---
 
-You can also install it globally:
+## 🧠 Architecture
 
-```bash
-npm install -g remcodex
-remcodex
+```
+Codex CLI → Event stream → Semantic layer → Timeline → Web UI
 ```
 
-RemCodex starts a local server and opens the browser for you.
-
-If you want to make it reachable from your phone, expose the local machine on your LAN and open the same URL with your host IP.
+---
 
-### Linux Install Note
+## ⚙️ Requirements
 
-If `npx remcodex` appears to hang during the first install, it is usually still installing or compiling native dependencies.
+- Node.js
+- Codex CLI (already working locally)
 
-Make sure the machine has:
+---
 
-- `python3`
-- `make`
-- `g++`
+## ⚙️ Configuration
 
-Common setup examples:
+Default port: **18840**
 
 ```bash
-# Debian / Ubuntu
-apt-get install -y python3 make g++
-
-# RHEL / CentOS / Rocky / Alibaba Cloud Linux
-yum install -y python3 make gcc-c++
+PORT=18841 npx remcodex
 ```
 
-## Install FAQ
+---
 
-### Why does `npx remcodex` seem to hang on Linux?
+## 📦 Install FAQ
 
-The package includes native dependencies such as `better-sqlite3` and `node-pty`.
+### Why does `npx remcodex` hang on Linux?
 
-On some Linux machines, the first install may need to download or compile native binaries before RemCodex itself starts. That can look like a long spinner before you see any RemCodex output.
+First install may compile native deps:
 
-### What usually fixes Linux install failures?
+- `better-sqlite3`
+- `node-pty`
 
-Install the native build tools first:
+Make sure you have:
 
 - `python3`
 - `make`
 - `g++`
 
-If you see `node-gyp`, `g++`, or build-related errors, the machine is usually missing part of that toolchain.
+---
 
-### How can I get clearer logs than `npx remcodex`?
-
-If the first `npx` run is unclear, install it globally instead:
+### Debug install issues
 
 ```bash
 npm install -g remcodex
@@ -213,194 +228,88 @@ remcodex doctor
 remcodex start
 ```
 
-That usually makes native install errors much easier to read.
-
-### What if I am starting RemCodex on a headless server?
+---
 
-Use:
+### Headless mode
 
 ```bash
 npx remcodex --no-open
 ```
 
-or:
-
-```bash
-remcodex start --no-open
-```
-
-RemCodex will still print the local and LAN URLs even when it does not try to open a browser.
-
-### Do I need Codex CLI installed first?
-
-Yes.
-
-RemCodex is a control surface for your local Codex runtime. If `codex` is not already installed and working in `PATH`, run:
+---
 
-```bash
-remcodex doctor
-```
+## 🔧 How it works
 
-and fix the reported Codex CLI issue first.
+1. Codex emits events
+2. Backend stores them (SQLite)
+3. Frontend loads timeline snapshot
+4. Live updates stream via WebSocket
 
-## Local CLI
+Result:
 
-RemCodex also works well from source if you want to develop locally or inspect the runtime setup.
+- recoverable sessions
+- real-time UI
+- consistent execution flow
 
-Local development path:
+---
 
-```bash
-npm install
-npm run build
-npm link
-remcodex start
-```
+## 📊 Status
 
-Useful commands:
+- Beta / developer preview
+- Local-first architecture
+- No cloud dependency
 
-```bash
-node dist/server/src/cli.js doctor
-node dist/server/src/cli.js start --no-open
-node dist/server/src/cli.js version
-```
+---
 
-Use a specific database:
+## 🗺 Roadmap
 
-```bash
-node dist/server/src/cli.js start --db ~/.remcodex/remcodex-alt.db --no-open
-node dist/server/src/cli.js doctor --db ~/.remcodex/remcodex-alt.db
-```
+**Visibility**
 
-## Development
+- fully observable execution
+- clear action timeline
 
-```bash
-npm install
-npm run dev
-```
+**Control**
 
-## How It Works
+- fine-grained approvals
+- safer execution
 
-The app uses `codex app-server` as the primary runtime path.
+**Continuity**
 
-At a high level:
+- survive refresh / sleep
+- stable long runs
 
-1. Codex emits semantic events
-2. The backend stores them in SQLite
-3. The frontend reads an aggregated timeline view for initial load
-4. Live updates continue over WebSocket with catch-up after refresh
+**Access**
 
-This gives the UI:
+- control from any device
 
-- smooth streaming
-- recoverable sessions
-- imported rollout support
-- a consistent execution timeline instead of raw terminal logs
+**Integration**
 
-## Key Behaviors
+- IDE integrations
+- optional sharing
 
-### Approvals
+---
 
-- Writes inside the working area usually pass directly
-- Writes outside the working area trigger approval
-- `Allow once` approves only the current request
-- `Allow for this turn` expands writable roots for the active turn
-- Historical approval records stay visible in the timeline
-- Only live approvals stay actionable in the bottom approval bar
-
-### Imported Codex Sessions
-
-- Existing Codex rollouts can be imported from local session history
-- Imported sessions keep their own source metadata
-- Imported sessions can continue syncing after you open them
-- Native sessions are excluded from the import picker
-
-### Timeline and Execution Flow
-
-- The UI renders semantic timeline items, not raw logs
-- Commands and patches can be grouped into lighter activity summaries
-- Running and failed commands remain visually important
-- The final thinking placeholder appears only at the end of the active flow
-
-## Configuration
-
-Supported environment variables:
-
-- `PORT`
-- `DATABASE_PATH`
-- `PROJECT_ROOTS`
-- `CODEX_COMMAND`
-- `CODEX_MODE`
-- `REMOTE_HOSTS`
-- `ACTIVE_REMOTE_HOST`
-
-Notes:
-
-- The default runtime mode is `app-server`
-- `exec-json` is kept only as a fallback compatibility path
-- If `PROJECT_ROOTS` is not set, the app falls back to a broad local browsing root
-
-## Project Structure
-
-```text
-server/
-  src/
-    app.ts
-    controllers/
-    db/
-    gateways/
-    services/
-    types/
-    utils/
-web/
-  index.html
-  styles.css
-  api.js
-  session-ws.js
-  app.js
-scripts/
-  fix-node-pty-helper.js
-```
-
-## Main Endpoints
+## 👥 Who it’s for
 
-- `GET /health`
-- `GET /api/codex/mode`
-- `GET /api/codex/status`
-- `GET /api/codex/quota`
-- `GET /api/sessions`
-- `GET /api/sessions/:sessionId`
-- `GET /api/sessions/:sessionId/timeline`
-- `GET /api/sessions/:sessionId/events`
-- `POST /api/sessions`
-- `POST /api/sessions/:sessionId/messages`
-- `POST /api/sessions/:sessionId/stop`
-- `POST /api/sessions/:sessionId/approvals/:requestId`
-- `WS /ws/sessions/:sessionId`
+- developers already using Codex
+- people tired of terminal-only workflows
+- anyone who wants **control, not just output**
+- multi-device workflows
 
-## What Is Not Finished Yet
+---
 
-This is the honest list:
+## ⚠️ What’s not finished yet
 
 - no polished installer yet
-- no desktop packaging yet
-- no full automated test suite yet
-- no production-grade auth / multi-user hardening yet
-- no release pipeline yet
-
-If you are comfortable running a local Node app or a small CLI tool, you can use it today.
-
-## Roadmap
+- no desktop packaging
+- no production-grade auth
+- no release pipeline
 
-Near-term:
+If you're comfortable running a local Node app —  
+you can use it today.
 
-- improve onboarding and installation
-- ship a cleaner public README and screenshots
-- add stronger regression coverage
-- harden long-running session recovery
-- continue refining the execution timeline UI
+---
 
-Later:
+## 📄 License
 
-- improve the first-run install and update experience
-- optional sync / multi-device helpers
-- stronger sharing, auditing, and team workflows
+MIT License

package/dist/server/src/cli.js

@@ -242,8 +242,9 @@ async function main() {
         usage();
         return;
     }
-    const command = argv[0] && !argv[0].startsWith("-") ? argv[0] : "start";
-    const flagArgs = command === "start" ? argv.slice(1) : argv;
+    const hasExplicitCommand = Boolean(argv[0] && !argv[0].startsWith("-"));
+    const command = hasExplicitCommand ? argv[0] : "start";
+    const flagArgs = hasExplicitCommand ? argv.slice(1) : argv;
     const flags = parseFlags(flagArgs);
     switch (command) {
         case "start":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remcodex",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "description": "Control Codex from anywhere. Even on your phone.",
   "license": "MIT",
   "bin": {

package/web/i18n/locales/en.js

@@ -64,9 +64,9 @@ export default {
   "projects.registryEyebrow": "Project registry",
   "projects.addTitle": "Add project",
   "projects.name": "Project name",
-  "projects.namePlaceholder": "e.g. easygo-service",
+  "projects.namePlaceholder": "e.g. my-service",
   "projects.path": "Local path",
-  "projects.pathPlaceholder": "/workspace/easygo-service",
+  "projects.pathPlaceholder": "/workspace/my-service",
   "projects.register": "Register project",
   "projects.listTitle": "Projects",
   "projects.count": ({ count }) => (count === 1 ? "1 project" : `${count} projects`),

package/web/i18n/locales/zh-CN.js

@@ -64,9 +64,9 @@ export default {
   "projects.registryEyebrow": "项目登记",
   "projects.addTitle": "新增项目",
   "projects.name": "项目名",
-  "projects.namePlaceholder": "例如 easygo-service",
+  "projects.namePlaceholder": "例如 my-service",
   "projects.path": "本地路径",
-  "projects.pathPlaceholder": "/workspace/easygo-service",
+  "projects.pathPlaceholder": "/workspace/my-service",
   "projects.register": "登记项目",
   "projects.listTitle": "项目列表",
   "projects.count": ({ count }) => `${count} 个项目`,