Bring cumulative RemCodex improvements upstream

.cache/3d37c554f4f09215e1f38a0e99af42d5681e0211f2416e8e740a8893b1eee23f.json

@@ -0,0 +1,6 @@
+{
+  "url": "https://remcodex.com/",
+  "markdown": "# RemCodex - Remote Codex Control from Anywhere\nRemote Codex control\nRun Codex on one machine and control the same session from another device. RemCodex is a local-first remote control layer for Codex that gives you a browser and phone view for monitoring progress, approving commands, interrupting work, and resuming remotely.\nIt runs on your machine, not in a cloud IDE or remote desktop. You keep the existing Codex workflow, then open the same live session from your browser or your phone.\n$ `npx remcodex`\nMIT licensed npm package live Local-first\nRuns locally Your code stays on your machine\nBrowser and phone Same session across devices\nRemote actions Monitor, approve, interrupt, resume\nDefault port 18840, with auto fallback\n![RemCodex browser and phone views for remote Codex control](https://remcodex.com/assets/hero-cover.png)\nQuick start\n## How to Control Codex from Another Device\nStart RemCodex on the machine where Codex already runs, open the browser UI locally, then keep the same session available from another device. If you want the full flow, [see how remote Codex control works](https://remcodex.com/how-it-works).\n```\nnpx remcodex\n```\nRemCodex starts locally on `http://127.0.0.1:18840` by default and can also be opened with your host IP when you want remote Codex access from a phone or another browser on the same network.\n1.  Run `npx remcodex` next to the Codex session you want to control.\n2.  Open the browser UI and choose the session you want to monitor or resume.\n3.  Use the same session from your phone or another device when you leave your desk.\nLive demos\n## Use Codex on Your Phone Without Leaving the Same Session\nWatch the desktop and phone walkthroughs side by side. They show the same remote Codex control loop: monitor progress, review events, and stay connected from the browser even when you are away from the machine.\nDesktop walkthrough\n### See remote Codex control in the browser\nFollow the browser workflow for monitoring, approvals, and same-session handoff.\n[RemCodex desktop walkthrough](https://www.youtube-nocookie.com/embed/FNeAIqYps7o?rel=0)\nPhone walkthrough\n### Control Codex from your phone\nSee how phone access stays inside the same session instead of becoming a separate workflow.\n[RemCodex mobile walkthrough](https://www.youtube-nocookie.com/embed/-VuxsfbBmZA?rel=0)\nWhy it exists\n## Why Remote Codex Control Matters\n### The gap\nCodex already works well on a local machine. The friction shows up when a long session keeps running after you leave your desk and still needs supervision, approvals, or an occasional interrupt from another device.\n### What RemCodex adds\nRemCodex adds browser control for Codex without turning the product into a remote desktop, cloud IDE, or generic AI dashboard. It keeps the Codex process local and adds a clean control surface on top.\nGuides\n## What RemCodex Is\nRemCodex is a local-first remote control layer for Codex. These pages cover remote Codex setup, browser control, phone access, and the product boundaries that keep it different from remote desktop tools.\nWorkflow\n## Monitor, Approve, Interrupt, and Resume Remotely\nRemCodex is built for the real moments around a running Codex session: keep watching, respond to approvals, interrupt when the session goes off course, and resume the same run from another device.\n### Monitor a running Codex session\nView commands, edits, approvals, and assistant updates in one execution timeline.\n### Approve Codex commands remotely\nHandle file-system approvals from the browser or your phone without dropping into a raw terminal.\n### Interrupt and resume the same session\nPause or continue the live run instead of creating a second disconnected workflow on another device.\n### Keep remote Codex access local-first\nOpen your own machine from another browser while the code and execution stay where Codex already runs.\nA practical remote Codex loop\n### Control Codex from anywhere without leaving the same session behind.\n1 **Run Codex locally**\nKeep files, processes, and context on your own machine.\n2 **Open the browser UI**\nWatch the live session from your main machine first, then hand it off when needed.\n3 **Approve on your phone**\nReview the pending action remotely and keep the same session moving.\n4 **Interrupt or resume**\nStay in control when you need to pause, recover, or continue the live run.\nScreenshots\n## See the Remote Codex Control Surface\nThese product views show the current browser surface for remote Codex control: desktop monitoring, phone access, approvals, and readable session history.\n![RemCodex desktop browser view for remote Codex control](https://remcodex.com/assets/hero-desktop.png)\n### Desktop workspace\nRun, review, and reconnect to the same Codex session in one browser control surface.\n![RemCodex phone view for Codex remote access](https://remcodex.com/assets/mobile-session.png)\n### Phone view\nUse Codex on your phone when the same session needs attention away from your desk.\n![Browser approval flow for remote Codex commands](https://remcodex.com/assets/approval-flow.png)\n### Approval flow\nApprove sensitive actions remotely instead of juggling raw terminal prompts.\n![RemCodex session history view for Codex remote monitoring](https://remcodex.com/assets/imported-session.png)\n### Session history\nKeep Codex rollouts readable and available from the same browser workspace.\nInstall details\n## Local-First Remote Control for Codex\nThe fastest path is still the npm package. RemCodex starts locally on port `18840` by default, keeps your code on your own machine, and opens a browser control layer for the same Codex session.\n```\nnpx remcodex\n```\nOr install it globally if you plan to keep using remote Codex control every day.\n```\nnpm install -g remcodex\nremcodex\n```\n-   Node.js installed\n-   Codex CLI already working locally\n-   LAN reachability if you want Codex on phone or another device\nNeed more context first? [Read the remote Codex docs](https://remcodex.com/docs) or [check the FAQ about remote Codex access](https://remcodex.com/faq).\nStart now\n## Control the Same Codex Session from Anywhere\nStart locally with `npx remcodex`, then open the same live session from your browser or phone when you need remote Codex control.",
+  "timestamp": 1783042317681,
+  "title": "RemCodex - Remote Codex Control from Anywhere"
+}

