remcodex 0.1.0-beta.1

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

@@ -0,0 +1,331 @@
+# 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
+```
+
+- 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
+
+This project is currently a **beta / developer preview**.
+
+MIT licensed — free for personal and commercial use.
+
+Cloud version coming soon.
+
+It is already usable for local and internal workflows, but it is not yet packaged as a one-click desktop app.
+
+## Why People Use It
+
+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
+
+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
+
+- 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
+
+![RemCodex desktop workspace](docs/assets/hero-desktop.png)
+
+> Run and review Codex sessions in a single-page workspace.
+
+![RemCodex mobile session view](docs/assets/mobile-session.png)
+
+> Follow a live Codex session from your phone.
+
+![RemCodex approval flow](docs/assets/approval-flow.png)
+
+> Approve sensitive file-system actions from the UI.
+
+![RemCodex imported Codex session](docs/assets/imported-session.png)
+
+> Bring imported Codex rollouts into the same workspace and keep them easy to review.
+
+## 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
+
+## Screens It Aims To Replace
+
+- 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
+
+- Single-page workspace UI
+- Left sidebar for session navigation
+- Right-side timeline / execution flow for the active session
+- Fixed composer at the bottom
+- Semantic timeline rendering for:
+  - user messages
+  - assistant commentary / final messages
+  - 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`
+
+## Requirements
+
+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
+
+This project is currently developed primarily around a local macOS workflow.
+
+## Quick Start
+
+For the current developer preview, the recommended local install path is:
+
+```bash
+npm install
+npm run build
+npm link
+remcodex start
+```
+
+Then open:
+
+```text
+http://127.0.0.1:3000
+```
+
+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
+
+RemCodex already ships with a local CLI entrypoint, even though the npm package is not published yet.
+
+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
+```
+
+Useful commands:
+
+```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:
+
+```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
+```
+
+Planned install target after the npm package is published:
+
+```bash
+npx remcodex
+```
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+## How It Works
+
+The app uses `codex app-server` as the primary runtime path.
+
+At a high level:
+
+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
+
+This gives the UI:
+
+- smooth streaming
+- recoverable sessions
+- imported rollout support
+- a consistent execution timeline instead of raw terminal logs
+
+## Key Behaviors
+
+### 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
+
+- `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`
+
+## What Is Not Finished Yet
+
+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.
+
+## Roadmap
+
+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
+
+Later:
+
+- package for easier local install
+- optional sync / multi-device helpers
+- stronger sharing, auditing, and team workflows
+
+## License
+
+No license has been added yet.
+
+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

