clawdex-mobile 5.1.3-internal.8 → 5.2.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.2.0 - 2026-05-18
+
+### Added
+- Cursor support alongside Codex and OpenCode.
+- Bundled `cursor-app-server` in the published `clawdex-mobile` package.
+- Bridge-driven mobile UI payload support for richer runtime details.
+
+### Improved
+- `clawdex init` now gives clearer Cursor API key setup guidance.
+- Published-package setup now avoids source-checkout workspace assumptions.
+- Bridge onboarding waits longer for first-start readiness.
+
+### Fixed
+- Cursor setup now fails visibly when the API key or app-server path is missing instead of falling through silently.
+
 ## 5.1.2 - 2026-04-07
 
 ### Added

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, local LAN, or GitHub Codespaces forwarded HTTPS URLs.
+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.
 
-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.
+This project is for trusted/private networking by default. Keep the bridge on a private network, leave bridge auth enabled, and do not expose it directly to the public internet.
 
 ## What You Get
 
@@ -25,11 +25,11 @@ Before you start:
 - `git`
 - `codex` in `PATH` for the default Codex flow
 - `opencode` in `PATH` if you want the OpenCode flow
-- `cursor-app-server` in `PATH` if you want the Cursor SDK flow
+- Cursor app-server is bundled with `clawdex-mobile` for the Cursor SDK flow
 
 Install the mobile app:
 
-- Android APK: <https://github.com/Mohit-Patil/clawdex-mobile/releases/latest>
+- Android APK: <https://www.getclawdex.com/android-beta/>
 - iOS: <https://apple.co/4rNAHRF>
 
 Install the CLI and start the bridge:
@@ -53,72 +53,23 @@ 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_APP_CLIENT_ID` and `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL`, users can now tap `Use GitHub Codespaces` in onboarding/settings, complete one in-app GitHub sign-in, pick a Codespace, and connect without manually copying the bridge token.
-- The tiny auth backend for that flow lives in `services/github-app-auth-worker`. Point the GitHub App callback URL at `https://<your-domain>/github/callback` and configure the worker with the GitHub App client ID/secret.
-- 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 the selected engines 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 default enabled engine and starts the bridge in the background. You can rerun either command manually any time.
-
-To enable more engines in Codespaces, set `CLAWDEX_CODESPACES_ENGINES` before bootstrap:
-
-```bash
-CLAWDEX_CODESPACES_ENGINES=codex,opencode,cursor npm run codespaces:bootstrap
-```
-
-When `opencode` or `cursor` are selected, bootstrap installs their CLI/server package if the command is missing. Cursor still needs `CURSOR_API_KEY` in the environment or `.env.secure`.
-
-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 App user token it used to discover and start the Codespace.
-
 ## Extra Harness Setup
 
 OpenCode and Cursor can run beside Codex from the same bridge.
 
 ```bash
 npm install -g opencode-ai
-npm install -g @clawdex/cursor-app-server
 npm install -g clawdex-mobile@latest
 clawdex init --engines codex,opencode,cursor
 ```
 
-That writes `BRIDGE_ENABLED_ENGINES=codex,opencode,cursor` to `.env.secure`, so the mobile app can control the selected harnesses from one bridge. When Cursor is selected, `clawdex init` asks for the Cursor API key and saves it in `.env.secure`.
+That writes `BRIDGE_ENABLED_ENGINES=codex,opencode,cursor` to `.env.secure`, so the mobile app can control the selected harnesses from one bridge. When Cursor is selected, `clawdex init` uses the bundled `cursor-app-server`, asks for a Cursor account API key from Cursor Dashboard > Integrations > User API Keys, and saves it in `.env.secure`. Cursor documents this under CLI authentication: https://docs.cursor.com/en/cli/reference/authentication
 
 Notes:
 
 - `clawdex init` without flags now lets you multi-select harnesses in the wizard with Space, then Enter to continue.
 - Use `clawdex init --engine codex`, `clawdex init --engine opencode`, or `clawdex init --engine cursor` if you want a single-harness setup.
