Skip to content

armgit / chums

Public Imported from GitHub
0

Talk to Claude Code and Codex agents from an Apple Watch and an iPhone. Each agent is a character on the watch.

9.5 KB
Raw Blame
#!/bin/zsh
# Build Chums (signed) and install it straight onto the Apple Watch, then launch it; the iPhone app too, when Xcode
# knows the iPhone. Run it again to update the app,
# after the hub's token or public address changed, and within 7 days when you sign with a free Personal Team.
# Needs: the watch known to Xcode (xcrun devicectl list devices), Developer Mode on the watch, an Apple ID in Xcode.
# Settings (environment or ~/.chums/config.json): CHUMS_TEAM / "team", CHUMS_BUNDLE / "bundleId". See tools/common.zsh.
# What each error means and how to fix it: docs/troubleshooting.md.
set -e
ROOT="${0:A:h:h}"
source "$ROOT/tools/common.zsh"
chums_help "$@"
: ${DEVELOPER_DIR:=/Applications/Xcode.app/Contents/Developer}; export DEVELOPER_DIR
[[ -d $DEVELOPER_DIR ]] || chums_die "Xcode not found at $DEVELOPER_DIR. Install Xcode 26 or later, or set DEVELOPER_DIR."
chums_need xcodegen "Install it with: brew install xcodegen"
chums_need_config

