Add Support for Mac by Bobyue0118 · Pull Request #6 · StarsTom/mobileCodexHelper

Bobyue0118 · 2026-04-10T08:37:34Z

变更说明

本 PR 在保留原有 Windows 优先路线的前提下，补充了一条 macOS + iPhone 的 mobile-first 使用路径，目标是让 Codex 继续运行在 Mac 上，而 iPhone 通过私有网页继续查看历史、发送消息和控制会话。

主要改动包括：

新增 owner-admin 后端接口和本地 Owner Admin 面板，用于本地审批首次登录的新设备、查看受信设备和 Tailscale 状态。
新增 macOS 运行脚本，包括启动/停止、本地运行环境检查、Tailscale 远程入口、以及可选的 launchd 自启动脚本。
同步更新 README 和部署文档，明确说明这个 macOS 路线与原始 Windows 支持版的区别，并补充新手上手流程。

为什么要改：
当前仓库的默认文档和运行方式明显偏 Windows，Mac 用户虽然能理解目标，但缺少一条“Codex 跑在 Mac、iPhone 私有访问并继续控制”的完整落地路径。这个 PR 主要是在不改变默认公网暴露模型的前提下，把这条路径补齐。

变更类型

你做了哪些验证

本地手动验证过
运行过相关脚本语法检查
运行过 python -m py_compile mobile_codex_control.py
运行过 scripts/check-open-source-tree.ps1
运行过 scripts/smoke-test-override-flow.ps1

请补充必要的验证说明：

- 在 macOS 本地对 vendor/claudecodeui-1.25.2 执行 ./scripts/apply-upstream-overrides.sh，覆盖文件应用成功
- 执行 ./scripts/check-mobile-codex-runtime.sh 和 ./scripts/test-macos-runtime.sh，通过
- 在 vendor/claudecodeui-1.25.2 目录执行 npm run build，成功
- 运行 node --test upstream-overrides/claudecodeui-1.25.2/server/utils/__tests__/owner-admin.test.mjs，通过
- 运行 node --test upstream-overrides/claudecodeui-1.25.2/src/components/admin/utils/__tests__/ownerAdminAccess.test.mjs，通过
- 运行 python3 -m py_compile mobile_codex_control.py，通过
- 本地交互验证 ./scripts/start-mobile-codex.sh -> curl -sf http://127.0.0.1:3001/health -> ./scripts/stop-mobile-codex.sh，流程正常
- 在 Mac + iPhone + Tailscale 实机环境下验证过：Mac 本地注册账号、iPhone 通过私有 URL 访问、首次设备审批、审批后继续使用流程可用

Copilot

Pull request overview

This PR shifts the repo toward a macOS-hosted, iPhone-first workflow by adding macOS runtime scripts and a browser-based “Owner Admin” surface to manage first-time device approvals (replacing the Windows desktop helper dependency for that flow).

Changes:

Add Owner Admin APIs + UI to view Tailscale/status, list pending/trusted devices, and approve/reject/revoke devices from the local Mac browser.
Add macOS-oriented Bash scripts for applying overrides, starting/stopping the service, enabling Tailscale Serve, and optional launchd auto-start.
Update READMEs and deployment docs to document the macOS mobile-first path alongside the existing Windows-first path.

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
upstream-overrides/claudecodeui-1.25.2/src/utils/api.js	Adds client wrappers for new Owner Admin auth endpoints.
upstream-overrides/claudecodeui-1.25.2/src/components/app/AppContent.tsx	Adds Owner Admin launcher button + modal panel wiring.
upstream-overrides/claudecodeui-1.25.2/src/components/admin/utils/ownerAdminAccess.js	Adds loopback-host gating logic for showing the Owner Admin launcher.
upstream-overrides/claudecodeui-1.25.2/src/components/admin/utils/tests/ownerAdminAccess.test.mjs	Adds unit tests for Owner Admin launcher gating.
upstream-overrides/claudecodeui-1.25.2/src/components/admin/useOwnerAdminState.ts	Adds polling state hook for Owner Admin status/devices and actions.
upstream-overrides/claudecodeui-1.25.2/src/components/admin/OwnerAdminPanel.tsx	Adds the Owner Admin modal UI (status, pending, trusted devices).
upstream-overrides/claudecodeui-1.25.2/server/utils/owner-admin.js	Adds server utilities for loopback detection and Tailscale status parsing.
upstream-overrides/claudecodeui-1.25.2/server/utils/tests/owner-admin.test.mjs	Adds unit tests for owner-admin utilities.
upstream-overrides/claudecodeui-1.25.2/server/routes/auth.js	Adds Owner Admin routes + local-session restriction middleware.
upstream-overrides/claudecodeui-1.25.2/server/database/db.js	Adds DB helper to list pending approval requests scoped to a user.
scripts/uninstall-mobile-codex-launchd.sh	Adds uninstall helper for macOS `launchd` agent.
scripts/test-macos-runtime.sh	Adds basic macOS script sanity + path anchoring checks.
scripts/stop-mobile-codex.sh	Adds stop script for the macOS-run local service.
scripts/stop-mobile-codex-stack.sh	Adds wrapper stop script for the “stack”.
scripts/start-mobile-codex.sh	Adds start script for the macOS-run local service (localhost-bound).
scripts/start-mobile-codex-stack.sh	Adds wrapper start script for the “stack”.
scripts/lib-mobile-codex.sh	Adds shared macOS script helpers (paths, node/tailscale resolution, logs).
scripts/install-mobile-codex-launchd.sh	Adds installer for a per-user `launchd` agent to auto-start service.
scripts/enable-mobile-codex-remote.sh	Adds Tailscale Serve helper to expose the localhost service privately.
scripts/check-mobile-codex-runtime.sh	Adds runtime diagnostic script for macOS workflow.
scripts/apply-upstream-overrides.sh	Adds Bash override-applier to copy override layer into upstream checkout.
README.md	Reframes docs toward macOS+iPhone workflow; keeps Windows docs pointers.
README.en.md	English version of macOS+iPhone workflow docs and commands.
docs/superpowers/specs/2026-04-10-macos-mobile-codex-design.md	Adds macOS mobile-first design/spec doc for the new workflow.
docs/DEPLOYMENT.zh-CN.md	Adds note that this remains the Windows-first deployment path.
docs/DEPLOYMENT.md	Adds note that this remains the Windows-first deployment path.
docs/DEPLOYMENT-macos.zh-CN.md	Adds macOS mobile-first deployment guide (CN).
docs/DEPLOYMENT-macos.md	Adds macOS mobile-first deployment guide (EN).
.gitignore	Ignores `.worktrees/` alongside local runtime/output directories.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-10T08:43:26Z

+    typeof req.headers['x-forwarded-for'] === 'string'
+      ? req.headers['x-forwarded-for'].split(',')[0].trim()
+      : null,
+    req.ip,
+    req.socket?.remoteAddress,


requireLocalOwnerSession currently allows access if any of x-forwarded-for, req.ip, or req.socket.remoteAddress is loopback. In a proxied setup (e.g., Tailscale Serve), req.socket.remoteAddress will be loopback even for remote iPhone requests, which defeats the “local Mac browser only” restriction. Prefer checking the client IP only (e.g., req.ip with app.set('trust proxy', 1) already in use) and/or explicitly rejecting proxied requests instead of accepting loopback proxy addresses.

Copilot · 2026-04-10T08:43:26Z

+    void refresh();
+    const timer = window.setInterval(() => {
+      void refresh();
+    }, 3000);
+


The Owner Admin UI refresh runs on a fixed setInterval without guarding against an in-flight refresh() call. If any of the 3 requests takes >3s, multiple concurrent refreshes can stack up and cause extra load / out-of-order state updates. Consider using a self-scheduling setTimeout loop, tracking an inFlight flag, or cancelling/ignoring overlapping refreshes.

Copilot · 2026-04-10T08:43:26Z

+backend_state="$(python3 - <<'PY' "$status_json"
+import json, sys
+payload = json.loads(sys.argv[1])
+print(payload.get("BackendState", "Unknown"))
+PY


This script assumes python3 is available for JSON parsing, but it doesn’t check for it or fail with a targeted message. On many macOS setups python3 is not installed by default. Add an explicit command -v python3 check (with a clear install hint) or switch the JSON parsing to a tool you already require (e.g., Node).

Copilot · 2026-04-10T08:43:27Z