-- For non-interactive host automation, set `CURSOR_API_KEY` before running setup. `CURSOR_MODEL` is optional; the app model picker sends the model for normal chats.
+- For non-interactive host automation, set `CURSOR_API_KEY` before running setup. This should be a Cursor account API key for the Cursor agent/SDK, not an OpenAI, Anthropic, or other provider key configured inside the Cursor editor. `CURSOR_MODEL` is optional; the app model picker sends the model for normal chats.
 
 ## Monorepo Development
 

package/bin/clawdex.js

@@ -10,11 +10,11 @@ function printUsage() {
   console.log(`Usage: clawdex <command> [options]
 
 Commands:
-  init [--no-start] [--engine codex|opencode]
+  init [--no-start] [--engine codex|opencode|cursor] [--engines codex,opencode,cursor]
       Run interactive bridge onboarding and secure setup.
       By default, this also starts the secure bridge in the background.
       Use --no-start to configure only.
-      Use --engine to set the preferred backend written to .env.secure.
+      Use --engine or --engines to choose the backend harnesses written to .env.secure.
 
   stop
       Stop bridge services for this project.

package/docs/setup-and-operations.md

@@ -2,6 +2,8 @@
 
 This guide is the detailed companion to the top-level `README.md`.
 
+For bridge-driven provider UI payloads such as Codex goals, see `docs/bridge-ui-surfaces.md`.
+
 ## Choosing Harnesses
 
 The setup wizard now lets you choose which harnesses the phone should control.
@@ -18,7 +20,7 @@ From a source checkout, the equivalent command is:
 npm run setup:wizard -- --engines codex,opencode,cursor
 ```
 
-That writes `BRIDGE_ENABLED_ENGINES=codex,opencode,cursor` into `.env.secure`, so the bridge starts the selected backends and the mobile app can control them from one UI. When Cursor is selected, `clawdex init` asks for the Cursor API key and saves it in `.env.secure`.
+That writes `BRIDGE_ENABLED_ENGINES=codex,opencode,cursor` into `.env.secure`, so the bridge starts the selected backends and the mobile app can control them from one UI. When Cursor is selected, `clawdex init` uses the bundled `cursor-app-server`, asks for a Cursor account API key from Cursor Dashboard > Integrations > User API Keys, and saves it in `.env.secure`. Cursor documents this under CLI authentication: https://docs.cursor.com/en/cli/reference/authentication
 
 If you want only one harness, use `--engine codex`, `--engine opencode`, or `--engine cursor`.
 
@@ -39,87 +41,6 @@ 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_APP_CLIENT_ID` and `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL`, onboarding/settings can now open one GitHub sign-in, start the Codespace, and connect directly with the same GitHub App user token instead of copying `BRIDGE_AUTH_TOKEN`
-- Users do not need to grant the GitHub App repository installation access to the `clawdex-codespace` template for the normal Codespaces flow
-- 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 App token and refresh token are updated
-
-For the one-flow GitHub App setup:
-
-- deploy the tiny auth service under `services/github-app-auth-worker`
-- set the GitHub App `Callback URL` to `https://<your-domain>/github/callback`
-- set the mobile env `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL=https://<your-domain>`
-
-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`, `BRIDGE_GITHUB_CODESPACES_AUTH=true`, and the selected engine list
-- writes `CODEX_HOME=$HOME/.codex` in Codespaces so Codex-managed ChatGPT auth survives bridge restarts and Codespace wakes
-- starts the bridge in the background unless you set `CLAWDEX_CODESPACES_SKIP_START=true` or pass `--no-start`
-
-Clawdex-created Codespaces request a 45-minute idle timeout. The bridge emits a lightweight active-turn keepalive while a Codex, OpenCode, or Cursor turn is running, so active work has activity even if a long step is otherwise quiet. When no turn is running, the keepalive stops and GitHub can pause the Codespace normally to save cost.
-
-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
-CLAWDEX_CODESPACES_ENGINES=codex,opencode,cursor npm run codespaces:bootstrap
-```
-
-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
@@ -161,7 +82,7 @@ When multiple harnesses are selected, the bridge starts each backend and merges
 
 ### 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`, `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.
+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.
 
 ### In-app Bridge Maintenance
 
@@ -268,7 +189,7 @@ npm run teardown -- --yes
 
 | Variable | Purpose |
 |---|---|
-| `BRIDGE_NETWORK_MODE` | bridge connectivity mode (`tailscale`, `local`, or `codespaces`) |
+| `BRIDGE_NETWORK_MODE` | bridge connectivity mode (`tailscale` or `local`) |
 | `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`) |
@@ -276,16 +197,12 @@ npm run teardown -- --yes
 | `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_HOME` | Codex auth/config home; set to `$HOME/.codex` in Codespaces so ChatGPT auth persists across bridge restarts |
 | `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`, `cursor`, or a comma-separated mix) |
 | `OPENCODE_CLI_BIN` | opencode executable for dual-engine startup |
