codex-relay 1.0.0

package/README.md

@@ -0,0 +1,139 @@
+# Codex Relay CLI
+
+Codex Relay runs a local bridge server for the Codex Relay mobile app. Keep Codex on your computer, then use your phone to pair with that local session, send prompts, watch streamed output, and respond to approval requests.
+
+## Requirements
+
+- Node.js 22.14 or newer
+- Codex CLI installed and signed in on the computer running the relay
+- The Codex Relay mobile app on the same network, Tailscale network, or another route that can reach your computer
+
+## Start the Relay
+
+Run the server from the workspace you want Codex to use:
+
+```sh
+npx codex-relay
+```
+
+The CLI prints a QR code, a mobile URL, and a `codex-relay://pair...` pairing payload. Scan the QR code from the mobile app. If scanning is not available, paste the full pairing payload into the app.
+
+When the app shows an approval code, approve it on the computer:
+
+```sh
+npx codex-relay approve XXXX-XXXX
+```
+
+After approval, the phone can list Codex threads, start new work, stream messages, and handle approval prompts from the local Codex runtime.
+
+## Background Mode
+
+To keep the relay running after the command returns:
+
+```sh
+npx codex-relay --bg
+```
+
+Background mode writes runtime files under `.codex-relay/` in the current directory:
+
+- `.codex-relay/server.log`
+- `.codex-relay/server.pid`
+- `.codex-relay/server-state.json`
+- `.codex-relay/auth.db`
+
+Print the current pairing QR again:
+
+```sh
+npx codex-relay qr
+```
+
+Stop a background server with the printed process id:
+
+```sh
+kill -TERM <pid>
+```
+
+## Commands
+
+```sh
+npx codex-relay
+```
+
+Start the relay in the foreground.
+
+```sh
+npx codex-relay --bg
+```
+
+Start the relay in the background.
+
+```sh
+npx codex-relay qr
+```
+
+Print the latest pairing QR for an already running relay.
+
+```sh
+npx codex-relay approve XXXX-XXXX
+```
+
+Approve a pending mobile pairing request.
+
+## Configuration
+
+The relay listens on `0.0.0.0:8787` by default. Configure it with environment variables:
+
+| Variable                      | Purpose                                                                                     |
+| ----------------------------- | ------------------------------------------------------------------------------------------- |
+| `PORT`                        | Server port. Defaults to `8787`.                                                            |
+| `HOST`                        | Listen host. Defaults to `0.0.0.0`.                                                         |
+| `CODEX_RELAY_PUBLIC_URL`      | URL printed into the pairing QR, for example a Tailscale or tunnel URL.                     |
+| `CODEX_RELAY_WORKSPACE_PATH`  | Workspace path Codex should use. Defaults to the directory where you run `npx codex-relay`. |
+| `CODEX_RELAY_AUTH_DB_PATH`    | Pairing and session database path. Defaults to `.codex-relay/auth.db`.                      |
+| `CODEX_RELAY_APPROVAL_SECRET` | Secret used by the local approve command. Usually generated automatically.                  |
+| `CODEX_HOME`                  | Codex home directory, used when reading Codex session metadata.                             |
+| `CODEX_BIN`                   | Codex CLI executable path.                                                                  |
+
+Examples:
+
+```sh
+PORT=8788 npx codex-relay
+```
+
+```sh
+CODEX_RELAY_PUBLIC_URL=http://100.64.0.10:8787 npx codex-relay
+```
+
+```sh
+CODEX_RELAY_WORKSPACE_PATH=/path/to/project npx codex-relay
+```
+
+## Network Notes
+
+The phone must be able to reach the URL printed as `Mobile:` by the relay.
+
+- On the same Wi-Fi network, the relay usually prints a local network address.
+- On Tailscale, the relay prefers your Tailscale address when it can detect one.
+- If the printed URL is not reachable from the phone, set `CODEX_RELAY_PUBLIC_URL` to a reachable HTTP URL.
+
+## Troubleshooting
+
+If `npx codex-relay qr` cannot find a server, start one first:
+
+```sh
+npx codex-relay
+```
+
+If the relay says another process is using the local pairing database, use the existing server:
+
+```sh
+npx codex-relay qr
+```
+
+Or stop the background process shown by the CLI:
+
+```sh
+kill -TERM <pid>
+```
+
+If the mobile app cannot connect, confirm that the phone can reach the printed `Mobile:` URL and that the chosen port is not blocked by a firewall.