@@ -0,0 +1,186 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePackageRoot = resolvePackageRoot;
+exports.resolveDefaultDatabasePath = resolveDefaultDatabasePath;
+exports.startRemCodexServer = startRemCodexServer;
+const node_fs_1 = require("node:fs");
+const node_http_1 = __importDefault(require("node:http"));
+const node_os_1 = require("node:os");
+const node_path_1 = __importDefault(require("node:path"));
+const express_1 = __importDefault(require("express"));
+const codex_options_controller_1 = require("./controllers/codex-options.controller");
+const message_controller_1 = require("./controllers/message.controller");
+const project_controller_1 = require("./controllers/project.controller");
+const session_controller_1 = require("./controllers/session.controller");
+const client_1 = require("./db/client");
+const migrations_1 = require("./db/migrations");
+const ws_gateway_1 = require("./gateways/ws.gateway");
+const event_store_1 = require("./services/event-store");
+const codex_rollout_sync_1 = require("./services/codex-rollout-sync");
+const project_manager_1 = require("./services/project-manager");
+const session_manager_1 = require("./services/session-manager");
+const session_timeline_service_1 = require("./services/session-timeline-service");
+const command_1 = require("./utils/command");
+const errors_1 = require("./utils/errors");
+function isPackageRoot(root) {
+    return ((0, node_fs_1.existsSync)(node_path_1.default.join(root, "package.json")) &&
+        (0, node_fs_1.existsSync)(node_path_1.default.join(root, "web", "index.html")));
+}
+function resolvePackageRoot(startDir = __dirname) {
+    let current = node_path_1.default.resolve(startDir);
+    while (true) {
+        if (isPackageRoot(current)) {
+            return current;
+        }
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return process.cwd();
+}
+function resolveDefaultDatabasePath() {
+    return node_path_1.default.join((0, node_os_1.homedir)(), ".remcodex", "remcodex.db");
+}
+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 databasePath = options.databasePath ??
+        process.env.DATABASE_PATH ??
+        resolveDefaultDatabasePath();
+    const codexCommand = (0, command_1.resolveExecutable)(options.codexCommand ?? process.env.CODEX_COMMAND ?? "codex");
+    const codexMode = options.codexMode ?? (process.env.CODEX_MODE === "exec-json" ? "exec-json" : "app-server");
+    const projectRootsEnv = options.projectRootsEnv ?? process.env.PROJECT_ROOTS;
+    (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(databasePath), { recursive: true });
+    const db = (0, client_1.createDatabase)(databasePath);
+    (0, migrations_1.runMigrations)(db);
+    const eventStore = new event_store_1.EventStore(db);
+    const sessionTimeline = new session_timeline_service_1.SessionTimelineService(eventStore);
+    const projectManager = new project_manager_1.ProjectManager(db, projectRootsEnv, repoRoot);
+    const codexRolloutSync = new codex_rollout_sync_1.CodexRolloutSyncService(db);
+    const sessionManager = new session_manager_1.SessionManager({
+        db,
+        eventStore,
+        projectManager,
+        codexCommand,
+        codexMode,
+    });
+    const app = (0, express_1.default)();
+    const server = node_http_1.default.createServer(app);
+    app.use(express_1.default.json({ limit: "1mb" }));
+    app.get("/health", (_request, response) => {
+        response.json({
+            ok: true,
+            codexMode,
+            codexCommand,
+            projectRoots: projectManager.listAllowedRoots(),
+            now: new Date().toISOString(),
+        });
+    });
+    app.use("/api/projects", (0, project_controller_1.createProjectRouter)(projectManager));
+    app.use("/api/codex", (0, codex_options_controller_1.createCodexOptionsRouter)({
+        sessionManager,
+        projectManager,
+        eventStore,
+        codexMode,
+        codexRolloutSync,
+    }));
+    app.use("/api/sessions", (0, session_controller_1.createSessionRouter)(sessionManager, eventStore, projectManager, codexRolloutSync, sessionTimeline));
+    app.use("/api/sessions/:sessionId/messages", (0, message_controller_1.createMessageRouter)(sessionManager));
+    const webRoot = node_path_1.default.join(repoRoot, "web");
+    app.use(express_1.default.static(webRoot));
+    app.get("/", (_request, response) => {
+        response.sendFile(node_path_1.default.join(webRoot, "index.html"));
+    });
+    app.use((error, _request, response, _next) => {
+        if ((0, errors_1.isAppError)(error)) {
+            response.status(error.statusCode).json({ error: error.message });
+            return;
+        }
+        const message = error instanceof Error ? error.message : "Internal server error";
+        response.status(500).json({
+            error: message,
+        });
+    });
+    (0, ws_gateway_1.registerSessionGateway)(server, {
+        eventStore,
+        sessionManager,
+    });
+    return {
+        app,
+        server,
+        closeDatabase: () => {
+            const closable = db;
+            closable.close?.();
+        },
+        port,
+        repoRoot,
+        databasePath,
+        codexCommand,
+        codexMode,
+        projectRoots: projectManager.listAllowedRoots(),
+        logStartup: options.logStartup ?? true,
+    };
+}
+async function startRemCodexServer(options = {}) {
+    const built = buildRemCodexServer(options);
+    await new Promise((resolve, reject) => {
+        const handleError = (error) => {
+            built.server.off("listening", handleListening);
+            reject(error);
+        };
+        const handleListening = () => {
+            built.server.off("error", handleError);
+            resolve();
+        };
+        built.server.once("error", handleError);
+        built.server.once("listening", handleListening);
+        built.server.listen(built.port);
+    });
+    if (built.logStartup) {
+        console.log(JSON.stringify({
+            message: "RemCodex listening",
+            port: built.port,
+            codexMode: built.codexMode,
+            databasePath: built.databasePath,
+            codexCommand: built.codexCommand,
+        }));
+    }
+    return {
+        app: built.app,
+        server: built.server,
+        port: built.port,
+        repoRoot: built.repoRoot,
+        databasePath: built.databasePath,
+        codexCommand: built.codexCommand,
+        codexMode: built.codexMode,
+        projectRoots: built.projectRoots,
+        stop: () => new Promise((resolve, reject) => {
+            built.server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                built.closeDatabase();
+                resolve();
+            });
+        }),
+    };
+}
+async function main() {
+    await startRemCodexServer();
+}
+if (require.main === module) {
+    void main().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(JSON.stringify({
+            message: "Failed to start RemCodex",
+            error: message,
+        }));
+        process.exitCode = 1;
+    });
+}