clawdex-mobile 5.1.2 → 5.1.3-internal.1

package/README.md

@@ -4,9 +4,9 @@
   <img src="https://raw.githubusercontent.com/Mohit-Patil/clawdex-mobile/main/screenshots/social/clawdex-social-poster-1200x675.png" alt="Clawdex social banner" width="100%" />
 </p>
 
-Run Codex or OpenCode from your phone. `clawdex-mobile` ships the bridge CLI plus bundled Rust bridge binaries for supported hosts, and the mobile app pairs to that bridge over Tailscale or local LAN.
+Run Codex or OpenCode from your phone. `clawdex-mobile` ships the bridge CLI plus bundled Rust bridge binaries for supported hosts, and the mobile app pairs to that bridge over Tailscale, local LAN, or GitHub Codespaces forwarded HTTPS URLs.
 
-This project is for trusted/private networking only. Do not expose the bridge publicly.
+This project is for trusted/private networking by default. GitHub Codespaces is supported as an internet-reachable exception: keep bridge auth enabled, use only repos you trust, and remember forwarded public ports reset to private when a codespace restarts.
 
 ## What You Get
 
@@ -52,6 +52,45 @@ clawdex init
 clawdex stop
 ```
 
+## GitHub Codespaces
+
+You can run the bridge inside a GitHub Codespace instead of keeping a laptop or server online.
+
+From a repo checkout inside Codespaces:
+
+```bash
+npm run setup:wizard
+```
+
+Pick `GitHub Codespaces` as the network mode. The setup flow writes forwarded HTTPS bridge URLs into `.env.secure`, and bridge startup will try to mark both bridge ports public automatically.
+
+Notes:
+
+- The mobile app should pair to the printed `https://<codespace>-8787.app.github.dev` URL, not `127.0.0.1`.
+- Browser preview uses a second forwarded port (`8788` by default), so both ports need public visibility.
+- GitHub resets public forwarded ports back to private when a codespace restarts. Restarting the bridge reruns the visibility step.
+- If automatic visibility setup fails, run `gh codespace ports visibility 8787:public 8788:public`.
+- If the mobile app is built with `EXPO_PUBLIC_GITHUB_CLIENT_ID`, users can now tap `Use GitHub Codespaces` in onboarding/settings, sign in with GitHub, pick a Codespace, and connect without manually copying the bridge token.
+- The app can also create a new repo-backed Codespace directly. It prefers `<signed-in-user>/<EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME>` first. If that repo does not exist, it automatically forks `EXPO_PUBLIC_GITHUB_CODESPACES_SOURCE_OWNER/<EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME>` into the signed-in user account, then creates the Codespace there.
+
+This repo now also includes a Codespaces bootstrap flow. On Codespace start/resume, `.devcontainer/devcontainer.json` runs:
+
+```bash
+npm run codespaces:bootstrap
+```
+
+During initial Codespace creation, the devcontainer also runs:
+
+```bash
+npm run codespaces:bootstrap -- --prepare-only
+```
+
+That pre-installs Codex and prebuilds the Rust bridge binary so the later startup path is faster. The normal bootstrap command rewrites `.env.secure` for Codespaces with `codex` as the only enabled engine and starts the bridge in the background. You can rerun either command manually any time.
+
+The published npm package now includes that bootstrap script too, so a minimal Codespaces template repo can install `clawdex-mobile@latest` in `postCreateCommand` and call the packaged bootstrap without vendoring bridge source into the template itself.
+
+In Codespaces mode, the bootstrap also enables bridge-side GitHub bearer auth for the current `CODESPACE_NAME`, so the mobile app can authenticate with the same GitHub OAuth token it used to discover and start the Codespace.
+
 ## OpenCode Setup
 
 OpenCode is supported directly from the CLI now.

package/bin/clawdex.js