+  local target="$1"
+  local message="$2"
+
+  [[ -e "$target" ]] || {
+    echo "$message: $target" >&2


require_path only checks -e (exists), but it’s used for both directories and executables (e.g., Node). This can allow non-executable files or the wrong path type to pass validation and fail later with less clear errors. Consider adding require_executable / require_directory helpers (or parameterizing the check) so scripts fail fast with accurate diagnostics.

Copilot · 2026-04-10T08:43:27Z

+- a patched `claudecodeui` layer under [upstream-overrides/claudecodeui-1.25.2](/Users/bobyue/Documents/GitHub/mobileCodexHelper/upstream-overrides/claudecodeui-1.25.2)
+- Codex session discovery and resume support in [upstream-overrides/claudecodeui-1.25.2/server/openai-codex.js](/Users/bobyue/Documents/GitHub/mobileCodexHelper/upstream-overrides/claudecodeui-1.25.2/server/openai-codex.js)
+- project and session browsing in [upstream-overrides/claudecodeui-1.25.2/server/projects.js](/Users/bobyue/Documents/GitHub/mobileCodexHelper/upstream-overrides/claudecodeui-1.25.2/server/projects.js)
+- login and trusted-device persistence in [upstream-overrides/claudecodeui-1.25.2/server/routes/auth.js](/Users/bobyue/Documents/GitHub/mobileCodexHelper/upstream-overrides/claudecodeui-1.25.2/server/routes/auth.js) and [upstream-overrides/claudecodeui-1.25.2/server/database/db.js](/Users/bobyue/Documents/GitHub/mobileCodexHelper/upstream-overrides/claudecodeui-1.25.2/server/database/db.js)


This spec uses absolute local filesystem paths (e.g., /Users/.../mobileCodexHelper/...) in links, which won’t work for other contributors and leaks local environment details. Replace these with repo-relative links (e.g., ./upstream-overrides/claudecodeui-1.25.2/...) so the document renders correctly on GitHub.

Copilot · 2026-04-10T08:43:27Z

+- PowerShell scripts under [scripts](/Users/bobyue/Documents/GitHub/mobileCodexHelper/scripts)
+- a Windows desktop helper in [mobile_codex_control.py](/Users/bobyue/Documents/GitHub/mobileCodexHelper/mobile_codex_control.py)
+- Windows/nginx deployment assumptions in [README.md](/Users/bobyue/Documents/GitHub/mobileCodexHelper/README.md) and [docs/DEPLOYMENT.md](/Users/bobyue/Documents/GitHub/mobileCodexHelper/docs/DEPLOYMENT.md)


These bullets also link to absolute local paths (e.g., /Users/...) instead of repo-relative links, which breaks on GitHub and exposes local directory structure. Update them to relative links within the repository.

Copilot · 2026-04-10T08:43:27Z

+test('isLoopbackHost accepts macOS local browser hostnames', () => {
+  assert.equal(isLoopbackHost('127.0.0.1'), true);
+  assert.equal(isLoopbackHost('localhost'), true);
+  assert.equal(isLoopbackHost('::1'), true);
+  assert.equal(isLoopbackHost('bobyue-mac.tail123.ts.net'), false);
+});


The test data includes what looks like a personal machine DNS name (bobyue-mac.tail123.ts.net). Even if it’s not a secret, it’s better to avoid embedding personal identifiers in tests; use a clearly fake placeholder domain (e.g., example-mac.tailnet.ts.net).

Copilot · 2026-04-10T08:43:27Z

+test('buildOwnerAdminStatus returns local and remote URLs', () => {
+  const payload = buildOwnerAdminStatus({
+    workspacesRoot: '/Users/bobyue/Code',
+    tailscaleState: {
+      installed: true,
+      running: true,
+      backendState: 'Running',
+      dnsName: 'bobyue-mac.tail123.ts.net',
+      remoteUrl: 'https://bobyue-mac.tail123.ts.net',
+      authUrl: null,


This test hardcodes what appears to be a personal home directory (/Users/bobyue/Code) and a specific device DNS name. To keep the repo generic and avoid leaking identifiers, switch these to neutral placeholder values (e.g., /Users/example/Code, example-mac.tailnet.ts.net).

Bobyue0118 added 8 commits April 10, 2026 12:59

docs: add macos mobile codex design spec

3cbd41a

chore: ignore local worktrees

26fd086

feat: add owner admin backend APIs

e578a09

feat: add macos runtime shell foundation

b0abbbc

feat: add macos owner admin panel

4eb94ce

feat: add macos runtime and launchd scripts

5b7d43d

docs: add macos mobile deployment guide

9ce2c4b

docs: rewrite README for macos beginners

a38d5c4

Copilot AI review requested due to automatic review settings April 10, 2026 08:37

Copilot started reviewing on behalf of Bobyue0118 April 10, 2026 08:38 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

fix: redact personal examples from tests and spec

459b521

Gyarados4157 added a commit to Gyarados4157/mobileCodexHelper that referenced this pull request Apr 11, 2026

merge: PR StarsTom#6 add macOS support

07ab800

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Support for Mac#6

Add Support for Mac#6
Bobyue0118 wants to merge 9 commits into
StarsTom:mainfrom
Bobyue0118:main

Bobyue0118 commented Apr 10, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Copilot AI Apr 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Bobyue0118 commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

变更说明

变更类型

你做了哪些验证

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Bobyue0118 commented Apr 10, 2026 •

edited

Loading