remcodex 0.1.0-beta.2 → 0.1.0-beta.4

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.
 
-- 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
+> Everything else can disconnect — your session won’t.
 
-## Status
+---
 
-This project is currently a **beta / developer preview**.
+## 🔥 Why RemCodex exists
 
-MIT licensed — free for personal and commercial use.
+AI coding agents are powerful.  
+But today, they run like a black box.
 
-Cloud version coming soon.
+You either:
 
-It is already usable for local and internal workflows, but it is not yet packaged as a one-click desktop app.
+- trust everything blindly
+- or sit in front of your terminal watching it
 
-## Why People Use It
+RemCodex fixes that.
 
-Codex is powerful in the terminal, but many real workflows need a better control surface:
+> AI is no longer a black box.
 
-- 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
+---
 
-RemCodex turns Codex's event stream into a browser-based workspace that is easier to follow, easier to resume, and easier to operate.
+## ⚡ What it does
 
-## What It Does
+- 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
 
-- 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
+> No extra client install. Just open a browser.  
+> Your code never leaves your machine.
 
-## 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,232 +113,203 @@ 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.
+
+---
 
-## Who It Is For
+## 🧠 What it actually is
 
-- 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
+RemCodex is a **browser-based workspace for Codex sessions**.
 
-## Screens It Aims To Replace
+It is built for real workflows:
 
-- 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
+- long-running sessions
+- mobile check-ins
+- approval prompts
+- imported rollout history
+- timeline-style execution flow
 
-## Current Product Shape
+Instead of raw terminal logs, you get a structured, visual timeline you can follow and control.
+
+---
+
+## 🧩 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
+---
 
-This project is currently developed primarily around a local macOS workflow.
+### Timeline
 
-## Quick Start
+- Semantic rendering (not raw logs)
+- Commands grouped into readable activity blocks
+- Running / failed states clearly visible
+- Smooth streaming + recovery after refresh
 
-For the current beta, the fastest way to try RemCodex is:
+---
+
+### Imported sessions
+
+- Import from `~/.codex/sessions/...`
+- Keep syncing if still active
+- Unified view with native sessions
+
+---
+
+## 🧠 Architecture
 
-```bash
-npx remcodex
 ```
+Codex CLI → Event stream → Semantic layer → Timeline → Web UI
+```
+
+---
+
+## ⚙️ Requirements
+
+- Node.js
+- Codex CLI (already working locally)
 
-You can also install it globally:
+---
+
+## ⚙️ Configuration
+
+Default port: **18840**
 
 ```bash
-npm install -g remcodex
-remcodex
+PORT=18841 npx remcodex
 ```
 
-RemCodex starts a local server and opens the browser for you.
+---
+
+## 📦 Install FAQ
 
-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.
+### Why does `npx remcodex` hang on Linux?
 
-## Local CLI
+First install may compile native deps:
 
-RemCodex also works well from source if you want to develop locally or inspect the runtime setup.
+- `better-sqlite3`
+- `node-pty`
 
-Local development path:
+Make sure you have:
+
+- `python3`
+- `make`
+- `g++`
+
+---
+
+### Debug install issues
 
 ```bash
-npm install
-npm run build
-npm link
+npm install -g remcodex
+remcodex doctor
 remcodex start
 ```
 
-Useful commands:
+---
+
+### Headless mode
 
 ```bash
-node dist/server/src/cli.js doctor
-node dist/server/src/cli.js start --no-open
-node dist/server/src/cli.js version
+npx remcodex --no-open
 ```
 
-Use a specific database:
+---
 
-```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
-```
+## 🔧 How it works
 
-## Development
+1. Codex emits events
+2. Backend stores them (SQLite)
+3. Frontend loads timeline snapshot
+4. Live updates stream via WebSocket
 
-```bash
-npm install
-npm run dev
-```
+Result:
 
-## How It Works
+- recoverable sessions
+- real-time UI
+- consistent execution flow
 
-The app uses `codex app-server` as the primary runtime path.
+---
 
-At a high level:
+## 📊 Status
 
-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
+- Beta / developer preview
+- Local-first architecture
+- No cloud dependency
 
-This gives the UI:
+---
 
-- smooth streaming
-- recoverable sessions
-- imported rollout support
-- a consistent execution timeline instead of raw terminal logs
+## 🗺 Roadmap
 
-## Key Behaviors
+**Visibility**
 
-### Approvals
+- fully observable execution
+- clear action timeline
 
-- 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
-```
+**Control**
 
-## Main Endpoints
+- fine-grained approvals
+- safer execution
 
-- `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`
+**Continuity**
 
-## What Is Not Finished Yet
+- survive refresh / sleep
+- stable long runs
 
-This is the honest list:
+**Access**
 
-- 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
+- control from any device
+
+**Integration**
+
+- IDE integrations
+- optional sharing
+
+---
 
-If you are comfortable running a local Node app or a small CLI tool, you can use it today.
+## 👥 Who it’s for
 
-## Roadmap
+- developers already using Codex
+- people tired of terminal-only workflows
+- anyone who wants **control, not just output**
+- multi-device workflows
+
+---
+
+## ⚠️ What’s not finished yet
+
+- no polished installer yet
+- 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/app.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PORT = void 0;
 exports.resolvePackageRoot = resolvePackageRoot;
 exports.resolveDefaultDatabasePath = resolveDefaultDatabasePath;
 exports.startRemCodexServer = startRemCodexServer;
@@ -46,9 +47,10 @@ function resolvePackageRoot(startDir = __dirname) {
 function resolveDefaultDatabasePath() {
     return node_path_1.default.join((0, node_os_1.homedir)(), ".remcodex", "remcodex.db");
 }
+exports.DEFAULT_PORT = 18840;
 function buildRemCodexServer(options = {}) {
     const repoRoot = options.repoRoot ? node_path_1.default.resolve(options.repoRoot) : resolvePackageRoot();
-    const port = options.port ?? Number.parseInt(process.env.PORT ?? "3000", 10);
+    const port = options.port ?? Number.parseInt(process.env.PORT ?? String(exports.DEFAULT_PORT), 10);
     const databasePath = options.databasePath ??
         process.env.DATABASE_PATH ??
         resolveDefaultDatabasePath();

package/dist/server/src/cli.js

@@ -169,7 +169,7 @@ async function runStart(flags) {
         printError("Install Codex first, or set CODEX_COMMAND to the correct executable.");
         return 1;
     }
-    const preferredPort = flags.port ?? Number.parseInt(process.env.PORT ?? "3000", 10);
+    const preferredPort = flags.port ?? Number.parseInt(process.env.PORT ?? String(app_1.DEFAULT_PORT), 10);
     const codexMode = process.env.CODEX_MODE === "exec-json" ? "exec-json" : "app-server";
     let started = null;
     let activePort = preferredPort;
@@ -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.2",
+  "version": "0.1.0-beta.4",
   "description": "Control Codex from anywhere. Even on your phone.",
   "license": "MIT",
   "bin": {