# The watch first: the build takes minutes, and without a watch there is nothing to install it on.
JSON=$(mktemp)
xcrun devicectl list devices --json-output "$JSON" >/dev/null 2>&1 || true
IFS=$'\t' read -r WATCH WNAME WDEV < <(python3 -c '
import json, sys
try: devices = json.load(open(sys.argv[1]))["result"]["devices"]
except Exception: devices = []
for d in devices:
    if d.get("hardwareProperties", {}).get("platform") == "watchOS":
        p = d.get("deviceProperties", {})
        print(d["identifier"], p.get("name", "Apple Watch"), p.get("developerModeStatus", ""), sep="\t"); break' "$JSON") || true
# The iPhone app (the agents, their conversations, the widgets and the Talk control) goes on the iPhone, if Xcode has it.
IFS=$'\t' read -r PHONE PNAME PDEV < <(python3 -c '
import json, sys
try: devices = json.load(open(sys.argv[1]))["result"]["devices"]
except Exception: devices = []
for d in devices:
    p, c = d.get("deviceProperties", {}), d.get("connectionProperties", {})
    if d.get("hardwareProperties", {}).get("platform") == "iOS" and c.get("pairingState") == "paired" and c.get("tunnelState") != "unavailable":
        print(d["identifier"], p.get("name", "iPhone"), p.get("developerModeStatus", ""), sep="\t"); break' "$JSON") || true
rm -f "$JSON"
if [[ -z "$WATCH" ]]; then
  echo "Xcode doesn't know any Apple Watch yet. The first time:"
  echo "  1. Connect the paired iPhone to this Mac with a USB cable, unlock it and tap Trust."
  echo "  2. Keep the watch unlocked, near the iPhone, on the same Wi-Fi as the Mac."
  echo "  3. Open Xcode › Window › Devices and Simulators and wait until the watch is listed."
  echo "Then run this again. Details: docs/setup.md, \"Connect the iPhone and the watch to Xcode\"."
  exit 1
fi
# "unknown": Xcode can't reach the watch right now to ask (asleep, or the iPhone off USB); the install says if it fails
[[ $WDEV == unknown ]] && echo "Xcode can't read $WNAME's Developer Mode right now: trying anyway (keep the watch unlocked and awake)."
if [[ -n "$WDEV" && "$WDEV" != enabled && "$WDEV" != unknown ]]; then
  echo "$WNAME has Developer Mode $WDEV. On the watch: Settings › Privacy & Security › Developer Mode, turn it on,"
  echo "restart the watch when it asks, then unlock it and confirm Turn On. Then run this again."
  echo "No switch there? docs/setup.md, \"Turn on Developer Mode\"."
  exit 1
fi
echo "Watch: $WNAME"

"$ROOT/tools/gen-config.sh"
cd "$ROOT/app"
mkdir -p build && chmod 700 build                 # the built apps hold the watch token: readable by you only

# Sign with a paid team if Xcode has one, else your free Personal Team (installs expire after 7 days).
: ${CHUMS_TEAM:=$(chums_cfg team)}; export CHUMS_TEAM
KINDF=$(mktemp)                                   # pick-team.py says "free" on stderr for a free Personal Team
TEAM=$(python3 "$ROOT/tools/pick-team.py" 2>"$KINDF") || TEAM=""
KIND=$(cat "$KINDF" 2>/dev/null); rm -f "$KINDF"
if [[ -z "$TEAM" ]]; then
  echo "No developer team can sign: Xcode lists no team for any Apple ID."
  echo "Add an Apple ID in Xcode › Settings › Apple Accounts › + › Apple ID. Any Apple ID has a free Personal Team that"
  echo "can install Chums on your own devices (installs last 7 days)."
  echo "(A paid team also lists nothing while Apple converts a membership, e.g. from individual to organization.)"
  echo "Then run this again. (Or: CHUMS_TEAM=<team ID> bin/chums-install)"
  exit 1
fi
# a bundle ID belongs to the team that registered it first, so the default one carries the team's ID; set CHUMS_BUNDLE
# (or "bundleId" in ~/.chums/config.json) to keep one you already registered
: ${CHUMS_BUNDLE:=$(chums_cfg bundleId)}
: ${CHUMS_BUNDLE:=dev.chums.${TEAM:l}}
export CHUMS_BUNDLE CHUMS_TEAM=$TEAM
xcodegen generate --quiet
echo "Signing with team $TEAM as $CHUMS_BUNDLE"
[[ "$KIND" == free ]] && echo "(a free Personal Team: this install expires on $(date -v+7d '+%Y-%m-%d'); run bin/chums-install again before then)"
# -target (not -scheme): scheme builds demand the multi-GB watchOS platform download; target builds don't.
# Release: the characters do real per-frame maths (the tube is lit and sliced live); Debug Swift is ~15× slower.
echo "Building (a few minutes the first time)…"
LOG=$(mktemp)
xcodebuild -project Chums.xcodeproj -target Chums -configuration Release DEVELOPMENT_TEAM="$TEAM" \
  -allowProvisioningUpdates -allowProvisioningDeviceRegistration SYMROOT="$PWD/build/sym" build > "$LOG" 2>&1 || true
grep -E "error:|BUILD" "$LOG" | sort -u | head -8
if ! grep -q "BUILD SUCCEEDED" "$LOG"; then
  if grep -q "No Account for Team" "$LOG"; then
    echo "Xcode isn't signed in to the Apple ID for team $TEAM. Xcode › Settings › Apple Accounts › + › Apple ID, sign in, then run this again."
    echo "Any Apple ID works: a free one gets a Personal Team that can install on your own devices."
  elif grep -qi "has no devices" "$LOG"; then
    echo "Team $TEAM has no registered devices yet. Xcode registers a device the first time you run an app on it:"
    echo "  1. open $ROOT/app/Chums.xcodeproj"
    echo "  2. choose the Chums scheme and your iPhone as the destination, press Run (⌘R)"
    echo "  3. choose the ChumsWatch scheme and your watch as the destination, press Run"
    echo "Then run bin/chums-install again. Details: docs/troubleshooting.md, \"Your team has no devices\"."
  elif grep -qi "cannot be registered to your development team" "$LOG"; then
    echo "The bundle ID $CHUMS_BUNDLE belongs to another team. Pick one of your own: \"bundleId\": \"com.<you>.chums\" in"
    echo "~/.chums/config.json (or CHUMS_BUNDLE=…), then run this again."
  elif grep -qi "App ID limit" "$LOG"; then
    echo "A free Personal Team can register 10 App IDs in 7 days, and each new bundle ID uses 4 (the iPhone app, its"
    echo "widgets, the watch app, the watch's widget)."
    echo "Wait for the oldest to expire, and keep one bundle ID from then on (\"bundleId\" in ~/.chums/config.json)."
  elif grep -qi "license" "$LOG" && grep -qi "agree" "$LOG"; then
    echo "Xcode's license hasn't been accepted: open Xcode once, or run sudo xcodebuild -license accept. Then run this again."
  fi
  echo "Build failed; full log: $LOG"
  echo "Known errors and their fixes: docs/troubleshooting.md"
  exit 1
fi

ILOG=$(mktemp)
# The wireless connection to the watch often drops the first attempt or two; retry.
for i in 1 2 3 4 5; do
  xcrun devicectl device install app --device "$WATCH" build/sym/Release-watchos/ChumsWatch.app > "$ILOG" 2>&1 && break
  why=$(grep -m1 -o 'ERROR: [^(]*' "$ILOG" || tail -1 "$ILOG")
  if grep -q "IXErrorDomain error 48" "$ILOG"; then tip="the iPhone is installing Chums on the watch itself: unlock the watch and wait for it"
  elif grep -qi "locked" "$ILOG"; then tip="unlock the watch"
  elif grep -qi "disk image" "$ILOG"; then tip="unlock the watch and let Xcode finish preparing it (Window › Devices and Simulators)"
  else tip="keep the watch unlocked, awake and near the iPhone"; fi
  echo "install attempt $i failed ($why); $tip"
  if [[ $i == 5 ]]; then echo "Full log: $ILOG. Known errors and their fixes: docs/troubleshooting.md"; WATCH_FAILED=1; break; fi
  sleep 6
done
if [[ -n "$WATCH_FAILED" ]]; then
  :
elif xcrun devicectl device process launch --device "$WATCH" "$CHUMS_BUNDLE.watchkitapp" > "$ILOG" 2>&1; then
  echo "Chums is running on the watch."
else
  echo "Chums is installed, but it didn't open ($(grep -m1 -o 'ERROR: [^(]*' "$ILOG" || tail -1 "$ILOG"))."
  grep -qi "locked" "$ILOG" && echo "The watch was locked: unlock it and open Chums from its app list."
fi
# Then the iPhone app. (It carries the watch app too: installed after the watch has it, the iPhone has nothing to send.)
if [[ -z "$PHONE" ]]; then
  echo "No iPhone known to Xcode: skipping the iPhone app (connect the iPhone by USB once, then run this again)."
elif [[ -n "$PDEV" && "$PDEV" != enabled && "$PDEV" != unknown ]]; then
  echo "$PNAME has Developer Mode $PDEV: skipping the iPhone app. On the iPhone: Settings › Privacy & Security ›"
  echo "Developer Mode, turn it on, restart, confirm Turn On. Then run this again."
else
  for i in 1 2 3; do
    if xcrun devicectl device install app --device "$PHONE" build/sym/Release-iphoneos/Chums.app > "$ILOG" 2>&1; then
      echo "Chums is installed on $PNAME."; break
    fi
    echo "iPhone install attempt $i failed ($(grep -m1 -o 'ERROR: [^(]*' "$ILOG" || tail -1 "$ILOG")); unlock the iPhone"
    [[ $i == 3 ]] && { echo "The iPhone app didn't install. Full log: $ILOG"; PHONE_FAILED=1 }
    sleep 4
  done
fi

[[ -n "$WATCH_FAILED" || -n "${PHONE_FAILED:-}" ]] && exit 1
echo "Next: start the agents (bin/chums-agents install; docs/setup.md, step 10), and check the whole chain with bin/chums-doctor."