@@ -34,9 +34,14 @@ Commands:
 }
 
 function runCommand(command, args = [], options = {}) {
+  const workspaceRoot = process.env.CLAWDEX_WORKSPACE_ROOT || process.cwd();
   const child = spawnSync(command, args, {
     stdio: "inherit",
-    env: process.env,
+    env: {
+      ...process.env,
+      CLAWDEX_WORKSPACE_ROOT: workspaceRoot,
+      INIT_CWD: process.env.INIT_CWD || workspaceRoot,
+    },
     cwd: process.cwd(),
     ...options,
   });

package/docs/setup-and-operations.md

@@ -37,6 +37,77 @@ Published npm releases bundle prebuilt bridge binaries for `darwin-arm64`, `darw
 
 Published CLI installs are bridge-only. They do not include the Expo workspace or mobile app source files.
 
+## GitHub Codespaces Setup
+
+Codespaces can replace a user-managed always-on machine for development and lightweight remote use.
+
+From a repo checkout inside an active codespace:
+
+```bash
+npm run setup:wizard
+```
+
+Choose `GitHub Codespaces` for the bridge network mode.
+
+What that does:
+
+- binds the bridge locally inside the codespace
+- writes `BRIDGE_CONNECT_URL` and `BRIDGE_PREVIEW_CONNECT_URL` using the codespace forwarded HTTPS domain
+- enables bridge-side GitHub bearer auth for the current codespace
+- starts the bridge normally
+- attempts to mark the bridge port and browser-preview port public on each startup
+
+Important constraints:
+
+- Pair the mobile app to the printed `https://<codespace>-8787.app.github.dev` URL, not `127.0.0.1`
+- Browser preview uses the preview port (`8788` by default), so that forwarded port must also be public
+- GitHub resets public forwarded ports back to private whenever the codespace restarts
+- Keep bridge auth enabled and use Codespaces only for repos you trust, because public forwarded ports are internet-reachable
+- If the mobile app build sets `EXPO_PUBLIC_GITHUB_CLIENT_ID`, onboarding/settings can now sign in with GitHub, start the Codespace, and connect directly with the same OAuth token instead of copying `BRIDGE_AUTH_TOKEN`
+- That same in-app GitHub sign-in now also bootstraps GitHub git auth inside the Codespace so `git clone`, `git push`, GitHub HTTPS remotes, and common `git@github.com:...` SSH-style remotes can reuse the app login without extra account setup
+- The same in-app GitHub flow can create a new Codespace. It prefers `<signed-in-user>/<EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME>`. If that repo does not exist yet, Clawdex automatically forks `EXPO_PUBLIC_GITHUB_CODESPACES_SOURCE_OWNER/<EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME>` into the signed-in user account and creates the Codespace from that fork
+- Older saved GitHub Codespaces sessions may need one fresh sign-in from the app so the stored GitHub token includes repository access
+
+Manual recovery if port visibility does not update automatically:
+
+```bash
+gh codespace ports visibility 8787:public 8788:public
+```
+
+### Codespaces Bootstrap
+
+The repo devcontainer now includes:
+
+- `postCreateCommand`: `npm install --include=dev && npm run codespaces:bootstrap -- --prepare-only`
+- `postStartCommand`: `npm run codespaces:bootstrap`
+
+`npm run codespaces:bootstrap` does the following:
+
+- installs the Codex CLI via `npm install -g @openai/codex` if it is missing
+- in `--prepare-only` mode, prebuilds the Rust bridge binary without starting it
+- rewrites `.env.secure` for `BRIDGE_NETWORK_MODE=codespaces` with `BRIDGE_ACTIVE_ENGINE=codex`, `BRIDGE_ENABLED_ENGINES=codex`, and `BRIDGE_GITHUB_CODESPACES_AUTH=true`
+- starts the bridge in the background unless you set `CLAWDEX_CODESPACES_SKIP_START=true` or pass `--no-start`
+
+That means the first Codespace create now front-loads the expensive bridge compile during `postCreateCommand`, so the later `postStartCommand` can usually start the bridge much faster.
+
+The same bootstrap script is included in the published `clawdex-mobile` npm package. That lets the `clawdex-codespace` template stay minimal: it can install `clawdex-mobile@latest` globally in the devcontainer and invoke the packaged bootstrap against the current workspace instead of copying `scripts/*` and `services/rust-bridge/*` into the template repo.
+
+Manual examples:
+
+```bash
+npm run codespaces:bootstrap -- --prepare-only
+npm run codespaces:bootstrap
+npm run codespaces:bootstrap -- --no-start
+```
+
+Minimal template equivalent:
+
+```bash
+npm install -g clawdex-mobile@latest @openai/codex
+CLAWDEX_WORKSPACE_ROOT="$PWD" node "$(npm root -g)/clawdex-mobile/scripts/codespaces-bootstrap.js" --prepare-only
+CLAWDEX_WORKSPACE_ROOT="$PWD" node "$(npm root -g)/clawdex-mobile/scripts/codespaces-bootstrap.js"
+```
+
 ## Manual Secure Setup (No Wizard)
 
 ### 1) Install dependencies
@@ -78,7 +149,7 @@ When both CLIs are selected, the bridge starts both backends and merges chat lis
 
 ### 4) Pair from the mobile app
 
-Open the installed mobile app on your phone, then scan the bridge QR. If needed, enter the bridge URL manually (for example `http://100.x.y.z:8787` or `http://192.168.x.y:8787`). The chosen bridge URL is stored on-device and can be changed later in Settings.
+Open the installed mobile app on your phone, then scan the bridge QR. If needed, enter the bridge URL manually (for example `http://100.x.y.z:8787`, `http://192.168.x.y:8787`, or `https://<codespace>-8787.app.github.dev`). The chosen bridge URL is stored on-device and can be changed later in Settings.
 
 ### In-app Bridge Maintenance
 
@@ -173,11 +244,17 @@ npm run teardown -- --yes
 
 | Variable | Purpose |
 |---|---|
+| `BRIDGE_NETWORK_MODE` | bridge connectivity mode (`tailscale`, `local`, or `codespaces`) |
 | `BRIDGE_HOST` | bind host for rust bridge |
 | `BRIDGE_PORT` | bridge port (default `8787`) |
 | `BRIDGE_PREVIEW_PORT` | browser preview port for proxied localhost web apps (default `BRIDGE_PORT + 1`) |
+| `BRIDGE_CONNECT_URL` | externally reachable bridge base URL used for pairing/QR output |
+| `BRIDGE_PREVIEW_CONNECT_URL` | externally reachable browser preview base URL |
 | `BRIDGE_AUTH_TOKEN` | required auth token |
 | `BRIDGE_ALLOW_QUERY_TOKEN_AUTH` | query-token auth fallback |
+| `BRIDGE_GITHUB_CODESPACES_AUTH` | accept GitHub bearer tokens for the current codespace |
+| `BRIDGE_GITHUB_CODESPACE_NAME` | codespace name used when validating GitHub bearer tokens |
+| `BRIDGE_GITHUB_API_URL` | GitHub REST API base URL for Codespaces auth checks |
 | `CODEX_CLI_BIN` | codex executable |
 | `BRIDGE_ACTIVE_ENGINE` | internal preferred routing backend used when multiple harnesses are enabled |
 | `BRIDGE_ENABLED_ENGINES` | selected harnesses to expose (`codex`, `opencode`, or both) |
@@ -194,6 +271,11 @@ npm run teardown -- --yes
 | Variable | Purpose |
 |---|---|
 | `EXPO_PUBLIC_HOST_BRIDGE_TOKEN` | token used by local mobile dev builds |
+| `EXPO_PUBLIC_GITHUB_CLIENT_ID` | GitHub OAuth app client ID for in-app Codespaces sign-in |
+| `EXPO_PUBLIC_GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN` | forwarded port domain used to derive Codespaces bridge URLs (`app.github.dev` by default) |
+| `EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME` | repository name to sort matching Codespaces first in the in-app picker |
+| `EXPO_PUBLIC_GITHUB_CODESPACES_SOURCE_OWNER` | template/source repository owner used for automatic forking when the signed-in user does not have a same-name repo |
+| `EXPO_PUBLIC_GITHUB_CODESPACES_REPO_REF` | optional git ref/branch used when creating a new Codespace |
 | `EXPO_PUBLIC_ALLOW_QUERY_TOKEN_AUTH` | query-token behavior for WebSocket auth fallback |
 | `EXPO_PUBLIC_ALLOW_INSECURE_REMOTE_BRIDGE` | suppress insecure-HTTP warning |
 | `EXPO_PUBLIC_PRIVACY_POLICY_URL` | in-app Privacy link |
@@ -213,8 +295,9 @@ If you enable the optional tip jar:
 
 ## Production Readiness Checklist
 
-- Keep bridge network-private only (Tailscale/private LAN/VPN + host firewall)
-- Require `BRIDGE_AUTH_TOKEN`
+- Keep bridge network-private only by default (Tailscale/private LAN/VPN + host firewall)
+- If using GitHub Codespaces, remember the bridge is internet-reachable whenever its forwarded ports are public
+- Require bridge auth of some kind (`BRIDGE_AUTH_TOKEN` or GitHub Codespaces auth)
 - Keep `BRIDGE_ALLOW_QUERY_TOKEN_AUTH=true` only on private networks (required for Android WS auth fallback)
 - Do not set `BRIDGE_ALLOW_INSECURE_NO_AUTH=true` outside local debugging
 - Scope `BRIDGE_WORKDIR` to minimal required root

package/docs/troubleshooting.md

@@ -34,11 +34,84 @@ npm run stop:services
 ## Bridge auth errors (`401`, invalid token)
 
 - For the shipped mobile app, rescan the bridge QR or update the stored token in Settings.
+- For GitHub-auth Codespaces profiles, reopen `GitHub Codespaces` in the app and sign in with GitHub again if the OAuth token was revoked or expired.
 - For a local dev build, also ensure `BRIDGE_AUTH_TOKEN` in `.env.secure` matches `EXPO_PUBLIC_HOST_BRIDGE_TOKEN` in `apps/mobile/.env`.
 - Restart the bridge after token changes.
 - On secure-launcher installs, `Settings > Bridge Maintenance > Restart bridge safely` can do that from the phone.
 - If an in-app bridge update fails, inspect `.bridge-updater.log` and `.bridge-update-status.json` in the bridge install root.
 
+## GitHub Codespaces bridge URL does not connect
+
+- Pair to the printed forwarded HTTPS URL such as `https://<codespace>-8787.app.github.dev`, not `127.0.0.1`.
+- Public forwarded ports reset back to private when the codespace restarts.
+- Restart the bridge or rerun `npm run codespaces:bootstrap` to rerun the automatic visibility step.
+- If needed, set both ports public manually:
+
+```bash
+gh codespace ports visibility 8787:public 8788:public
+```
+
+- If `gh` is unavailable in the codespace, use the Codespaces `Ports` panel and change both forwarded ports to `Public`.
+- Keep bridge auth enabled. Public forwarded ports without bridge auth are not a safe setup.
+- If GitHub direct sign-in is not showing in the app, confirm the build includes `EXPO_PUBLIC_GITHUB_CLIENT_ID`.
+- If in-app Codespace creation forks or targets the wrong repo, check `EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME`, `EXPO_PUBLIC_GITHUB_CODESPACES_SOURCE_OWNER`, and `EXPO_PUBLIC_GITHUB_CODESPACES_REPO_REF` in the mobile build env.
+
+## GitHub Codespaces bootstrap did not start the bridge
+
+- Check the post-start command output in the Codespace terminal or rerun it manually:
+
+```bash
+npm run codespaces:bootstrap -- --prepare-only
+npm run codespaces:bootstrap
+```
+
+- On the minimal `clawdex-codespace` template, rerun the packaged bootstrap instead:
+
+```bash
+CLAWDEX_WORKSPACE_ROOT="$PWD" node "$(npm root -g)/clawdex-mobile/scripts/codespaces-bootstrap.js" --prepare-only
+CLAWDEX_WORKSPACE_ROOT="$PWD" node "$(npm root -g)/clawdex-mobile/scripts/codespaces-bootstrap.js"
+```
+
+- The Codespaces bootstrap only prepares the `codex` engine. It will try to install Codex automatically with `npm install -g @openai/codex`.
+- `--prepare-only` installs Codex if needed and prebuilds the Rust bridge binary without starting the bridge.
+- The bootstrap also enables `BRIDGE_GITHUB_CODESPACES_AUTH=true` so GitHub bearer tokens can connect directly to the bridge.
+- If that install fails, fix npm/global package permissions in the codespace and rerun the bootstrap.
+- Bridge startup logs and runtime state live in the Codespace repo root:
+
+```bash
+tail -n 200 .bridge.log
+ls -la .bridge.pid .bridge.log .env.secure
+```
+
+- To only rewrite `.env.secure` without starting the bridge:
+
+```bash
+npm run codespaces:bootstrap -- --no-start
+```
+
+## Git push in a Codespace fails with `403` or permission denied
+
+- The app now bootstraps GitHub HTTPS git credentials inside the Codespace after GitHub sign-in.
+- If you signed in before this behavior shipped, reopen `GitHub Codespaces` in the app and sign in with GitHub once more so the saved token includes repository access.
+- The bootstrap also rewrites common `git@github.com:...` and `ssh://git@github.com/...` remotes to HTTPS so they can use the same credential.
+- After reconnecting, retry the clone/push from the app or from the Codespace shell.
+
+## Voice transcription says no credentials were found
+
+- The bridge can transcribe with either `OPENAI_API_KEY`, `BRIDGE_CHATGPT_ACCESS_TOKEN`, or the same ChatGPT auth tokens already used for Codex login.
+- In GitHub Codespaces, finish the ChatGPT/Codex login step from the app first. The bridge will persist those tokens to `BRIDGE_WORKDIR/.clawdex-chatgpt-auth.json` and reuse them for voice transcription.
+- If you still see the error after logging in, restart the bridge once so it reloads the persisted auth cache:
+
+```bash
+npm run secure:bridge
+```
+
+- You can inspect whether the bridge captured the token bundle:
+
+```bash
+ls -la .clawdex-chatgpt-auth.json
+```
+
 ## Local browser preview does not open
 
 - The in-app browser only supports loopback targets from the bridge host: `localhost`, `127.0.0.1`, or `::1`.
@@ -49,6 +122,7 @@ npm run stop:services
 - By default the preview server binds to `BRIDGE_PORT + 1`.
 - Restart the bridge after changing `BRIDGE_PREVIEW_PORT`.
 - If the page shell loads but live reload does not, verify the target dev server is still serving its WebSocket/HMR endpoint locally.
+- In GitHub Codespaces, the preview port (`8788` by default) must also be public or the Browser screen will fail even if the main bridge port works.
 
 ## Tailscale issues
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdex-mobile",
-  "version": "5.1.2",
+  "version": "5.1.3-internal.1",
   "description": "Private-network mobile bridge and CLI for Codex and OpenCode",
   "keywords": [
     "codex",
@@ -34,6 +34,7 @@
     "docs/troubleshooting.md",
     "scripts/bridge-binary.js",
     "scripts/bridge-self-update.js",
+    "scripts/codespaces-bootstrap.js",
     "scripts/setup-secure-dev.sh",
     "scripts/setup-wizard.sh",
     "scripts/start-bridge-secure.js",
@@ -58,6 +59,7 @@
     "secure:setup": "./scripts/setup-secure-dev.sh",
     "secure:bridge": "node ./scripts/start-bridge-secure.js",
     "secure:bridge:dev": "node ./scripts/start-bridge-secure.js --dev",
+    "codespaces:bootstrap": "node ./scripts/codespaces-bootstrap.js",
     "bridge:ts": "BRIDGE_WORKDIR=$(pwd) npm run -w @codex/mac-bridge dev",
     "version:sync": "node scripts/sync-versions.js",
     "build": "npm run --workspaces build",

package/scripts/bridge-binary.js

@@ -81,9 +81,9 @@ function packagedBinaryPath(rootDir = repoRoot(), target = resolveRuntimeTarget(
   return path.join(rootDir, "vendor", "bridge-binaries", target, binaryNameForTarget(target));
 }
 
-function builtBinaryPath(rootDir = repoRoot(), platform = os.platform()) {
+function builtBinaryPath(rootDir = repoRoot(), platform = os.platform(), profile = "release") {
   const binaryName = platform === "win32" ? "codex-rust-bridge.exe" : "codex-rust-bridge";
-  return path.join(rootDir, "services", "rust-bridge", "target", "release", binaryName);
+  return path.join(rootDir, "services", "rust-bridge", "target", profile, binaryName);
 }
 
 function ensureExecutable(filePath) {
@@ -168,13 +168,13 @@ function main() {
       return;
     }
     case "current-built-path": {
-      console.log(builtBinaryPath(rootDir));
+      console.log(builtBinaryPath(rootDir, os.platform(), flags.profile || "release"));
       return;
     }
     case "stage-current": {
       const destination = stageBinary({
         rootDir,
-        from: builtBinaryPath(rootDir),
+        from: builtBinaryPath(rootDir, os.platform(), flags.profile || "release"),
         target: flags.target || resolveRuntimeTarget(),
       });
       console.log(destination);
@@ -194,8 +194,8 @@ function main() {
       console.error("  node scripts/bridge-binary.js current-target");
       console.error("  node scripts/bridge-binary.js has-current-packaged");
       console.error("  node scripts/bridge-binary.js current-packaged-path [--target <target>]");
-      console.error("  node scripts/bridge-binary.js current-built-path");
-      console.error("  node scripts/bridge-binary.js stage-current [--target <target>]");
+      console.error("  node scripts/bridge-binary.js current-built-path [--profile <debug|release>]");
+      console.error("  node scripts/bridge-binary.js stage-current [--target <target>] [--profile <debug|release>]");
       console.error("  node scripts/bridge-binary.js stage --from <binary> [--target <target>]");
       process.exit(1);
   }

package/scripts/codespaces-bootstrap.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function resolveRootDir() {
+  return path.resolve(__dirname, "..");
+}
+
+function resolveWorkspaceDir() {
+  const candidates = [
+    process.env.CLAWDEX_WORKSPACE_ROOT,
+    process.env.INIT_CWD,
+    process.cwd(),
+  ];
+
+  for (const candidate of candidates) {
+    if (typeof candidate !== "string" || !candidate.trim()) {
+      continue;
+    }
+    return path.resolve(candidate);
+  }
+
+  return resolveRootDir();
+}
+
+function readEnvFile(filePath) {
+  const contents = fs.readFileSync(filePath, "utf8");
+  const nextEnv = {};
+
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+    if (!match) {
+      continue;
+    }
+
+    const [, key, rawValue] = match;
+    let value = rawValue;
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    nextEnv[key] = value;
+  }
+
+  return nextEnv;
+}
+
+function readNonEmptyEnv(env, key) {
+  const value = env[key];
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+function runCommand(command, args, options = {}) {
+  return spawnSync(command, args, {
+    stdio: "inherit",
+    ...options,
+  });
+}
+
+function commandExists(command) {
+  if (typeof command === "string" && command.includes(path.sep)) {
+    try {
+      fs.accessSync(command, fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  const checker = process.platform === "win32" ? "where" : "which";
+  const result = spawnSync(checker, [command], { stdio: "ignore" });
+  return result.status === 0;
+}
+
+function parseArgs(argv) {
+  return {
+    noStart: argv.includes("--no-start"),
+    prepareOnly: argv.includes("--prepare-only"),
+    force: argv.includes("--force"),
+  };
+}
+
+function ensureCodespacesContext({ force }) {
+  if (force) {
+    return;
+  }
+
+  if (String(process.env.CODESPACES || "").trim().toLowerCase() === "true") {
+    return;
+  }
+
+  console.log("Codespaces bootstrap skipped because this shell is not running inside GitHub Codespaces.");
+  process.exit(0);
+}
+
+function runSetup(rootDir, workspaceDir) {
+  const setupEnv = {
+    ...process.env,
+  };
+
+  delete setupEnv.BRIDGE_NETWORK_MODE;
+  delete setupEnv.BRIDGE_HOST_OVERRIDE;
+  delete setupEnv.BRIDGE_ACTIVE_ENGINE;
+  delete setupEnv.BRIDGE_ENABLED_ENGINES;
+
+  setupEnv.INIT_CWD = rootDir;
+  setupEnv.CLAWDEX_WORKSPACE_ROOT = workspaceDir;
+  setupEnv.BRIDGE_NETWORK_MODE = "codespaces";
+  setupEnv.BRIDGE_HOST_OVERRIDE = "127.0.0.1";
+  setupEnv.BRIDGE_ACTIVE_ENGINE = "codex";
+  setupEnv.BRIDGE_ENABLED_ENGINES = "codex";
+
+  console.log("Preparing .env.secure for GitHub Codespaces...");
+  const result = runCommand(path.join(rootDir, "scripts", "setup-secure-dev.sh"), [], {
+    cwd: workspaceDir,
+    env: setupEnv,
+    shell: false,
+  });
+
+  if ((result.status ?? 1) !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function ensureCodexCliInstalled(secureEnv) {
+  const codexBinary = readNonEmptyEnv(secureEnv, "CODEX_CLI_BIN") || "codex";
+  if (commandExists(codexBinary)) {
+    return;
+  }
+
+  console.log("Codex CLI not found in this codespace. Installing via npm...");
+  const installResult = runCommand("npm", ["install", "-g", "@openai/codex"], {
+    cwd: resolveWorkspaceDir(),
+    env: process.env,
+  });
+  if ((installResult.status ?? 1) !== 0) {
+    console.error("error: failed to install Codex CLI automatically.");
+    process.exit(installResult.status ?? 1);
+  }
+
+  if (!commandExists(codexBinary)) {
+    console.error(`error: Codex CLI still not found after install attempt: ${codexBinary}`);
+    process.exit(1);
+  }
+
+  console.log("Codex CLI installed.");
+}
+
+function prepareBridgeBinary(rootDir, workspaceDir, secureEnv) {
+  console.log("Prebuilding bridge binary for faster Codespaces startup...");
+  const prepareEnv = {
+    ...process.env,
+    ...secureEnv,
+    CLAWDEX_WORKSPACE_ROOT: workspaceDir,
+    INIT_CWD: process.env.INIT_CWD || workspaceDir,
+  };
+  const result = runCommand(
+    process.execPath,
+    [path.join(rootDir, "scripts", "start-bridge-secure.js"), "--prepare-only"],
+    {
+      cwd: workspaceDir,
+      env: prepareEnv,
+    }
+  );
+
+  if ((result.status ?? 1) !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function startBridge(rootDir, workspaceDir) {
+  console.log("Starting bridge in background for this codespace...");
+  const result = runCommand(
+    process.execPath,
+    [path.join(rootDir, "scripts", "start-bridge-secure.js"), "--background"],
+    {
+      cwd: workspaceDir,
+      env: {
+        ...process.env,
+        CLAWDEX_WORKSPACE_ROOT: workspaceDir,
+        INIT_CWD: process.env.INIT_CWD || workspaceDir,
+      },
+    }
+  );
+
+  if ((result.status ?? 1) !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  ensureCodespacesContext(options);
+
+  const rootDir = resolveRootDir();
+  const workspaceDir = resolveWorkspaceDir();
+  const secureEnvPath = path.join(workspaceDir, ".env.secure");
+
+  runSetup(rootDir, workspaceDir);
+
+  if (!fs.existsSync(secureEnvPath)) {
+    console.error(`error: expected secure env at ${secureEnvPath}`);
+    process.exit(1);
+  }
+
+  const secureEnv = readEnvFile(secureEnvPath);
+  if (options.noStart || String(process.env.CLAWDEX_CODESPACES_SKIP_START || "").trim().toLowerCase() === "true") {
+    console.log("Codespaces bootstrap configured bridge env only. Bridge auto-start skipped.");
+    return;
+  }
+
+  ensureCodexCliInstalled(secureEnv);
+  if (options.prepareOnly) {
+    prepareBridgeBinary(rootDir, workspaceDir, secureEnv);
+    console.log("Codespaces bootstrap prepared Codex and the bridge binary without starting the bridge.");
+    return;
+  }
+  startBridge(rootDir, workspaceDir);
+}
+
+main();