remcodex 0.1.0-beta.6 → 0.1.0-beta.7

package/README.md

@@ -1,104 +1,45 @@
-# 🚀 RemCodex
+# RemCodex
 
-> Remote control for Codex.  
-> From your browser and phone.
+> Control Codex from anywhere. Even on your phone.
 
-Run Codex on one machine.  
-Monitor, approve, and control the same session from another.
+RemCodex is a local-first web UI for running, reviewing, approving, and resuming Codex sessions from your browser.
 
-🌐 https://remcodex.com
+It is built for the real workflow: long-running sessions, mobile check-ins, approval prompts, imported rollout history, and timeline-style execution flow.
 
-> Not a remote desktop. Not a proxy.  
-> A local-first way to control Codex away from the terminal.
+- 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
 
-![RemCodex hero cover](docs/assets/hero-cover.png)
+## Status
 
----
+This project is currently a **beta / developer preview**.
 
-## ✨ What is RemCodex?
+It is already usable for local and internal workflows, but it is not yet packaged as a one-click desktop app.
 
-RemCodex is **remote control for Codex**.
+## Why People Use It
 
-It lets you start Codex on one machine, then keep the same session visible,
-interruptible, and controllable from another.
+Codex is powerful in the terminal, but many real workflows need a better control surface:
 
-- 👀 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
+- 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
 
-> One session. Any device.
+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
 
-## 🎬 A real workflow
+- 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
 
-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
+## Screenshots
 
 ![RemCodex desktop workspace](docs/assets/hero-desktop.png)
 
@@ -114,203 +55,249 @@ http://<your-ip>:18840
 
 ![RemCodex imported Codex session](docs/assets/imported-session.png)
 
-> Bring imported Codex rollouts into the same workspace.
-
----
+> Bring imported Codex rollouts into the same workspace and keep them easy to review.
 
-## 🧠 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 execution timeline
-- Fixed input composer
+- Right-side timeline / execution flow for the active session
+- Fixed composer at the bottom
 - Semantic timeline rendering for:
-    - user messages
-    - assistant output
-    - thinking
-    - commands
-    - patches
-    - approvals
-    - system events
-
----
-
-## ⚙️ Key behaviors
+  - user messages
+  - assistant commentary / final messages
+  - thinking
+  - commands
+  - patches
+  - approvals
+  - system events
 
-### Approvals
-
-- Writes inside working area → auto allowed
-- Writes outside → require approval
-- `Allow once` / `Allow for this turn` supported
-- Approval history stays visible in timeline
+## 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`
 
-### Timeline
+## Requirements
 
-- Semantic rendering (not raw logs)
-- Commands grouped into readable activity blocks
-- Running / failed states clearly visible
-- Smooth streaming + recovery after refresh
+Before running this project, you should have:
 
----
+- Node.js installed
+- Codex CLI installed and already working locally
+- A machine where this app can access your local Codex data and working directories
 
-### Imported sessions
+This project is currently developed primarily around a local macOS workflow.
 
-- Import from `~/.codex/sessions/...`
-- Keep syncing if still active
-- Unified view with native sessions
+## Quick Start
 
----
+For the current developer preview, the recommended local install path is:
 
-## 🧠 Architecture
-
-```
-Codex CLI → Event stream → Semantic layer → Timeline → Web UI
+```bash
+npm install
+npm run build
+npm link
+remcodex start
 ```
 
----
+Then open:
 
-## ⚙️ Requirements
+```text
+http://127.0.0.1:3000
+```
 
-- Node.js
-- Codex CLI (already working locally)
+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
 
-## ⚙️ Configuration
+RemCodex already ships with a local CLI entrypoint, even though the npm package is not published yet.
 
-Default port: **18840**
+If you do not want to run `npm link`, you can call the built CLI directly:
 
 ```bash
-PORT=18841 npx remcodex
+node dist/server/src/cli.js start --no-open
 ```
 
----
-
-## 📦 Install FAQ
-
-### Why does `npx remcodex` hang on Linux?
-
-First install may compile native deps:
-
-- `better-sqlite3`
-- `node-pty`
+Useful commands:
 
-Make sure you have:
+```bash
+node dist/server/src/cli.js doctor
+node dist/server/src/cli.js start --no-open
+node dist/server/src/cli.js version
+```
 
-- `python3`
-- `make`
-- `g++`
+Use a specific database:
 
----
+```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
+```
 
-### Debug install issues
+Planned install target after the npm package is published:
 
 ```bash
-npm install -g remcodex
-remcodex doctor
-remcodex start
+npx remcodex
 ```
 
----
-
-### Headless mode
+## Development
 
 ```bash
