androdex 1.1.3

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026 Emanuele Di Pietro
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# androdex
+
+`androdex` is the host-side CLI bridge for the Androdex project.
+
+It is published separately from the Android app. The daemon keeps a stable host identity alive on the host machine and lets the Android client control local Codex remotely.
+
+## Install
+
+```sh
+npm install -g androdex
+```
+
+## Usage
+
+```sh
+androdex pair
+androdex up
+androdex daemon status
+androdex reset-pairing
+androdex resume
+androdex watch
+```
+
+## What it does
+
+- keeps a durable relay presence keyed by a stable host id
+- prints a pairing QR code and raw pairing payload on demand
+- activates local `codex app-server` for the current workspace
+- forwards JSON-RPC traffic between the host and the Android client
+- handles git and workspace actions on the host machine
+
+## Commands
+
+### `androdex up`
+
+Activates the current workspace in the daemon and launches `codex app-server` locally if needed.
+
+### `androdex pair`
+
+Prints a fresh pairing QR and raw pairing payload for the already-running daemon identity.
+
+### `androdex daemon [start|stop|status]`
+
+Manages the background daemon that owns the stable host identity and relay presence.
+
+### `androdex reset-pairing`
+
+Clears the saved trusted-device state so the next `androdex pair` starts a fresh pairing flow.
+
+### `androdex resume`
+
+Reopens the last active thread in the local Codex desktop app if available.
+
+### `androdex watch [threadId]`
+
+Tails the rollout log for the selected thread in real time.
+
+## Environment variables
+
+`androdex` accepts `ANDRODEX_*` variables.
+
+Useful variables:
+
+- `ANDRODEX_RELAY`: set the relay URL explicitly
+- `ANDRODEX_CODEX_ENDPOINT`: connect to an existing Codex WebSocket instead of spawning a local runtime
+- `ANDRODEX_REFRESH_ENABLED`: enable the macOS desktop refresh workaround explicitly
+- `ANDRODEX_REFRESH_DEBOUNCE_MS`: adjust refresh debounce timing
+- `ANDRODEX_REFRESH_COMMAND`: override desktop refresh with a custom command
+
+## Source builds
+
+If you cloned the repository and want to run the bridge from source:
+
+```sh
+cd androdex-bridge
+npm install
+npm start
+```
+
+## Project status
+
+This package is part of Androdex, a local-first project focused on the host-machine-plus-Android workflow today.
+
+Credit for the upstream fork chain remains with [relaydex](https://github.com/Ranats/relaydex) and [Remodex](https://github.com/Emanuele-web04/remodex).

package/bin/androdex.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// FILE: androdex.js
+// Purpose: Canonical CLI entrypoint for the Androdex npm package.
+// Layer: CLI binary
+// Exports: none
+// Depends on: ./cli
+
+require("./cli");

package/bin/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// FILE: cli.js
+// Purpose: CLI surface for daemon start, workspace activation, pairing, thread resume, and rollout tailing.
+// Layer: CLI binary
+// Exports: none
+// Depends on: ../src
+
+const {
+  createPairing,
+  getDaemonStatus,
+  runDaemonProcess,
+  startBridge,
+  startDaemonCli,
+  stopDaemonCli,
+  resetBridgePairing,
+  openLastActiveThread,
+  watchThreadRollout,
+} = require("../src");
+const { printQR } = require("../src/qr");
+
+const command = process.argv[2] || "up";
+const CLI_NAME = "androdex";
+const CLI_PREFIX = `[${CLI_NAME}]`;
+
+void main().catch((error) => {
+  console.error(`${CLI_PREFIX} ${(error && error.message) || "Command failed."}`);
+  process.exit(1);
+});
+
+async function main() {
+  if (command === "__daemon-run") {
+    await runDaemonProcess();
+    return;
+  }
+
+  if (command === "up") {
+    const status = await startBridge();
+    console.log(`${CLI_PREFIX} Active workspace: ${status.currentCwd || process.cwd()}`);
+    console.log(`${CLI_PREFIX} Relay: ${status.relayStatus}`);
+    return;
+  }
+
+  if (command === "pair") {
+    const response = await createPairing();
+    printQR(response.pairingPayload);
+    return;
+  }
+
+  if (command === "daemon") {
+    await handleDaemonCommand(process.argv[3] || "status");
+    return;
+  }
+
+  if (command === "reset-pairing") {
+    await resetBridgePairing();
+    console.log(`${CLI_PREFIX} Cleared the saved pairing state. Run \`${CLI_NAME} pair\` to create a fresh pairing QR.`);
+    return;
+  }
+
+  if (command === "resume") {
+    const state = openLastActiveThread();
+    console.log(
+      `${CLI_PREFIX} Opened last active thread: ${state.threadId} (${state.source || "unknown"})`
+    );
+    return;
+  }
+
+  if (command === "watch") {
+    watchThreadRollout(process.argv[3] || "");
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  console.error("Usage: androdex up | androdex pair | androdex daemon [start|stop|status] | androdex reset-pairing | androdex resume | androdex watch [threadId]");
+  process.exit(1);
+}
+
+async function handleDaemonCommand(subcommand) {
+  if (subcommand === "start") {
+    const response = await startDaemonCli();
+    printDaemonStatus(response.status);
+    return;
+  }
+
+  if (subcommand === "stop") {
+    await stopDaemonCli();
+    console.log(`${CLI_PREFIX} Daemon stopped.`);
+    return;
+  }
+
+  if (subcommand === "status") {
+    const response = await getDaemonStatus();
+    printDaemonStatus(response.status);
+    return;
+  }
+
+  throw new Error(`Unknown daemon subcommand: ${subcommand}`);
+}
+
+function printDaemonStatus(status) {
+  console.log(`${CLI_PREFIX} Relay: ${status.relayStatus || "unknown"}`);
+  console.log(`${CLI_PREFIX} Host ID: ${status.hostId || "unavailable"}`);
+  console.log(`${CLI_PREFIX} Workspace: ${status.currentCwd || "none"}`);
+  console.log(`${CLI_PREFIX} Workspace active: ${status.workspaceActive ? "yes" : "no"}`);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "androdex",
+  "version": "1.1.3",
+  "description": "Local bridge between Codex and the Androdex mobile app. Run `androdex up` to start.",
+  "main": "src/index.js",
+  "bin": {
+    "androdex": "bin/androdex.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node ./bin/androdex.js up",
+    "test": "node --test ./test/*.test.js"
+  },
+  "keywords": [
+    "androdex",
+    "codex",
+    "bridge",
+    "cli",
+    "android"
+  ],
+  "author": "Robert Gordon",
+  "license": "ISC",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0",
+    "uuid": "^13.0.0",
+    "ws": "^8.19.0"
+  }
+}

package/src/bridge.js

@@ -0,0 +1,363 @@
+// FILE: bridge.js
+// Purpose: Runs Codex locally, bridges relay traffic, and coordinates desktop refreshes for Codex.app.
+// Layer: CLI service
+// Exports: startBridge
+// Depends on: ws, uuid, ./qr, ./codex-desktop-refresher, ./codex-transport
+
+const WebSocket = require("ws");
+const { v4: uuidv4 } = require("uuid");
+const {
+  CodexDesktopRefresher,
+  readBridgeConfig,
+} = require("./codex-desktop-refresher");
+const { createCodexTransport } = require("./codex-transport");
+const { printQR } = require("./qr");
+const { rememberActiveThread } = require("./session-state");
+const { handleGitRequest } = require("./git-handler");
+const { handleWorkspaceRequest } = require("./workspace-handler");
+const { loadOrCreateBridgeDeviceState } = require("./secure-device-state");
+const { createBridgeSecureTransport } = require("./secure-transport");
+
+function startBridge() {
+  const config = readBridgeConfig();
+  if (!config.relayUrl) {
+    throw new Error("Set ANDRODEX_RELAY to a reachable relay URL before pairing or starting the bridge.");
+  }
+  const sessionId = uuidv4();
+  const relayBaseUrl = config.relayUrl.replace(/\/+$/, "");
+  const relaySessionUrl = `${relayBaseUrl}/${sessionId}`;
+  const deviceState = loadOrCreateBridgeDeviceState();
+  const desktopRefresher = new CodexDesktopRefresher({
+    enabled: config.refreshEnabled,
+    debounceMs: config.refreshDebounceMs,
+    refreshCommand: config.refreshCommand,
+    bundleId: config.codexBundleId,
+    appPath: config.codexAppPath,
+  });
+
+  // Keep the local Codex runtime alive across transient relay disconnects.
+  let socket = null;
+  let isShuttingDown = false;
+  let reconnectAttempt = 0;
+  let reconnectTimer = null;
+  let lastConnectionStatus = null;
+  let codexHandshakeState = config.codexEndpoint ? "warm" : "cold";
+  const forwardedInitializeRequestIds = new Set();
+  const secureTransport = createBridgeSecureTransport({
+    sessionId,
+    relayUrl: relayBaseUrl,
+    deviceState,
+  });
+
+  const codex = createCodexTransport({
+    endpoint: config.codexEndpoint,
+    env: process.env,
+    logPrefix: "[androdex]",
+  });
+
+  codex.onError((error) => {
+    if (config.codexEndpoint) {
+      console.error(`[androdex] Failed to connect to Codex endpoint: ${config.codexEndpoint}`);
+    } else {
+      console.error("[androdex] Failed to start `codex app-server`.");
+      console.error(`[androdex] Launch command: ${codex.describe()}`);
+      console.error("[androdex] Make sure the Codex CLI is installed and that the launcher works on this OS.");
+    }
+    console.error(error.message);
+    process.exit(1);
+  });
+
+  function clearReconnectTimer() {
+    if (!reconnectTimer) {
+      return;
+    }
+
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+
+  // Keeps npm start output compact by emitting only high-signal connection states.
+  function logConnectionStatus(status) {
+    if (lastConnectionStatus === status) {
+      return;
+    }
+
+    lastConnectionStatus = status;
+    console.log(`[androdex] ${status}`);
+  }
+
+  // Retries the relay socket while preserving the active Codex process and session id.
+  function scheduleRelayReconnect(closeCode) {
+    if (isShuttingDown) {
+      return;
+    }
+
+    if (closeCode === 4000 || closeCode === 4001) {
+      logConnectionStatus("disconnected");
+      shutdown(codex, () => socket, () => {
+        isShuttingDown = true;
+        clearReconnectTimer();
+      });
+      return;
+    }
+
+    if (reconnectTimer) {
+      return;
+    }
+
+    reconnectAttempt += 1;
+    const delayMs = Math.min(1_000 * reconnectAttempt, 5_000);
+    logConnectionStatus("connecting");
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connectRelay();
+    }, delayMs);
+  }
+
+  function connectRelay() {
+    if (isShuttingDown) {
+      return;
+    }
+
+    logConnectionStatus("connecting");
+    const nextSocket = new WebSocket(relaySessionUrl, {
+      headers: { "x-role": "mac" },
+    });
+    socket = nextSocket;
+
+    nextSocket.on("open", () => {
+      clearReconnectTimer();
+      reconnectAttempt = 0;
+      logConnectionStatus("connected");
+      secureTransport.bindLiveSendWireMessage((wireMessage) => {
+        if (nextSocket.readyState === WebSocket.OPEN) {
+          nextSocket.send(wireMessage);
+        }
+      });
+    });
+
+    nextSocket.on("message", (data) => {
+      const message = typeof data === "string" ? data : data.toString("utf8");
+      if (secureTransport.handleIncomingWireMessage(message, {
+        sendControlMessage(controlMessage) {
+          if (nextSocket.readyState === WebSocket.OPEN) {
+            nextSocket.send(JSON.stringify(controlMessage));
+          }
+        },
+        onApplicationMessage(plaintextMessage) {
+          handleApplicationMessage(plaintextMessage);
+        },
+      })) {
+        return;
+      }
+    });
+
+    nextSocket.on("close", (code) => {
+      logConnectionStatus("disconnected");
+      if (socket === nextSocket) {
+        socket = null;
+      }
+      desktopRefresher.handleTransportReset();
+      scheduleRelayReconnect(code);
+    });
+
+    nextSocket.on("error", () => {
+      logConnectionStatus("disconnected");
+    });
+  }
+
+  printQR(secureTransport.createPairingPayload());
+  connectRelay();
+
+  codex.onMessage((message) => {
+    trackCodexHandshakeState(message);
+    desktopRefresher.handleOutbound(message);
+    rememberThreadFromMessage("codex", message);
+    secureTransport.queueOutboundApplicationMessage(message, (wireMessage) => {
+      if (socket?.readyState === WebSocket.OPEN) {
+        socket.send(wireMessage);
+      }
+    });
+  });
+
+  codex.onClose(() => {
+    logConnectionStatus("disconnected");
+    isShuttingDown = true;
+    clearReconnectTimer();
+    desktopRefresher.handleTransportReset();
+    if (socket?.readyState === WebSocket.OPEN || socket?.readyState === WebSocket.CONNECTING) {
+      socket.close();
+    }
+  });
+
+  process.on("SIGINT", () => shutdown(codex, () => socket, () => {
+    isShuttingDown = true;
+    clearReconnectTimer();
+  }));
+  process.on("SIGTERM", () => shutdown(codex, () => socket, () => {
+    isShuttingDown = true;
+    clearReconnectTimer();
+  }));
+
+  // Routes decrypted app payloads through the same bridge handlers as before.
+  function handleApplicationMessage(rawMessage) {
+    if (handleBridgeManagedHandshakeMessage(rawMessage)) {
+      return;
+    }
+    if (handleWorkspaceRequest(rawMessage, sendApplicationResponse)) {
+      return;
+    }
+    if (handleGitRequest(rawMessage, sendApplicationResponse)) {
+      return;
+    }
+    desktopRefresher.handleInbound(rawMessage);
+    rememberThreadFromMessage("phone", rawMessage);
+    codex.send(rawMessage);
+  }
+
+  // Encrypts bridge-generated responses instead of letting the relay see plaintext.
+  function sendApplicationResponse(rawMessage) {
+    secureTransport.queueOutboundApplicationMessage(rawMessage, (wireMessage) => {
+      if (socket?.readyState === WebSocket.OPEN) {
+        socket.send(wireMessage);
+      }
+    });
+  }
+
+  function rememberThreadFromMessage(source, rawMessage) {
+    const threadId = extractThreadId(rawMessage);
+    if (!threadId) {
+      return;
+    }
+
+    rememberActiveThread(threadId, source);
+  }
+
+  // The spawned/shared Codex app-server stays warm across phone reconnects.
+  // When iPhone reconnects it sends initialize again, but forwarding that to the
+  // already-initialized Codex transport only produces "Already initialized".
+  function handleBridgeManagedHandshakeMessage(rawMessage) {
+    let parsed = null;
+    try {
+      parsed = JSON.parse(rawMessage);
+    } catch {
+      return false;
+    }
+
+    const method = typeof parsed?.method === "string" ? parsed.method.trim() : "";
+    if (!method) {
+      return false;
+    }
+
+    if (method === "initialize" && parsed.id != null) {
+      if (codexHandshakeState !== "warm") {
+        forwardedInitializeRequestIds.add(String(parsed.id));
+        return false;
+      }
+
+      sendApplicationResponse(JSON.stringify({
+        id: parsed.id,
+        result: {
+          bridgeManaged: true,
+        },
+      }));
+      return true;
+    }
+
+    if (method === "initialized") {
+      return codexHandshakeState === "warm";
+    }
+
+    return false;
+  }
+
+  // Learns whether the underlying Codex transport has already completed its own MCP handshake.
+  function trackCodexHandshakeState(rawMessage) {
+    let parsed = null;
+    try {
+      parsed = JSON.parse(rawMessage);
+    } catch {
+      return;
+    }
+
+    const responseId = parsed?.id;
+    if (responseId == null) {
+      return;
+    }
+
+    const responseKey = String(responseId);
+    if (!forwardedInitializeRequestIds.has(responseKey)) {
+      return;
+    }
+
+    forwardedInitializeRequestIds.delete(responseKey);
+
+    if (parsed?.result != null) {
+      codexHandshakeState = "warm";
+      return;
+    }
+
+    const errorMessage = typeof parsed?.error?.message === "string"
+      ? parsed.error.message.toLowerCase()
+      : "";
+    if (errorMessage.includes("already initialized")) {
+      codexHandshakeState = "warm";
+    }
+  }
+}
+
+function shutdown(codex, getSocket, beforeExit = () => {}) {
+  beforeExit();
+
+  const socket = getSocket();
+  if (socket?.readyState === WebSocket.OPEN || socket?.readyState === WebSocket.CONNECTING) {
+    socket.close();
+  }
+
+  codex.shutdown();
+
+  setTimeout(() => process.exit(0), 100);
+}
+
+function extractThreadId(rawMessage) {
+  let parsed = null;
+  try {
+    parsed = JSON.parse(rawMessage);
+  } catch {
+    return null;
+  }
+
+  const method = parsed?.method;
+  const params = parsed?.params;
+
+  if (method === "turn/start") {
+    return readString(params?.threadId) || readString(params?.thread_id);
+  }
+
+  if (method === "thread/start" || method === "thread/started") {
+    return (
+      readString(params?.threadId)
+      || readString(params?.thread_id)
+      || readString(params?.thread?.id)
+      || readString(params?.thread?.threadId)
+      || readString(params?.thread?.thread_id)
+    );
+  }
+
+  if (method === "turn/completed") {
+    return (
+      readString(params?.threadId)
+      || readString(params?.thread_id)
+      || readString(params?.turn?.threadId)
+      || readString(params?.turn?.thread_id)
+    );
+  }
+
+  return null;
+}
+
+function readString(value) {
+  return typeof value === "string" && value ? value : null;
+}
+
+module.exports = { startBridge };

