remcodex 0.1.0-beta.11 → 0.1.0-beta.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RemCodex contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,104 @@
-# RemCodex
+# 🚀 RemCodex
 
-> Control Codex from anywhere. Even on your phone.
+> Remote control for Codex.  
+> From your browser and phone.
 
-RemCodex is a local-first web UI for running, reviewing, approving, and resuming Codex sessions from your browser.
+Run Codex on one machine.  
+Monitor, approve, and control the same session from another.
 
-It is built for the real workflow: long-running sessions, mobile check-ins, approval prompts, imported rollout history, and timeline-style execution flow.
+🌐 https://remcodex.com
 
-- 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
+> Not a remote desktop. Not a proxy.  
+> A local-first way to control Codex away from the terminal.
 
-## Status
+![RemCodex hero cover](docs/assets/hero-cover.png)
 
-This project is currently a **beta / developer preview**.
+---
 
-It is already usable for local and internal workflows, but it is not yet packaged as a one-click desktop app.
+## ✨ What is RemCodex?
 
-## Why People Use It
+RemCodex is **remote control for Codex**.
 
-Codex is powerful in the terminal, but many real workflows need a better control surface:
+It lets you start Codex on one machine, then keep the same session visible,
+interruptible, and controllable from another.
 
-- 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
+- 👀 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
 
-RemCodex turns Codex's event stream into a browser-based workspace that is easier to follow, easier to resume, and easier to operate.
+> One session. Any device.
 
-## What It Does
+---
 
-- 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
+## 🎬 A real workflow
 
-## Screenshots
+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.
+
+---
+
+## 🔥 Why RemCodex exists
+
+AI coding agents are powerful.  
+But today, they run like a black box.
+
+You either:
+
+- trust everything blindly
+- or sit in front of your terminal watching it
+
+RemCodex fixes that.
+
+> AI is no longer a black box.
+
+---
+
+## ⚡ 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
+
+> No extra client install. Just open a browser.  
+> Your code never leaves your machine.
+
+---
+
+## 🚀 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)
 
@@ -55,268 +114,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
+---
 
-- 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
+## 🧠 What it actually is
 
-## Screens It Aims To Replace
+RemCodex is a **browser-based workspace for Codex sessions**.
 
-- 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
+It is built for real workflows:
 
-## Current Product Shape
+- long-running sessions
+- mobile check-ins
+- approval prompts
+- imported rollout history
+- timeline-style execution flow
+
+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 20.x 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 developer preview, the recommended local install path is:
+---
 
-```bash
-npm install
-npm run build
-npm link
-remcodex start
-```
+### Imported sessions
 
-If you switch Node.js versions later, reinstall dependencies and relink or reinstall `remcodex`.
+- Import from `~/.codex/sessions/...`
+- Keep syncing if still active
+- Unified view with native sessions
 
-Then open:
+---
 
-```text
-http://127.0.0.1:3000
+## 🧠 Architecture
+
+```
+Codex CLI → Event stream → Semantic layer → Timeline → Web UI
 ```
 
-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.
+---
 
-## Local CLI
+## ⚙️ Requirements
 
-RemCodex already ships with a local CLI entrypoint, even though the npm package is not published yet.
+- Node.js
+- Codex CLI (already working locally)
 
-If you do not want to run `npm link`, you can call the built CLI directly:
+---
 
-```bash
-node dist/server/src/cli.js start --no-open
-```
+## ⚙️ Configuration
 
-Useful commands:
+Default port: **18840**
 
 ```bash
-node dist/server/src/cli.js doctor
-node dist/server/src/cli.js start --no-open
-node dist/server/src/cli.js version
+PORT=18841 npx remcodex
 ```
 
-Published package note:
+---
 
-- the npm package currently expects Node.js 20.x
-- if `better-sqlite3` or `node-pty` reports a native module / `NODE_MODULE_VERSION` error, reinstall `remcodex` under the same Node.js version you will use to run it
+## 📦 Install FAQ
 
-Use a specific database:
+### Why does `npx remcodex` hang on Linux?
 
-```bash
-node dist/server/src/cli.js start --db ~/.remcodex/remcodex-demo.db --no-open
-node dist/server/src/cli.js doctor --db ~/.remcodex/remcodex-demo.db
-```
+First install may compile native deps:
 
-Planned install target after the npm package is published:
+- `better-sqlite3`
+- `node-pty`
 
-```bash
-npx remcodex
-```
+Make sure you have:
 
-## Development
+- `python3`
+- `make`
+- `g++`
 
-```bash
-npm install
-npm run dev
-```
+---
 
-Smoke-test the published-package shape locally:
+### Debug install issues
 
 ```bash
-npm run smoke:tarball
+npm install -g remcodex
+remcodex doctor
+remcodex start
 ```
 
-Smoke-test a real isolated startup and `/health` check:
+---
+
+### Headless mode
 
 ```bash
