Cmux iPhone

English · 한국어

Watch and control your Claude Code, Codex, and cmux sessions from your iPhone (and Apple Watch).
See live terminal output and send prompts; approve permission requests on iPhone and monitor them on Apple Watch — over your LAN or Tailscale.

https://github.com/user-attachments/assets/5f478c28-2086-4696-9d76-e43dda853201

How it works (two halves)

   iPhone / Watch  ──HTTP+SSE──►  cmux-iphone bridge (Node)  ──hooks──►  Claude Code
   (SwiftUI app)   ◄────────────  on your Mac                 ──RPC───►  cmux mirror
                                                              ──log───►  Codex

• Bridge (Mac): a small Node server (cmux-iphone) that receives Claude Code hook events, mirrors live cmux workspaces, watches Codex, and serves the phone over HTTP + Server-Sent Events. Discovered on the LAN via Bonjour.
• App (iPhone + Watch): a SwiftUI app that pairs with the bridge, shows live sessions/terminal output, and answers permission prompts.

Everything runs on your own machines — no cloud, no account, no server to host. The bridge is loopback-only by default (expose it over Tailscale/LAN explicitly); a pairing code + per-device token are the auth boundary. Run it over Tailscale or a trusted LAN — it is not built to face the open internet (see SECURITY.md).

cmux is optional. With cmux installed you get the live workspace/terminal mirror; without it, the bridge still streams hook-based Claude/Codex sessions.

Requirements

Install — the Mac bridge

Homebrew (recommended)

brew install lim-won/tap/cmux-iphone
cmux-iphone setup

brew upgrade cmux-iphone updates it; re-run cmux-iphone setup once afterward so the LaunchAgent / cmux workspace re-point at the new version.

From source

git clone https://github.com/lim-won/cmux-iphone && cd cmux-iphone/skill/bridge
npm ci                        # reproducible install (use `npm install` if no lockfile)
npm link                      # optional: puts `cmux-iphone` on your PATH
cmux-iphone setup             # or: node bin/cmux-iphone.js setup

cmux-iphone setup is idempotent (safe to re-run). It:

1. checks macOS + Node 18+, detects Claude/Codex/cmux/Tailscale,
2. writes config.json and generates secrets (0600, never rotated on re-run),
3. backs up ~/.claude/settings.json and merges Cmux iPhone's hooks (scoped — it never touches another tool's hooks),
4. picks a runner — in-cmux when cmux is present (so the live mirror works), or a LaunchAgent when it isn't,
5. health-checks the bridge and prints your LAN/Tailscale address + pairing code.

Why two runners? A launchd process cannot reach the cmux control socket (verified). So when cmux is present the bridge runs inside a cmux workspace; otherwise it runs as a LaunchAgent serving hook/phone/Codex sessions only.

Using the cmux mirror

