wristcode/README.md

WristCode

An Apple Watch client for T3 Code. Browse threads across every T3 Code environment you run, reply by dictation, start new threads, and get a notification when an agent finishes. It works over the watch's own cellular connection, with no phone nearby.

Early work in progress.

How it fits together

watchOS only allows WebSockets for audio streaming apps, and T3 Code clients talk to their server over a WebSocket. So the watch talks HTTPS to a small gateway, and the gateway talks to each T3 Code server.

Apple Watch  --HTTPS-->  gateway  --WebSocket-->  T3 Code server (one per environment)
                            |
                            +--APNs-->  notifications on the watch

• gateway/ is the gateway: Bun and TypeScript, shipped as a container image.
• watch/ is the watchOS app: SwiftUI, watch only, no iPhone companion.
• docs/ holds the design notes and the T3 Code protocol reference.
• mocks/ holds static UI mocks of the watch screens.

Running the gateway

The gateway is one container with one SQLite file in /data. It runs under rootless podman on junior.gib, the VPS. deploy/compose.yml is a copy of that stack, and gateway/Containerfile builds the image. CI builds and deploys every push to main that touches gateway/.

Operators use the wristcode CLI inside the container, on junior.gib:

# Connect a T3 Code server. Make the one-time credential on that server first:
t3 auth pairing create --scope orchestration:read --scope orchestration:operate --label "WristCode gateway"
podman exec -it wristcode-gateway wristcode host add https://t3mac.gbrown.org <credential> --label "Mac mini"

# A host reachable more than one way, such as a laptop with a VPN route, lists fallbacks.
# The gateway tries them in order when the first does not answer.
podman exec -it wristcode-gateway wristcode host add https://t3laptop.gbrown.org <credential> --label "Laptop" --alt-url https://t3laptopvpn.gbrown.org

# Pair a watch: enter the printed code on the watch within 5 minutes.
podman exec -it wristcode-gateway wristcode pair

podman exec -it wristcode-gateway wristcode host list
podman exec -it wristcode-gateway wristcode device list
podman exec -it wristcode-gateway wristcode device revoke <id or name>

The gateway exchanges the credential for a 30 day T3 session limited to reading and driving threads, so the long-lived token never leaves the gateway. T3 sessions cannot be refreshed. A week before one expires, the watch gets a notification. scripts/renew-hosts.sh renews every host in one go over SSH, passing each one-time credential straight to the gateway without printing it. Edit its host list to match your machines.

For local development, run bun --watch src/main.ts in gateway/ with WRISTCODE_DB pointing at a scratch file. Without APNs settings, pushes are logged instead of sent.

License

MIT