-| `CURSOR_APP_SERVER_BIN` | Cursor app-server executable, usually `cursor-app-server` |
-| `CURSOR_API_KEY` | Cursor API key used by the Cursor SDK harness; collected by `clawdex init` when Cursor is selected |
+| `CURSOR_APP_SERVER_BIN` | Cursor app-server executable, usually the `cursor-app-server` binary bundled with `clawdex-mobile` |
+| `CURSOR_API_KEY` | Cursor account API key used by the Cursor SDK harness; create it from Cursor Dashboard > Integrations > User API Keys, then provide it to `clawdex init` when Cursor is selected. See https://docs.cursor.com/en/cli/reference/authentication |
 | `CURSOR_MODEL` | optional Cursor model id for non-interactive host defaults; normal mobile chats send the selected model |
 | `BRIDGE_OPENCODE_HOST` | loopback host for spawned opencode server |
 | `BRIDGE_OPENCODE_PORT` | loopback port for spawned opencode server |
@@ -299,13 +216,6 @@ npm run teardown -- --yes
 | Variable | Purpose |
 |---|---|
 | `EXPO_PUBLIC_HOST_BRIDGE_TOKEN` | token used by local mobile dev builds |
-| `EXPO_PUBLIC_GITHUB_APP_CLIENT_ID` | GitHub App client ID for in-app Codespaces sign-in |
-| `EXPO_PUBLIC_GITHUB_APP_SLUG` | optional GitHub App slug, reserved for future manage-access flows |
-| `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL` | HTTPS origin for the GitHub App auth worker (`/api/github/exchange`, `/api/github/refresh`, `/github/callback`) |
-| `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 |
@@ -326,8 +236,7 @@ If you enable the optional tip jar:
 ## Production Readiness Checklist
 
 - 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)
+- Require bridge auth with `BRIDGE_AUTH_TOKEN`
 - 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
@@ -454,12 +363,17 @@ Automation verifies tag/version consistency and publishes to npm.
 - `bridge/approvals/list`
 - `bridge/approvals/resolve`
 - `bridge/userInput/resolve`
+- `bridge/ui/present`
+- `bridge/ui/update`
+- `bridge/ui/dismiss`
+- `bridge/ui/resolve`
 
 ### Notifications (examples)
 
 - `turn/*`, `item/*`
 - `bridge/approval.*`
 - `bridge/userInput.*`
+- `bridge/ui.*`
 - `bridge/terminal/completed`
 - `bridge/git/updated`
 - `bridge/connection/state`

package/docs/troubleshooting.md

@@ -34,93 +34,26 @@ 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 GitHub App token or refresh 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_APP_CLIENT_ID`, `EXPO_PUBLIC_GITHUB_APP_SLUG`, and `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL`.
-- If the GitHub browser sheet returns but sign-in still fails, confirm the GitHub App callback URL is `https://<your-domain>/github/callback` and that `Request user authorization (OAuth) during installation` is enabled.
-- If the app signs in but still cannot create a Codespace or clone/push inside it, reopen the GitHub App access step in the app and make sure the template repo and any target repos are selected for the installation.
-- 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 `OPENAI_API_KEY`, `BRIDGE_CHATGPT_ACCESS_TOKEN`, a legacy bridge token cache, or the Codex-managed ChatGPT token in `$CODEX_HOME/auth.json`.
-- In GitHub Codespaces, finish the Codex login step from the app first. Codex writes the login to `$HOME/.codex/auth.json`, and `.env.secure` sets `CODEX_HOME` to that persistent location.
-- Current app builds automatically restart the Codespace Codex app-server after the Codex login step so it reloads the Codex auth home. On older builds, restart the bridge once after logging in:
+- If Codex login just completed, restart the bridge once so it reloads the Codex auth home:
 
 ```bash
 npm run secure:bridge
 ```
 
-- You can inspect whether Codex saved auth in the Codespace:
+- You can inspect whether Codex saved auth:
 
 ```bash
 ls -la "${CODEX_HOME:-$HOME/.codex}/auth.json"
 ```
 
-## Codespace wakes but Codex says account authentication is required
-
-- Codespaces should use Codex-managed auth, the same as a local bridge. The login is stored in `${CODEX_HOME:-$HOME/.codex}/auth.json`.
-- The app starts Codex's normal ChatGPT web login first. It captures the OAuth callback on the phone and forwards that callback to the Codex loopback server inside the Codespace, so device-code login is only a fallback.
-- Run `source .env.secure && ls -la "$CODEX_HOME/auth.json"` in the Codespace to confirm the auth file exists.
-- If the file is missing, reopen GitHub Codespaces setup in the app and complete the Codex login step once. After that, bridge restarts and Codespace wakes should not require reauthentication.
-
 ## 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`.
@@ -131,7 +64,6 @@ ls -la "${CODEX_HOME:-$HOME/.codex}/auth.json"
 - 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,7 +1,7 @@
 {
   "name": "clawdex-mobile",
-  "version": "5.1.3-internal.8",
-  "description": "Private-network mobile bridge and CLI for Codex and OpenCode",
+  "version": "5.2.0",
+  "description": "Private-network mobile bridge and CLI for Codex, OpenCode, and Cursor",
   "keywords": [
     "codex",
     "opencode",
@@ -20,10 +20,13 @@
     "access": "public"
   },
   "dependencies": {
-    "qrcode-terminal": "^0.12.0"
+    "@cursor/sdk": "1.0.11",
+    "qrcode-terminal": "^0.12.0",
+    "zod": "^3.25.0"
   },
   "bin": {
-    "clawdex": "./bin/clawdex.js"
+    "clawdex": "bin/clawdex.js",
+    "cursor-app-server": "services/cursor-app-server/dist/stdio.js"
   },
   "files": [
     "CHANGELOG.md",
@@ -34,11 +37,13 @@
     "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",
     "scripts/stop-services.sh",
+    "services/cursor-app-server/dist",
+    "services/cursor-app-server/README.md",
+    "services/cursor-app-server/package.json",
     "services/rust-bridge/Cargo.lock",
     "services/rust-bridge/Cargo.toml",
     "services/rust-bridge/src",
@@ -52,18 +57,24 @@
     "mobile": "./scripts/start-expo.sh mobile",
     "ios": "./scripts/start-expo.sh ios",
     "android": "./scripts/start-expo.sh android",
+    "desktop:mac": "swift run --package-path apps/macos ClawdexDesktop",
+    "desktop:mac:build": "swift build --package-path apps/macos",
+    "desktop:mac:bundle": "./scripts/build-macos-desktop-app.sh",
+    "desktop:mac:sign": "./scripts/sign-macos-desktop-app.sh",
+    "desktop:mac:notarize": "./scripts/notarize-macos-desktop-app.sh",
     "stack:lan": "./scripts/start-mobile-stack-lan.sh",
     "stack:tailscale": "./scripts/start-mobile-stack-tailscale.sh",
     "bridge": "BRIDGE_WORKDIR=$(pwd) npm run -w @codex/rust-bridge dev",
+    "bridge:ui:demo": "node ./scripts/send-bridge-ui-demo.js",
     "bridge:package:stage-current": "node ./scripts/bridge-binary.js stage-current",
     "setup:wizard": "./scripts/setup-wizard.sh",
     "stop:services": "./scripts/stop-services.sh",
     "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",
+    "prepack": "npm run build -w @clawdex/cursor-app-server",
     "build": "npm run --workspaces build",
     "typecheck": "npm run --workspaces typecheck",
     "lint": "npm run --workspaces lint",

package/scripts/setup-secure-dev.sh

@@ -112,51 +112,6 @@ is_non_loopback_ipv4() {
   [[ "$ip" != 127.* ]]
 }
 
-normalize_base_url() {
-  local value="$1"
-  value="$(printf '%s' "$value" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
-  if [[ -z "$value" ]]; then
-    return 1
-  fi
-
-  case "$value" in
-    http://*|https://*)
-      ;;
-    *)
-      return 1
-      ;;
-  esac
-
-  printf '%s' "${value%/}"
-}
-
-resolve_codespaces_forwarded_url() {
-  local port="$1"
-  local override="$2"
-  local normalized_override=""
-  local codespace_name=""
-  local forwarding_domain=""
-
-  if [[ -n "$override" ]]; then
-    normalized_override="$(normalize_base_url "$override" || true)"
-    if [[ -z "$normalized_override" ]]; then
-      echo "error: invalid Codespaces URL override '$override'." >&2
-      return 1
-    fi
-    printf '%s' "$normalized_override"
-    return 0
-  fi
-
-  codespace_name="$(printf '%s' "${CODESPACE_NAME:-}" | tr -d '[:space:]')"
-  forwarding_domain="$(printf '%s' "${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN:-}" | tr -d '[:space:]')"
-  if [[ -z "$codespace_name" ]] || [[ -z "$forwarding_domain" ]]; then
-    echo "error: GitHub Codespaces env vars are missing. Run this inside an active codespace or set BRIDGE_CONNECT_URL_OVERRIDE." >&2
-    return 1
-  fi
-
-  printf 'https://%s-%s.%s' "$codespace_name" "$port" "$forwarding_domain"
-}
-
 resolve_tailscale_ipv4() {
   local ip
   ip="$(tailscale ip -4 2>/dev/null | head -n1 | tr -d '[:space:]' || true)"
@@ -272,10 +227,10 @@ HOST_SOURCE=""
 BRIDGE_NETWORK_MODE="${BRIDGE_NETWORK_MODE:-tailscale}"
 
 case "$BRIDGE_NETWORK_MODE" in
-  tailscale|local|codespaces)
+  tailscale|local)
     ;;
   *)
-    echo "error: BRIDGE_NETWORK_MODE must be 'tailscale', 'local', or 'codespaces'." >&2
+    echo "error: BRIDGE_NETWORK_MODE must be 'tailscale' or 'local'." >&2
     exit 1
     ;;
 esac
@@ -345,9 +300,6 @@ else
     ensure_tailscale_cli
     BRIDGE_HOST="$(resolve_tailscale_ipv4)"
     HOST_SOURCE="tailscale"
-  elif [[ "$BRIDGE_NETWORK_MODE" == "codespaces" ]]; then
-    BRIDGE_HOST="127.0.0.1"
-    HOST_SOURCE="codespaces"
   else
     BRIDGE_HOST="$(resolve_local_ipv4)"
     HOST_SOURCE="local"
@@ -361,17 +313,8 @@ if [[ "$BRIDGE_PREVIEW_PORT" == "$BRIDGE_PORT" ]]; then
   exit 1
 fi
 
-if [[ "$BRIDGE_NETWORK_MODE" == "codespaces" ]]; then
-  BRIDGE_CONNECT_URL="$(
-    resolve_codespaces_forwarded_url "$BRIDGE_PORT" "${BRIDGE_CONNECT_URL_OVERRIDE:-}"
-  )"
-  BRIDGE_PREVIEW_CONNECT_URL="$(
-    resolve_codespaces_forwarded_url "$BRIDGE_PREVIEW_PORT" "${BRIDGE_PREVIEW_CONNECT_URL_OVERRIDE:-}"
-  )"
-else
-  BRIDGE_CONNECT_URL="http://$BRIDGE_HOST:$BRIDGE_PORT"
-  BRIDGE_PREVIEW_CONNECT_URL="http://$BRIDGE_HOST:$BRIDGE_PREVIEW_PORT"
-fi
+BRIDGE_CONNECT_URL="http://$BRIDGE_HOST:$BRIDGE_PORT"
+BRIDGE_PREVIEW_CONNECT_URL="http://$BRIDGE_HOST:$BRIDGE_PREVIEW_PORT"
 
 EXISTING_TOKEN=""
 if [[ -f "$SECURE_ENV_FILE" ]]; then
@@ -383,17 +326,6 @@ if [[ -z "$BRIDGE_TOKEN" ]]; then
   BRIDGE_TOKEN="$(openssl rand -hex 24)"
 fi
 
-GITHUB_CODESPACES_AUTH_ENABLED="false"
-GITHUB_CODESPACES_NAME=""
-CODEX_HOME_ENV_BLOCK=""
-if [[ "$BRIDGE_NETWORK_MODE" == "codespaces" ]]; then
-  GITHUB_CODESPACES_AUTH_ENABLED="true"
-  GITHUB_CODESPACES_NAME="$(printf '%s' "${CODESPACE_NAME:-}" | tr -d '[:space:]')"
-  CODEX_AUTH_HOME="${CODEX_HOME:-$HOME/.codex}"
-  mkdir -p "$CODEX_AUTH_HOME"
-  CODEX_HOME_ENV_BLOCK="CODEX_HOME=$CODEX_AUTH_HOME"
-fi
-
 cat > "$SECURE_ENV_FILE" <<EOT
 BRIDGE_NETWORK_MODE=$BRIDGE_NETWORK_MODE
 BRIDGE_HOST=$BRIDGE_HOST
@@ -403,12 +335,8 @@ BRIDGE_CONNECT_URL=$BRIDGE_CONNECT_URL
 BRIDGE_PREVIEW_CONNECT_URL=$BRIDGE_PREVIEW_CONNECT_URL
 BRIDGE_AUTH_TOKEN=$BRIDGE_TOKEN
 BRIDGE_ALLOW_QUERY_TOKEN_AUTH=true
-BRIDGE_GITHUB_CODESPACES_AUTH=$GITHUB_CODESPACES_AUTH_ENABLED
-BRIDGE_GITHUB_CODESPACE_NAME=$GITHUB_CODESPACES_NAME
-BRIDGE_GITHUB_API_URL=https://api.github.com
 BRIDGE_ACTIVE_ENGINE=$BRIDGE_ACTIVE_ENGINE
 BRIDGE_ENABLED_ENGINES=$BRIDGE_ENABLED_ENGINES
-$CODEX_HOME_ENV_BLOCK
 CODEX_CLI_BIN=codex
 OPENCODE_CLI_BIN=$OPENCODE_CLI_BIN
 CURSOR_APP_SERVER_BIN=$CURSOR_APP_SERVER_BIN
@@ -425,6 +353,7 @@ if has_local_mobile_workspace; then
   upsert_env_key "$MOBILE_ENV_FILE" "EXPO_PUBLIC_MAC_BRIDGE_TOKEN" "$BRIDGE_TOKEN"
   upsert_env_key "$MOBILE_ENV_FILE" "EXPO_PUBLIC_ALLOW_QUERY_TOKEN_AUTH" "true"
   upsert_env_key "$MOBILE_ENV_FILE" "EXPO_PUBLIC_ALLOW_INSECURE_REMOTE_BRIDGE" "true"
+  chmod 600 "$MOBILE_ENV_FILE"
 fi
 
 echo "Secure dev setup complete."
@@ -433,9 +362,6 @@ echo "Bridge network mode: $BRIDGE_NETWORK_MODE"
 echo "Bridge host: $BRIDGE_HOST ($HOST_SOURCE)"
 echo "Bridge port: $BRIDGE_PORT"
 echo "Bridge connect URL: $BRIDGE_CONNECT_URL"
-if [[ "$GITHUB_CODESPACES_AUTH_ENABLED" == "true" ]]; then
-  echo "GitHub Codespaces auth: enabled"
-fi
 echo "Harnesses: $BRIDGE_ENABLED_ENGINES"
 echo "Token source: $SECURE_ENV_FILE"
 if has_local_mobile_workspace; then