-npm run smoke:start
+npx remcodex --no-open
 ```
 
-## How It Works
-
-The app uses `codex app-server` as the primary runtime path.
+---
 
-At a high level:
+## 🔧 How it works
 
-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
+1. Codex emits events
+2. Backend stores them (SQLite)
+3. Frontend loads timeline snapshot
+4. Live updates stream via WebSocket
 
-This gives the UI:
+Result:
 
-- smooth streaming
 - recoverable sessions
-- imported rollout support
-- a consistent execution timeline instead of raw terminal logs
+- real-time UI
+- consistent execution flow
 
-## Key Behaviors
+---
 
-### Approvals
+## 📊 Status
 
-- 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
+- Beta / developer preview
+- Local-first architecture
+- No cloud dependency
 
-### 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
+## 🗺 Roadmap
 
-### Timeline and Execution Flow
+**Visibility**
 
-- 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
+- fully observable execution
+- clear action timeline
 
-## Configuration
+**Control**
 
-Supported environment variables:
+- fine-grained approvals
+- safer execution
 
-- `PORT`
-- `DATABASE_PATH`
-- `PROJECT_ROOTS`
-- `CODEX_COMMAND`
-- `CODEX_MODE`
+**Continuity**
 
-For launch screenshots or demo data, you can rebuild a clean demo database with:
+- survive refresh / sleep
+- stable long runs
 
-```bash
-DATABASE_PATH="$HOME/.remcodex/remcodex-demo.db" ~/.nvm/versions/node/v20.19.5/bin/node scripts/seed-launch-demo-data.js --clean
-```
-- `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
-  import-codex-rollout.js
-  reset-semantic-demo-data.js
-```
+**Access**
 
-## Main Endpoints
+- control from any device
 
-- `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`
+**Integration**
 
-## What Is Not Finished Yet
+- IDE integrations
+- optional sharing
 
-This is the honest list:
+---
 
-- 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 cloning a repo and running a local Node app, 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
 
-Near-term:
+---
 
-- 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
+## ⚠️ What’s not finished yet
 
-Later:
+- no polished installer yet
+- no desktop packaging
+- no production-grade auth
+- no release pipeline
 
-- package for easier local install
-- optional sync / multi-device helpers
-- stronger sharing, auditing, and team workflows
+If you're comfortable running a local Node app —  
+you can use it today.
 
-## License
+---
 
-No license has been added yet.
+## 📄 License
 
-Until a license is added, assume this repository is **source-available for review only**, not open source for reuse.
+MIT License

package/dist/server/src/app.js

@@ -25,7 +25,7 @@ const command_1 = require("./utils/command");
 const errors_1 = require("./utils/errors");
 function buildRemCodexServer(options = {}) {
     const repoRoot = options.repoRoot ? node_path_1.default.resolve(options.repoRoot) : (0, runtime_paths_1.resolvePackageRoot)();
-    const port = options.port ?? Number.parseInt(process.env.PORT ?? "3000", 10);
+    const port = options.port ?? Number.parseInt(process.env.PORT ?? "18840", 10);
     const databasePath = options.databasePath ??
         process.env.DATABASE_PATH ??
         (0, runtime_paths_1.resolveDefaultDatabasePath)();

package/dist/server/src/cli.js

@@ -226,7 +226,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 ?? "18840", 10);
     const codexMode = process.env.CODEX_MODE === "exec-json" ? "exec-json" : "app-server";
     let started = null;
     let activePort = preferredPort;

package/dist/server/src/services/session-manager.js

@@ -279,6 +279,17 @@ class SessionManager {
             seq: event.seq,
         };
     }
+    stopSession(sessionId) {
+        const runtime = this.runners.get(sessionId);
+        if (!runtime || !runtime.runner.isAlive()) {
+            this.setStatus(sessionId, "idle");
+            return { accepted: true };
+        }
+        runtime.stopRequested = true;
+        this.setStatus(sessionId, "stopping");
+        runtime.runner.stop();
+        return { accepted: true };
+    }
     retryApprovalRequest(sessionId, requestId, codexLaunch) {
         const session = this.getSessionOrThrow(sessionId);
         const project = this.options.projectManager.getProject(session.project_id);
@@ -303,17 +314,6 @@ class SessionManager {
             turnId,
         };
     }
-    stopSession(sessionId) {
-        const runtime = this.runners.get(sessionId);
-        if (!runtime || !runtime.runner.isAlive()) {
-            this.setStatus(sessionId, "idle");
-            return { accepted: true };
-        }
-        runtime.stopRequested = true;
-        this.setStatus(sessionId, "stopping");
-        runtime.runner.stop();
-        return { accepted: true };
-    }
     resolveApproval(sessionId, requestId, decision) {
         const runtime = this.runners.get(sessionId);
         if (!runtime?.runner.isAlive()) {

package/package.json

@@ -1,11 +1,8 @@
 {
   "name": "remcodex",
-  "version": "0.1.0-beta.11",
+  "version": "0.1.0-beta.12",
   "description": "Control Codex from anywhere. Even on your phone.",
-  "license": "UNLICENSED",
-  "engines": {
-    "node": "20.x"
-  },
+  "license": "MIT",
   "bin": {
     "remcodex": "dist/server/src/cli.js"
   },
@@ -14,16 +11,15 @@
     "web",
     "scripts/check-node-version.js",
     "scripts/fix-node-pty-helper.js",
-    "README.md",
-    "docs/assets"
+    "README.md"
   ],
   "scripts": {
-    "preinstall": "node scripts/check-node-version.js",
     "postinstall": "node scripts/fix-node-pty-helper.js",
     "dev": "tsx watch server/src/app.ts",
     "start": "tsx server/src/cli.ts --no-open",
     "build": "tsc -p tsconfig.json && node scripts/copy-db-assets.js",
     "cli": "tsx server/src/cli.ts --no-open",
+    "preinstall": "node scripts/check-node-version.js",
     "smoke:tarball": "node scripts/smoke-test-tarball.js",
     "smoke:start": "node scripts/smoke-start-tarball.js"
   },
@@ -40,5 +36,8 @@
     "@types/ws": "^8.5.14",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": "20.x"
   }
 }