README.md

@@ -72,6 +72,7 @@ RemCodex fixes that.
 - Human-in-the-loop command approval
 - Multi-device access to the same live session
 - Resume after refresh, sleep, or reconnect
+- Voice-note prompt capture with local transcription
 - Browser-based UI — **no extra client required**
 - Works with Codex CLI
 
@@ -96,6 +97,28 @@ http://<your-ip>:18840
 
 > Runs entirely on your local machine. No cloud, no data upload.
 
+### RemCodex directory
+
+RemCodex can also serve a directory page that links to multiple RemCodex
+instances. Configure the instances as a JSON array at startup:
+
+```bash
+export REMCODEX_DIRECTORY_INSTANCES='[
+  {"name":"Home","url":"https://remcodex.example","description":"Primary workspace"},
+  {"name":"Lab","url":"https://lab-remcodex.example"}
+]'
+npx remcodex
+```
+
+Then open `/directory` on the RemCodex host. Each configured instance is
+validated and displayed as an openable card.
+
+Nix users can run the packaged server directly:
+
+```bash
+nix run .#
+```
+
 ---
 
 ## 🖥 Screenshots
@@ -128,10 +151,28 @@ It is built for real workflows:
 - mobile check-ins
 - approval prompts
 - imported rollout history
+- discoverable Codex app-server sessions
 - timeline-style execution flow
 
 Instead of raw terminal logs, you get a structured, visual timeline you can follow and control.
 
+### Interactive Codex app-servers
+
+When configured by Panoply, a bare interactive `codex` command starts a Unix-socket
+app-server and records its endpoint under `$XDG_RUNTIME_DIR/codex-app-servers`.
+RemCodex discovers those endpoints, imports their thread history, and can send
+follow-up turns through the same app-server. Remote follow-up turns preserve the
+unattended dangerous-bypass policy and auto-approve tools from discovered MCP
+servers. Explicit Codex subcommands continue to pass directly to the underlying
+CLI.
+
+The workspace sidebar's `+ New session` control also remembers a default
+profile. Pick `Custom` to keep the current project-selection flow, or choose one
+of the defined profiles to reuse it for future UI-started sessions.
+When a profile provides a starting prompt, RemCodex shows it above the composer
+as a temporary banner and prepends it to the first message you send in that
+session.
+
 ---
 
 ## 🧩 Current product shape
@@ -140,6 +181,7 @@ Instead of raw terminal logs, you get a structured, visual timeline you can foll
 - Left sidebar for session navigation
 - Right-side execution timeline
 - Fixed input composer
+- Optional voice-note capture button under send
 - Semantic timeline rendering for:
     - user messages
     - assistant output
