remcodex 0.1.0-beta.1 → 0.1.0-beta.10

package/README.md

@@ -1,81 +1,104 @@
-# 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
+
+> Remote control for Codex.  
+> From your browser and phone.
+
+Run Codex on one machine.  
+Monitor, approve, and control the same session from another.
+
+🌐 https://remcodex.com
+
+> Not a remote desktop. Not a proxy.  
+> A local-first way to control Codex away from the terminal.
+
+![RemCodex hero cover](docs/assets/hero-cover.png)
+
+---
+
+## ✨ What is RemCodex?
+
+RemCodex is **remote control for Codex**.
+
+It lets you start Codex on one machine, then keep the same session visible,
+interruptible, and controllable from another.
+
+- 👀 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
 
-- 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
+The session continues instantly.
 
-## Status
+> Everything else can disconnect — your session won’t.
 
-This project is currently a **beta / developer preview**.
+---
 
-MIT licensed — free for personal and commercial use.
+## 🔥 Why RemCodex exists
 
-Cloud version coming soon.
+AI coding agents are powerful.  
+But today, they run like a black box.
 
-It is already usable for local and internal workflows, but it is not yet packaged as a one-click desktop app.
+You either:
 
-## Why People Use It
+- trust everything blindly
+- or sit in front of your terminal watching it
 
-Codex is powerful in the terminal, but many real workflows need a better control surface:
+RemCodex fixes that.
 
-- 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
+> AI is no longer a black box.
 
-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
 
-- 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
+- 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
 
-## Screenshots
+> 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)
 
@@ -91,241 +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.
+
+---
+
+## 🧠 What it actually is
+
+RemCodex is a **browser-based workspace for Codex sessions**.
 
-## Who It Is For
+It is built for real workflows:
 
-- 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
+- long-running sessions
+- mobile check-ins
+- approval prompts
+- imported rollout history
+- timeline-style execution flow
 
-## Screens It Aims To Replace
+Instead of raw terminal logs, you get a structured, visual timeline you can follow and control.
 
-- 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
+---
 
-## 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
+---
 
-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
 
-Then open:
+- Import from `~/.codex/sessions/...`
+- Keep syncing if still active
+- Unified view with native sessions
+
+---
+
+## 🧠 Architecture
 
-```text
-http://127.0.0.1:3000
+```
+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
 ```
 
-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
-```
+## 📦 Install FAQ
+
+### Why does `npx remcodex` hang on Linux?
+
+First install may compile native deps:
+
+- `better-sqlite3`
+- `node-pty`
+
+Make sure you have:
+
+- `python3`
+- `make`
+- `g++`
 
-Planned install target after the npm package is published:
+---
+
+### Debug install issues
 
 ```bash
-npx remcodex
+npm install -g remcodex
+remcodex doctor
+remcodex start
 ```
 
-## Development
+---
+
+### Headless mode
 
 ```bash
-npm install
-npm run dev
+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
-
-### 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
-```
+- Beta / developer preview
+- Local-first architecture
+- No cloud dependency
 
-## Main Endpoints
+---
 
-- `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`
+## 🗺 Roadmap
 
-## What Is Not Finished Yet
+**Visibility**
 
-This is the honest list:
+- fully observable execution
+- clear action timeline
 
-- 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**
+
+- fine-grained approvals
+- safer execution
 
-If you are comfortable cloning a repo and running a local Node app, you can use it today.
+**Continuity**
 
-## Roadmap
+- survive refresh / sleep
+- stable long runs
 
-Near-term:
+**Access**
 
-- 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
+- control from any device
 
-Later:
+**Integration**
+
+- IDE integrations
+- optional sharing
+
+---
+
+## 👥 Who it’s for
+
+- 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
 
-- 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

@@ -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/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/codex-rollout-sync.js

@@ -9,6 +9,7 @@ const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const errors_1 = require("../utils/errors");
 const ids_1 = require("../utils/ids");
+const output_limits_1 = require("../utils/output-limits");
 function computeSourceRolloutHasOpenTurnFromRecords(records) {
     const openTurnIds = new Set();
     for (const record of records) {
@@ -571,22 +572,7 @@ function translateRolloutRecords(records, emitFromRecordIndex = 0) {
                     : `call_${index}`;
                 const started = commandStarts.get(callId) || null;
                 const parsed = parseExecOutput(payload.output);
-                if (parsed.outputText) {
-                    appendSemantic(index, {
-                        type: "command.output.delta",
-                        turnId: currentTurnId,
-                        messageId: null,
-                        callId,
-                        requestId: null,
-                        phase: null,
-                        stream: "stdout",
-                        payload: {
-                            stream: "stdout",
-                            textDelta: parsed.outputText,
-                        },
-                        timestamp,
-                    });
-                }
+                const cappedOutput = parsed.outputText ? (0, output_limits_1.capTextValue)(parsed.outputText) : null;
                 appendSemantic(index, {
                     type: "command.end",
                     turnId: currentTurnId,
@@ -598,6 +584,9 @@ function translateRolloutRecords(records, emitFromRecordIndex = 0) {
                     payload: {
                         command: parsed.commandLine || started?.commandPayload.command || null,
                         cwd: started?.commandPayload.cwd || null,
+                        stdout: cappedOutput?.text || null,
+                        aggregatedOutput: cappedOutput?.text || null,
+                        stdoutTruncated: cappedOutput?.truncated || undefined,
                         status: parsed.exitCode == null
                             ? "completed"
                             : parsed.exitCode === 0