For the live cmux mirror, cmux must be running and its control socket reachable when you run setup (configure cmux's socket password if it uses one). Then:

cmux-iphone setup --cmux     # fails fast if cmux RPC isn't reachable (instead of half-installing)
cmux-iphone doctor           # confirm:  cmux RPC = mobile.workspace.list OK

If cmux is installed but its socket isn't reachable, setup stops and tells you — it won't silently start a bridge that can't mirror. To skip cmux entirely and run hook/phone/Codex sessions only: cmux-iphone setup --launchd.

Manage it with the CLI:

Install — the iPhone / Watch app (build it yourself)

There is no App Store / TestFlight build — Cmux iPhone is distributed as source and you build it with your own free Apple ID. (TestFlight requires a paid Apple Developer Program; a public binary may come later if the project enrolls.)

1. Set your bundle id (one command — no XcodeGen needed; the iPhone id, the Watch id, and the Watch's companion id all derive from it):

./scripts/configure-ios.sh com.yourname.cmuxiphone
open ios/CmuxiPhone/CmuxiPhone.xcodeproj

2. Add your Apple ID to Xcode: Xcode → Settings → Accounts → + → Apple ID (a free account works).

3. Set the Team on BOTH targets: select the project → for CmuxiPhone and CmuxiPhoneWatch, Signing & Capabilities → Automatically manage signing → Team = your Personal Team. (The bundle ids are already set by step 1.)

4. Enable Developer Mode on the iPhone (iOS 16+): Settings → Privacy & Security → Developer Mode → On → restart. (Do the same on the Watch if deploying to it: Watch app / watchOS Settings → Privacy & Security.)

5. Run: plug in your iPhone (with the Watch paired), pick the CmuxiPhone scheme + your iPhone as the destination → Run (⌘R). For the Watch app, pick the CmuxiPhoneWatch scheme and the paired-Watch destination (deploy via the iPhone if direct watch install fails).

6. Trust the developer cert: on the iPhone, Settings → General → VPN & Device Management → tap your developer profile → Trust.

Free-team limits: the app expires ~7 days after building (re-run from Xcode to refresh), no push notifications (local notifications only), max 3 devices. SideStore/AltStore can auto-refresh the iPhone app wirelessly.

Maintainers: the project is generated from project.yml with xcodegen — only needed if you change the project structure; end users use the script above.

Pair

1. Open the app → enter the pairing code (see below) + the Mac's address (cmux-iphone status shows the LAN and Tailscale addresses).
2. Same Wi-Fi → the bridge is also auto-discovered (Bonjour), so you can skip typing the address. Across networks, use the Tailscale address so the same pairing works whether you're in the office or away.

Each device gets its own token; revoke any of them with cmux-iphone pair --revoke <id> (see cmux-iphone pair --list).

Where do I get the pairing code?

You don't need to be a developer — it's two commands at most:

• At install, cmux-iphone setup prints your code (and the addresses) at the end. It generates one stable code per Mac and saves it — it does not keep changing, so you can reuse it.
• Anytime later, run cmux-iphone pair to show it again.

$ cmux-iphone pair
Pairing code: 000000
Enter this code in the Cmux iPhone app on your iPhone.

Choose your own code (optional): set CMUX_IPHONE_PAIR_CODE=123456 in the bridge's environment to pin a memorable code. The code is the pairing gate (rate-limited — 5 tries per 5 min — and each device still gets its own token), so keep it private. Trusted LAN or Tailscale use is recommended; do not expose the bridge directly to the public internet.

Rotating code (optional): prefer a code that rotates over a fixed one? Run cmux-iphone setup --rotating — a fresh 6-digit code each restart (24h TTL, cleared once a device pairs) instead of the stable per-Mac default.

Watch approvals (beta): the Watch shows approvals but you answer them on the iPhone for now.

Remote access over Tailscale

The bridge speaks plain HTTP and is built for your LAN or a private Tailscale tailnet — never the open internet. Tailscale lets your iPhone reach your Mac from anywhere, as if they were on the same Wi-Fi.

1. Install Tailscale on both devices, same account.

brew install --cask tailscale     # Mac (or download the app), then sign in

On the iPhone, install Tailscale from the App Store and sign in with the same account. Both devices now share one private tailnet.

2. Find your Mac's Tailscale address.

cmux-iphone status
# Tailscale: http://100.x.y.z:7860

100.x.y.z is your Mac's tailnet IP. With MagicDNS enabled (Tailscale admin console) you can use the Mac's hostname instead (e.g. your-mac).

3. Pair the phone with that address. Bonjour auto-discovery only works on the same Wi-Fi and does not cross the tailnet, so for remote access enter the address by hand: in the app tap Enter IP manually, type the 100.x.y.z (or MagicDNS hostname) + your pairing code (cmux-iphone pair). The same pairing then works on Wi-Fi, cellular, or anywhere your tailnet reaches — no re-pairing.

4. Exposing the bridge (it is loopback-only by default). For safety the bridge binds 127.0.0.1 out of the box, so a fresh install is never reachable over plaintext HTTP by anyone else on your network — and your phone can't reach it yet. Pick how to expose it:

cmux-iphone setup --bind 100.x.y.z     # Tailscale IP — encrypted, recommended
cmux-iphone setup --lan                # entire LAN — plaintext, trusted networks only

Both persist bindAddress to config.json and restart the bridge. (The HOST env var only affects a bridge you launch by hand — the managed launchd/cmux service does not inherit it, so use setup --bind or edit config.json for the installed bridge.)

Re-run cmux-iphone status to confirm the bound address, and keep the Mac awake for remote use: sudo pmset -a sleep 0 && sudo pmset -a disablesleep 1.

Multiple Macs on the road? See REMOTE-SETUP.md for naming each Mac (office-mac-1, …) and switching between them in the app.

Troubleshooting

Run cmux-iphone doctor first — it prints a PASS/WARN/FAIL report (no secrets) that's ideal to paste into an issue.

• iPhone "Connection failed": run cmux-iphone status to get the bridge's actual address + port (it may bind another port in 7860–7869, or a non-loopback interface), then probe /health there — e.g. curl http://<addr>:<port>/health (note: /status requires auth). Bridge + phone must share the LAN (or Tailscale).
• No cmux workspaces: cmux only mirrors when the bridge runs inside cmux (cmux-iphone status shows the runner). Without cmux you still get hook sessions.
• Watch/phone can't find the bridge (Bonjour): check, in order — the app's iOS Local Network permission; both devices on the same network; the router's AP / client isolation is off; mDNS isn't blocked; then fall back to entering the IP manually (from cmux-iphone status).
• Permission prompts don't appear: confirm hooks in ~/.claude/settings.json and that a device is paired (cmux-iphone pair --list).

How it works

Event flow (Mac → phone)

Claude Code runs a tool → a PostToolUse/PreToolUse hook POSTs to the bridge → the bridge pushes an SSE event → the app renders it.

Permission flow (Mac → phone → Mac)

Claude hits a permission prompt → the PermissionRequest hook blocks → the bridge pushes a permission-request SSE event → the phone shows the options → your choice is POSTed back → the bridge returns the decision to Claude. (For codex exec-approvals, the bridge types the answer into the pinned cmux terminal, guarded by a screen hash — it refuses if the screen changed.)

Hooks installed (loopback listener, secret-gated): PostToolUse, PreToolUse, PermissionRequest (blocking, up to 10 min), SessionStart, SessionEnd, Stop, error events.

Security

By default the bridge listens on 127.0.0.1:<port> (loopback-only); exposing it to your phone is an explicit opt-in via bindAddress / the HOST env / setup --lan (prefer a Tailscale IP — encrypted). Requests carrying a foreign Host header are rejected (DNS-rebinding defense). Auth is the pairing code + per-device token; the hook listener is loopback-only and secret-gated. Secrets live outside the repo at 0600. Trusted LAN or Tailscale use is recommended — do not expose the bridge directly to the public internet. Full model + reporting in SECURITY.md.

License

MIT — see LICENSE.

Cmux iPhone is a fork of shobhit99/claude-watch (MIT); original-author copyright is preserved. The app ships neutral icons — no Claude/Anthropic or OpenAI/Codex logo assets are bundled; "Claude" and "Codex" are trademarks of Anthropic and OpenAI respectively, used only as text labels. This is an independent community tool, not affiliated with or endorsed by Anthropic or OpenAI. See NOTICE.md for full attribution.