@@ -202,6 +244,150 @@ Default port: **18840**
 PORT=18841 npx remcodex
 ```
 
+If RemCodex is reached through a hostname or reverse proxy, set
+`REMCODEX_HOSTNAME` to the public hostname or full HTTP(S) origin. Session
+links returned by the API and MCP tools will use that value; when it is not
+set, they remain relative links:
+
+```bash
+REMCODEX_HOSTNAME=https://remcodex.example.com npx remcodex
+```
+
+The MCP endpoint lives at `POST /mcp`. If `REMCODEX_MCP_API_TOKEN` is set at
+startup, the server will require the matching bearer token on every MCP
+request. If it is not set, MCP stays disabled and the rest of RemCodex still
+starts normally:
+
+```bash
+REMCODEX_MCP_API_TOKEN=secret npx remcodex
+```
+
+Clients must send:
+
+```bash
+Authorization: Bearer secret
+```
+
+To register RemCodex itself as a Codex MCP server, add this to
+`~/.codex/config.toml` and adjust the port or token path if needed:
+
+```toml
+[mcp_servers.remcodex]
+url = "http://127.0.0.1:18840/mcp"
+default_tools_approval_mode = "approve"
+
+[mcp_servers.remcodex.http_headers]
+Authorization = "Bearer $(cat /path/to/remcodex-token)"
+```
+
+If you do not set `REMCODEX_MCP_API_TOKEN` when starting RemCodex, leave the
+`http_headers` table out.
+
+### Interactive TUI wrapper
+
+`remcodex-tui` is a Python wrapper around the Codex CLI. With no arguments it
+starts a local Unix-socket Codex app-server, registers it for RemCodex
+discovery, and launches the interactive TUI through `codex --remote`. Explicit
+Codex arguments pass through unchanged, so commands such as
+`remcodex-tui exec --help` retain normal Codex behavior.
+
+The wrapper honors `CODEX_COMMAND`, `XDG_RUNTIME_DIR`, and
+`CODEX_APP_SERVER_REGISTRY_DIR`.
+
+The MCP `create-session` tool accepts either a `projectId` or a
+`workingDirectory`. Directory requests resolve an existing project and reuse
+the latest non-terminal session for that directory; if the directory is not
+registered yet, RemCodex registers it as a project before creating the session.
+Providing `parentSessionId` always creates a new child session instead of
+reusing an existing one.
+
+The read-only `list-sessions-by-directory` tool returns all sessions recorded
+for a working directory, including completed and failed sessions.
+
+The `resume-session` tool selects an existing session for continued work. It
+can optionally associate the resumed session with a parent session and changes
+terminal session status back to `idle` so the next message can continue it.
+Parenting follows the directory tree: a parent session's project directory
+must contain the child session's project directory.
+
+RemCodex can seed agent profiles from a static TOML config at startup. By
+default it reads `~/.remcodex/config.toml`, and you can override that with
+`REMCODEX_CONFIG_PATH`.
+
+The sample file at `docs/remcodex-profiles.example.toml` shows the supported
+shape:
+
+```toml
+[[profiles]]
+name = "remcodex-demo"
+starting_prompt = "Use RemCodex to inspect the current session, keep the workspace state in view, and prefer small safe changes when testing UI flows."
+default_directory = "/home/evak/programming/by_category/agentic/remcodex"
+```
+
+The profile API still exists for runtime additions, but startup config is the
+preferred way to define the profiles that appear in the new-session dropdown.
+The profile `starting_prompt` becomes a one-time prefix for the first message in
+the session, and the UI banner disappears after that message is sent.
+
+The flake default package wraps `remcodex` with:
+
+- Node.js 20
+- `whisper-ctranslate2`
+- `ffmpeg`
+- a bundled tiny English Whisper model exposed through `REMCODEX_STT_MODEL_PATH`
+
+Examples:
+
+```bash
+nix build .#
+./result/bin/remcodex doctor
+./result/bin/remcodex stt-self-test
+
+nix develop
+remcodex start
+```
+
+For the Web UI reply-drop investigation harness, the flake also exposes a Linux check that:
+
+- boots RemCodex in a local OCI container
+- swaps real Codex calls for a deterministic mock `app-server`
+- streams assistant replies through cumulative `item/updated` events
+- drives repeated chat submissions through Playwright until a reply goes missing or the loop completes
+
+Run it with:
+
+```bash
+nix build .#checks.x86_64-linux.remcodex-debug-output
+```
+
+The package also includes a smoke test for the MCP auth gate:
+
+```bash
+npm run smoke:mcp-auth
+```
+
+Voice-note transcription is optional and stays local. RemCodex will look for a whisper CLI on the server machine in this order:
+
+- `whisper`
+- `whisper.cpp`
+- `whisper-ctranslate2`
+
+You can override that detection with:
+
+```bash
+REMCODEX_STT_BINARY=/path/to/whisper \
+REMCODEX_STT_MODEL_PATH=/path/to/model \
+npx remcodex
+```
+
+When voice transcription is available, the composer shows a microphone button below send. Click once to record, click again to stop, transcribe, and submit the transcript as a normal user prompt in the timeline.
+
+To validate the local transcription wiring without opening the browser:
+
+```bash
+remcodex stt-self-test
+```
+
 ---
 
 ## 📦 Install FAQ

bin/remcodex-tui

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec python3 "$(dirname "$0")/../scripts/remcodex-tui.py" "$@"

docs/remcodex-mcp-config.toml

@@ -0,0 +1,9 @@
+# Example Codex MCP configuration for RemCodex.
+# Copy this into ~/.codex/config.toml and adjust the token path if needed.
+
+[mcp_servers.remcodex]
+url = "http://127.0.0.1:18840/mcp"
+default_tools_approval_mode = "approve"
+
+[mcp_servers.remcodex.http_headers]
+Authorization = "Bearer $(cat /path/to/remcodex-token)"

docs/remcodex-profiles.example.toml

@@ -0,0 +1,16 @@
+# Copy this to ~/.remcodex/config.toml or point REMCODEX_CONFIG_PATH at it.
+
+[[profiles]]
+name = "orchestrator"
+starting_prompt = "Manage delegated Codex work by reusing an existing session in the requested directory or starting a fresh session there when none exists."
+default_directory = "/home/evak/programming"
+
+[[profiles]]
+name = "remcodex-demo"
+starting_prompt = "Use RemCodex to inspect the current session, keep the workspace state in view, and prefer small safe changes when testing UI flows."
+default_directory = "/home/evak/programming/by_category/agentic/remcodex"
+
+[[profiles]]
+name = "remcodex-review"
+starting_prompt = "Review the current RemCodex worktree, summarize risks, and check for regressions before making changes."
+default_directory = "/home/evak/programming/by_category/agentic/remcodex"