-npx remcodex --no-open
+npm install
+npm run dev
 ```
 
----
+## How It Works
+
+The app uses `codex app-server` as the primary runtime path.
 
-## 🔧 How it works
+At a high level:
 
-1. Codex emits events
-2. Backend stores them (SQLite)
-3. Frontend loads timeline snapshot
-4. Live updates stream via WebSocket
+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
 
-Result:
+This gives the UI:
 
+- smooth streaming
 - recoverable sessions
-- real-time UI
-- consistent execution flow
+- imported rollout support
+- a consistent execution timeline instead of raw terminal logs
 
----
+## Key Behaviors
 
-## 📊 Status
+### Approvals
 
-- Beta / developer preview
-- Local-first architecture
-- No cloud dependency
+- 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
 
-## 🗺 Roadmap
+- 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
 
-**Visibility**
+### Timeline and Execution Flow
 
-- fully observable execution
-- clear action timeline
+- 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
 
-**Control**
+## Configuration
 
-- fine-grained approvals
-- safer execution
+Supported environment variables:
 
-**Continuity**
+- `PORT`
+- `DATABASE_PATH`
+- `PROJECT_ROOTS`
+- `CODEX_COMMAND`
+- `CODEX_MODE`
 
-- survive refresh / sleep
-- stable long runs
+For launch screenshots or demo data, you can rebuild a clean demo database with:
 
-**Access**
+```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
+```
 
-- control from any device
+## Main Endpoints
 
-**Integration**
+- `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`
 
-- IDE integrations
-- optional sharing
+## What Is Not Finished Yet
 
----
+This is the honest list:
 
-## 👥 Who it’s for
+- 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
 
-- developers already using Codex
-- people tired of terminal-only workflows
-- anyone who wants **control, not just output**
-- multi-device workflows
+If you are comfortable cloning a repo and running a local Node app, you can use it today.
 
----
+## Roadmap
 
-## ⚠️ What’s not finished yet
+Near-term:
 
-- no polished installer yet
-- no desktop packaging
-- no production-grade auth
-- no release pipeline
+- 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:
 
-If you're comfortable running a local Node app —  
-you can use it today.
+- package for easier local install
+- optional sync / multi-device helpers
+- stronger sharing, auditing, and team workflows
 
----
+## License
 
-## 📄 License
+No license has been added yet.
 
-MIT License
+Until a license is added, assume this repository is **source-available for review only**, not open source for reuse.

package/dist/server/src/app.js

@@ -3,7 +3,6 @@ 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;
@@ -47,10 +46,9 @@ 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 ?? String(exports.DEFAULT_PORT), 10);
+    const port = options.port ?? Number.parseInt(process.env.PORT ?? "3000", 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 ?? String(app_1.DEFAULT_PORT), 10);
+    const preferredPort = flags.port ?? Number.parseInt(process.env.PORT ?? "3000", 10);
     const codexMode = process.env.CODEX_MODE === "exec-json" ? "exec-json" : "app-server";
     let started = null;
     let activePort = preferredPort;

package/dist/server/src/controllers/session.controller.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSessionRouter = createSessionRouter;
 const express_1 = require("express");
+const codex_launch_1 = require("../utils/codex-launch");
 function createSessionRouter(sessionManager, eventStore, projectManager, codexRolloutSync, sessionTimeline) {
     const router = (0, express_1.Router)();
     router.get("/", (_request, response) => {
@@ -171,5 +172,16 @@ function createSessionRouter(sessionManager, eventStore, projectManager, codexRo
             next(error);
         }
     });
+    router.post("/:sessionId/approvals/:requestId/retry", (request, response, next) => {
+        try {
+            const body = request.body;
+            const launch = (0, codex_launch_1.normalizeCodexExecLaunchInput)(body.codex);
+            const result = sessionManager.retryApprovalRequest(request.params.sessionId, request.params.requestId, launch);
+            response.json(result);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
     return router;
 }

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

@@ -277,6 +277,30 @@ class SessionManager {
             seq: event.seq,
         };
     }
+    retryApprovalRequest(sessionId, requestId, codexLaunch) {
+        const session = this.getSessionOrThrow(sessionId);
+        const project = this.options.projectManager.getProject(session.project_id);
+        if (!project) {
+            throw new errors_1.AppError(404, "Project not found for session.");
+        }
+        const currentRunner = this.runners.get(sessionId);
+        const busyStatuses = ["starting", "running", "stopping"];
+        if (currentRunner?.runner.isAlive() && busyStatuses.includes(session.status)) {
+            throw new errors_1.AppError(409, "Session already has an active task.");
+        }
+        const pending = this.pendingApprovals.get(sessionId)?.get(requestId) ??
+            this.restorePendingApprovalFromEvents(sessionId, requestId);
+        if (!pending) {
+            throw new errors_1.AppError(404, "Approval request not found.");
+        }
+        const turnId = (0, ids_1.createId)("turn");
+        const runtimePrompt = normalizeDemoPrompt(project.path, this.buildApprovalRetryRuntimePrompt(pending));
+        this.startRunner(sessionId, project.path, runtimePrompt, turnId, this.resolveResumeThreadId(session), codexLaunch);
+        return {
+            accepted: true,
+            turnId,
+        };
+    }
     stopSession(sessionId) {
         const runtime = this.runners.get(sessionId);
         if (!runtime || !runtime.runner.isAlive()) {
@@ -1368,6 +1392,35 @@ class SessionManager {
         }
         return null;
     }
+    buildApprovalRetryRuntimePrompt(approval) {
+        const commandText = this.extractApprovalCommand(approval.method, approval.params);
+        const reason = typeof approval.params.reason === "string" && approval.params.reason.trim()
+            ? approval.params.reason.trim()
+            : "";
+        if (commandText) {
+            return [
+                "Re-run the exact operation that previously requested approval.",
+                "Do not do extra exploration.",
+                "As soon as the approval prompt appears again, stop and wait for the user decision.",
+                "",
+                commandText,
+            ].join("\n");
+        }
+        if (reason) {
+            return [
+                "Re-run the exact step that previously requested approval.",
+                "Do not do extra exploration.",
+                "As soon as the approval prompt appears again, stop and wait for the user decision.",
+                "",
+                `Original approval reason: ${reason}`,
+            ].join("\n");
+        }
+        return [
+            "Re-run the exact step that previously requested approval.",
+            "Do not do extra exploration.",
+            "As soon as the approval prompt appears again, stop and wait for the user decision.",
+        ].join("\n");
+    }
     describeApprovalTitle(method) {
         if (method === "item/commandExecution/requestApproval" || method === "execCommandApproval") {
             return "Command execution requires approval";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "remcodex",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.7",
   "description": "Control Codex from anywhere. Even on your phone.",
-  "license": "MIT",
+  "license": "UNLICENSED",
   "bin": {
     "remcodex": "dist/server/src/cli.js"
   },
@@ -10,7 +10,8 @@
     "dist",
     "web",
     "scripts/fix-node-pty-helper.js",
-    "README.md"
+    "README.md",
+    "docs/assets"
   ],
   "scripts": {
     "postinstall": "node scripts/fix-node-pty-helper.js",

package/web/styles.css

@@ -1394,13 +1394,16 @@ button:hover {
 
 .approval-banner {
   display: grid;
+  grid-template-rows: minmax(0, 1fr) auto;
   gap: 0.6rem;
   margin-bottom: 0.7rem;
   padding: 0.72rem 0.82rem;
+  max-height: min(46dvh, 24rem);
   border-radius: 14px;
   border: 1px solid rgba(188, 90, 48, 0.16);
   background: rgba(255, 248, 238, 0.96);
   box-shadow: 0 6px 16px rgba(169, 77, 38, 0.06);
+  overflow: hidden;
 }
 
 .approval-banner[aria-busy="true"] {
@@ -1411,6 +1414,14 @@ button:hover {
 .approval-banner-copy {
   display: grid;
   gap: 0.28rem;
+  min-height: 0;
+  overflow-y: auto;
+  overflow-x: hidden;
+  overscroll-behavior: contain;
+  scrollbar-gutter: stable;
+  -webkit-overflow-scrolling: touch;
+  touch-action: pan-y;
+  padding-right: 0.18rem;
 }
 
 .approval-banner-head {
@@ -1496,6 +1507,9 @@ button:hover {
   display: flex;
   gap: 0.55rem;
   flex-wrap: wrap;
+  flex-shrink: 0;
+  padding-top: 0.15rem;
+  border-top: 1px solid rgba(188, 90, 48, 0.12);
 }
 
 .approval-banner-actions .primary-button,
@@ -5104,6 +5118,13 @@ button:hover {
     padding-right: env(safe-area-inset-right, 0px);
   }
 
+  .composer-panel:has(#session-approval-slot .approval-banner) {
+    max-height: calc(100dvh - env(safe-area-inset-top, 0px) - 3rem);
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    -webkit-overflow-scrolling: touch;
+  }
+
   .composer-dock {
     max-width: 100%;
   }
@@ -5112,6 +5133,7 @@ button:hover {
     gap: 0.45rem;
     margin-bottom: 0.45rem;
     padding: 0.56rem 0.62rem;
+    max-height: min(40dvh, 18rem);
   }
 }
 

package/LICENSE

@@ -1,21 +0,0 @@
-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.