package/src/codex-desktop-launcher.js

@@ -0,0 +1,93 @@
+// FILE: codex-desktop-launcher.js
+// Purpose: Opens Codex desktop deep links across supported host platforms.
+// Layer: CLI helper
+// Exports: openCodexDesktopTarget, openCodexDesktopTargetSync
+// Depends on: child_process
+
+const { execFile, execFileSync } = require("child_process");
+
+function openCodexDesktopTarget({
+  targetUrl = "",
+  bundleId = "com.openai.codex",
+  appPath = "/Applications/Codex.app",
+  platform = process.platform,
+} = {}) {
+  const plan = createDesktopLaunchPlan({ targetUrl, bundleId, appPath, platform });
+  return execFilePromise(plan.command, plan.args, plan.options);
+}
+
+function openCodexDesktopTargetSync({
+  targetUrl = "",
+  bundleId = "com.openai.codex",
+  appPath = "/Applications/Codex.app",
+  platform = process.platform,
+} = {}) {
+  const plan = createDesktopLaunchPlan({ targetUrl, bundleId, appPath, platform });
+  execFileSync(plan.command, plan.args, plan.options);
+}
+
+function createDesktopLaunchPlan({
+  targetUrl = "",
+  bundleId = "com.openai.codex",
+  appPath = "/Applications/Codex.app",
+  platform = process.platform,
+} = {}) {
+  const safeTargetUrl = typeof targetUrl === "string" ? targetUrl.trim() : "";
+
+  if (platform === "darwin") {
+    if (safeTargetUrl) {
+      return {
+        command: "open",
+        args: ["-b", bundleId, safeTargetUrl],
+        options: { stdio: "ignore" },
+      };
+    }
+
+    return {
+      command: "open",
+      args: ["-a", appPath],
+      options: { stdio: "ignore" },
+    };
+  }
+
+  if (!safeTargetUrl) {
+    throw new Error("Codex desktop target URL is required on this platform.");
+  }
+
+  if (platform === "win32") {
+    return {
+      command: "cmd.exe",
+      args: ["/d", "/c", "start", "\"\"", safeTargetUrl],
+      options: {
+        stdio: "ignore",
+        windowsHide: true,
+      },
+    };
+  }
+
+  return {
+    command: "xdg-open",
+    args: [safeTargetUrl],
+    options: { stdio: "ignore" },
+  };
+}
+
+function execFilePromise(command, args, options) {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, options, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+module.exports = {
+  createDesktopLaunchPlan,
+  openCodexDesktopTarget,
+  openCodexDesktopTargetSync,
+};