package/dist/cli.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import { w as apiPaths } from "./src.js";
+import { Command } from "@commander-js/extra-typings";
+import qrcode from "qrcode-terminal";
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { mkdir, readFile, unlink } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { setTimeout } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+//#region src/cli.ts
+const program = new Command().name("codex-relay").description("Run and approve the codex-relay local CLI bridge.").option("--bg", "run the Codex Relay server in the background").action(async (options) => {
+	if (options.bg) {
+		await startBackgroundServer();
+		return;
+	}
+	await import("./src2.js").catch(handleServerStartError);
+});
+program.command("qr").description("Print the current pairing QR for an already running server.").action(async () => {
+	await printPairingQr();
+});
+program.command("approve").description("Approve a pending mobile pairing request.").argument("<approval-code>", "approval code shown in the mobile app").action(async (approvalCode) => {
+	await approvePairing(approvalCode);
+});
+await program.parseAsync();
+async function startBackgroundServer() {
+	const logPath = resolve(process.cwd(), ".codex-relay/server.log");
+	const pidPath = resolve(process.cwd(), ".codex-relay/server.pid");
+	await mkdir(dirname(logPath), { recursive: true });
+	const existingPid = await readRunningPid(pidPath);
+	if (existingPid) {
+		console.log(`codex-relay is already running in the background (pid ${existingPid}).`);
+		console.log(`Logs: ${logPath}`);
+		console.log("Print the current pairing QR with: npx codex-relay qr");
+		return;
+	}
+	await unlink(pidPath).catch(() => void 0);
+	const output = openSync(logPath, "a", 384);
+	const cliPath = fileURLToPath(import.meta.url);
+	const child = spawn(process.execPath, [
+		...process.execArgv,
+		cliPath,
+		...backgroundArgs()
+	], {
+		cwd: process.cwd(),
+		detached: true,
+		env: {
+			...process.env,
+			CODEX_RELAY_BACKGROUND: "1",
+			CODEX_RELAY_PID_PATH: pidPath
+		},
+		stdio: [
+			"ignore",
+			output,
+			output
+		]
+	});
+	child.unref();
+	closeSync(output);
+	const startedPid = await waitForBackgroundPid(child, pidPath);
+	if (!startedPid) {
+		console.error("codex-relay failed to start in the background.");
+		console.error(`Logs: ${logPath}`);
+		process.exitCode = 1;
+		return;
+	}
+	console.log(`Started codex-relay in the background (pid ${startedPid}).`);
+	console.log(`Logs: ${logPath}`);
+	console.log("Print the pairing QR later with: npx codex-relay qr");
+}
+async function readRunningPid(pidPath) {
+	const value = await readFile(pidPath, "utf8").catch(() => void 0);
+	const pid = value ? Number(value.trim()) : NaN;
+	if (!Number.isInteger(pid) || pid <= 0) return;
+	try {
+		process.kill(pid, 0);
+		return pid;
+	} catch {
+		return;
+	}
+}
+function backgroundArgs() {
+	return process.argv.slice(2).filter((arg) => arg !== "--bg");
+}
+async function waitForBackgroundPid(child, pidPath) {
+	let childExited = false;
+	child.once("exit", () => {
+		childExited = true;
+	});
+	for (let attempt = 0; attempt < 50; attempt += 1) {
+		const pid = await readRunningPid(pidPath);
+		if (pid) return pid;
+		if (childExited) return;
+		await setTimeout(100);
+	}
+}
+async function approvePairing(rawCode) {
+	const approvalCode = normalizeApprovalCode(rawCode ?? "");
+	if (!approvalCode) {
+		console.error("Usage: codex-relay approve XXXX-XXXX");
+		process.exitCode = 1;
+		return;
+	}
+	const endpoint = await getApprovalEndpoint();
+	const secret = await readApprovalSecret();
+	const response = await fetch(`${endpoint}${apiPaths.pairApprove}`, {
+		method: "POST",
+		headers: {
+			accept: "application/json",
+			"content-type": "application/json",
+			"x-codex-relay-approve-secret": secret
+		},
+		body: JSON.stringify({ approvalCode })
+	});
+	const payload = await response.json().catch(() => void 0);
+	if (!response.ok) {
+		const message = payload && typeof payload === "object" && "error" in payload && payload.error && typeof payload.error === "object" && "message" in payload.error ? String(payload.error.message) : `Codex Relay server returned ${response.status}`;
+		console.error(message);
+		process.exitCode = 1;
+		return;
+	}
+	console.log("Approved Codex Relay pairing request.");
+}
+async function printPairingQr() {
+	const storedState = await readServerState();
+	const state = storedState?.pairingPayload ? storedState : await readServerLogState();
+	if (!state?.pairingPayload) {
+		console.error("No running Codex Relay server state was found.");
+		console.error("Start the server first with: npx codex-relay");
+		console.error("Or run it in the background with: npx codex-relay --bg");
+		process.exitCode = 1;
+		return;
+	}
+	console.log("");
+	qrcode.generate(state.pairingPayload, { small: true });
+	console.log("");
+	if (state.connectUrl) console.log(`Mobile: ${state.connectUrl}`);
+	if (state.listenUrl) console.log(`Server: ${state.listenUrl}`);
+	console.log("");
+	console.log(`Pairing: ${state.pairingPayload}`);
+	console.log("");
+}
+async function handleServerStartError(error) {
+	if (!isDatabaseLockError(error)) throw error;
+	const pidPath = resolve(process.cwd(), ".codex-relay/server.pid");
+	const logPath = resolve(process.cwd(), ".codex-relay/server.log");
+	const existingPid = await readRunningPid(pidPath);
+	const storedState = await readServerState();
+	const state = storedState?.pairingPayload ? storedState : await readServerLogState();
+	console.error("Codex Relay is already using its local pairing database.");
+	console.error("");
+	if (existingPid) {
+		console.error(`A background server appears to be running (pid ${existingPid}).`);
+		console.error("Use the existing server instead of starting a second one:");
+		console.error("  npx codex-relay qr");
+		console.error("");
+		console.error("To stop the background server:");
+		console.error(`  kill -TERM ${existingPid}`);
+		console.error("");
+		console.error(`Logs: ${logPath}`);
+	} else {
+		console.error("Another Codex Relay process is already running or exited without cleanup.");
+		if (state?.pairingPayload) {
+			console.error("Use the existing server instead of starting a second one:");
+			console.error("  npx codex-relay qr");
+			console.error("");
+		}
+		console.error("Find it with:");
+		console.error("  lsof -nP apps/server/.codex-relay/auth.db apps/server/.codex-relay/auth.db-wal");
+		console.error("  lsof -nP -iTCP:8787 -sTCP:LISTEN");
+		console.error("");
+		console.error("Then stop that process with:");
+		console.error("  kill -TERM <pid>");
+	}
+	console.error("");
+	console.error("If you wanted a persistent server, start it once with:");
+	console.error("  npx codex-relay --bg");
+	process.exitCode = 1;
+}
+async function readApprovalSecret() {
+	if (process.env.CODEX_RELAY_APPROVAL_SECRET) return process.env.CODEX_RELAY_APPROVAL_SECRET;
+	return (await readFile(resolve(process.cwd(), ".codex-relay/approval-secret"), "utf8")).trim();
+}
+async function getApprovalEndpoint() {
+	const state = await readServerState();
+	const port = process.env.PORT ? Number(process.env.PORT) : state?.port ?? 8787;
+	const host = process.env.HOST ?? state?.host ?? "127.0.0.1";
+	return `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${port}`;
+}
+async function readServerState() {
+	const state = await readFile(resolve(process.cwd(), ".codex-relay/server-state.json"), "utf8").then((value) => JSON.parse(value)).catch(() => void 0);
+	if (!state) return;
+	return {
+		connectUrl: typeof state.connectUrl === "string" ? state.connectUrl : void 0,
+		host: typeof state.host === "string" ? state.host : void 0,
+		listenUrl: typeof state.listenUrl === "string" ? state.listenUrl : void 0,
+		pairingPayload: typeof state.pairingPayload === "string" ? state.pairingPayload : void 0,
+		port: typeof state.port === "number" ? state.port : void 0
+	};
+}
+async function readServerLogState() {
+	const log = await readFile(resolve(process.cwd(), ".codex-relay/server.log"), "utf8").catch(() => void 0);
+	if (!log) return;
+	const connectUrl = lastLogValue(log, "Mobile");
+	const listenUrl = lastLogValue(log, "Server");
+	const pairingPayload = lastLogValue(log, "Pairing");
+	return pairingPayload ? {
+		connectUrl,
+		listenUrl,
+		pairingPayload
+	} : void 0;
+}
+function lastLogValue(log, label) {
+	const pattern = new RegExp(`${label}:\\s*(\\S+)`, "g");
+	let value;
+	for (const match of log.matchAll(pattern)) value = match[1];
+	return value;
+}
+function isDatabaseLockError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	return message.includes("failed to open database") && message.includes("Locking error");
+}
+function normalizeApprovalCode(value) {
+	const normalized = value.toUpperCase().replace(/[^A-Z0-9]/g, "").replaceAll("O", "0").replaceAll("I", "1");
+	return normalized.length === 8 ? `${normalized.slice(0, 4)}-${normalized.slice(4)}` : normalized;
+}
+//#endregion
+export {};