Companion apps for the operator loop

Install and update path

Android installation checklist

1. Join the private Play internal-testing track for the phone app and the Wear app.
2. Install or update the phone companion from Play first.
3. Install or update the Wear app from the paired watch flow, Play on-device, or a deliberate ADB QA install.
4. Open phone Settings → Watch App, tap Send to watch, then use watch Settings → Import from phone if the watch has not imported the profile automatically.
5. If the watch looks stale after a token or endpoint rotation, use phone Reset watch sync state and watch Refresh complications.

For a fast daemon connection, an Android caco://connect deep link opens the phone companion straight into a one-command daemon connect instead of entering the endpoint and token in connection settings by hand.

Architecture

Three tiers, with no changes to the daemon.

• Daemon host: the existing REST API, SSE stream and audio endpoints. An optional ttyd bridge exposes caco choices tui over WebSocket for the phone's WebView.
• Phone app: an SSE subscriber with a native choices list, the ttyd WebView and the watch relay; spawn-agent and quick-file dialogs, widgets and agent detail share one Compose chrome.
• Watch app: a structured-data client. A grouped Home menu leads to native screens for status, inbox, chat, choices, beads, agents, nodes, projects, files, logs, releases and more, each with drill-downs and watch-side actions; the crown or rotary input navigates choices, and it can probe a daemon directly as well as through the phone.

ttyd Bridge Setup

The ttyd bridge is optional but enables the full caco choices tui experience in a phone WebView.

Prerequisites

Install ttyd from a package manager you trust:

# macOS
brew install ttyd

# NixOS / nix-env
nix-env -iA nixpkgs.ttyd

# Debian/Ubuntu
sudo apt install ttyd

Avoid copy/pasting unpinned source builds that install directly into system paths for routine setup. If you must build ttyd yourself, pin a release tag or commit and verify the upstream release before installing.

Quick Start

# Start the ttyd bridge (uses the convenience command)
caco choices serve-ttyd

# Custom local-only port
caco choices serve-ttyd --port 8080 --bind 127.0.0.1

# Read-only mode (recommended unless you need phone input)
caco choices serve-ttyd --writable false

CLI Reference

The ttyd bridge is stateless — all choice state lives in the daemon. Restart freely without data loss.

Manual ttyd Setup

Alternatively, run ttyd directly:

ttyd --port 7682 --interface 127.0.0.1 caco choices tui

Phone App

Platforms

• iOS — Swift/SwiftUI, requires iOS 17+
• Android — Kotlin/Compose, requires Android 13+ (API 33)

Features

Connection Setup

1. Open the companion app on your phone
2. Go to Settings
3. Enter the daemon host, port (default 11100, the daemon API rather than caco-web's 11180 or ttyd's 7680/7681) and bearer token, or scan a connection QR code
4. Tap Connect

Connection QR codes carry {"host":…,"port":11100,"token":…} as JSON or as a caco://connect?host=…&port=…&token=… URL; both apps accept either.

The bearer token at $CACOPHONY_DIR/tokens/node.token grants broad local daemon access. Enter it only on devices you trust, keep it out of screenshots and shared notes, and rotate it if the phone is lost. Narrower companion-scoped tokens are not available yet.

Network Requirements

The phone must be on the same network (LAN or VPN) as the daemon host. The daemon is not exposed to the internet.

Watch App

Platforms

• watchOS — SwiftUI, requires watchOS 10+
• Wear OS — Compose for Wear, requires Wear OS 4+

Features

Interaction

• Digital crown (watchOS) / Rotary input (Wear OS) — Scroll through options with haptic clicks
• Tap — Select the highlighted option, brief confirmation animation
• Voice reply — For freeform choices, dictate via on-device speech recognition
• Notification actions — Resolve directly from the notification without opening the app

Connectivity

The Apple Watch now has two explicit connection modes:

Relay via iPhone (default): Watch ←→ Phone ←→ Daemon
Direct Wi-Fi (in progress): Watch ←→ Daemon

• Relay via iPhone remains the safe default. Existing Choices, Inbox, Agents, Beads, Feed, Status, voice, and nudge surfaces continue to use WatchConnectivity unless a direct-mode slice has explicitly moved that call path.
• Direct Wi-Fi is visible in the watch Connection Mode screen, Status, About, and Home. The watch can store direct host/port plus bearer-token credentials in local storage/Keychain, and the iPhone can hand off a saved local bearer-token connection to the watch. Direct mTLS/cert-pull, direct daemon networking, and direct action parity are separate tracked slices.
• Security — direct bearer tokens are saved in the watch Keychain and are not displayed after save. Future certificate material must follow the same Keychain/non-plaintext rule.

Offline and stale-state behavior

• Phone disconnected — Relay mode shows a phone-disconnected indicator and keeps restored cached state visible where available.
• Phone reachable, daemon disconnected — Relay replies include daemon connectivity metadata so watch empty-states can distinguish "Phone's daemon disconnected" from genuinely empty lists.
• Direct cached state — Direct mode surfaces cached/restored state with cache age on Home and Choices. The direct-mode validation harness includes mock scenarios for relay populated, phone disconnected, daemon disconnected, direct shell populated, and direct cached/offline shell.
• Limitations today — direct bearer-token setup and iPhone handoff exist, but full direct Choices/Inbox/Agents/Beads/Feed networking, mTLS/cert-pull, and direct watch-to-agent actions land through their own beads. Do not treat Direct mode as production-complete until those slices are merged and validated.

Daemon API Surface

The companion app consumes these existing endpoints (no daemon changes required):

Project Structure

companion/
├── ios/
│   ├── CacophonyCompanion/          # Phone app (SwiftUI)
│   │   └── Sources/
│   │       ├── App/                 # App entry point
│   │       ├── Connection/          # Daemon SSE + REST client
│   │       ├── Choices/             # Choices data model + views
│   │       ├── WebView/             # ttyd WKWebView surface
│   │       └── WatchRelay/          # WatchConnectivity bridge
│   └── CacophonyCompanionWatch/     # Watch app (SwiftUI)
│       └── Sources/
│           ├── App/                 # Watch app + state manager
│           ├── Views/               # Choices + idle views
│           ├── Notifications/       # Actionable notifications
│           └── Complications/       # Complication widget
└── android/
    ├── app/                         # Phone app (Kotlin/Compose)
    │   └── src/
    │       ├── main/java/.../
    │       │   ├── connection/      # SSE + REST client (ConnectionManager)
    │       │   ├── choices/         # Choices data model (ChoicesStore)
    │       │   ├── notifications/   # Android notification channels + builders
    │       │   ├── relay/           # Wear Data Layer bridge (WearRelay)
    │       │   ├── state/           # SSE-driven app state (AppStateStore, Models)
    │       │   └── ui/
    │       │       ├── actions/     # Actions list + execution screen
    │       │       ├── agents/      # Agents fleet list + detail screen
    │       │       ├── beads/       # Beads list + detail screens
    │       │       ├── chat/        # Chat surface with send mode selector
    │       │       ├── choices/     # Choices screen
    │       │       ├── inbox/       # Tabbed inbox (Choices/Messages/Broadcasts/Speech/All)
    │       │       ├── settings/    # Connection + notification settings
    │       │       ├── status/      # Node telemetry + service health dashboard
    │       │       └── theme/       # Nord theme (Compose)
    │       └── test/java/.../       # Unit + E2E tests
    │           ├── ActionsScreenTest
    │           ├── AgentsScreenTest
    │           ├── AppStateStoreTest
    │           ├── ChatScreenTest
    │           ├── DaemonApiE2eTest
    │           ├── FullAppTest
    │           ├── NotificationManagerTest
    │           ├── StatusScreenTest
    │           └── TestDaemonServer
    ├── scripts/
    │   └── test-against-daemon.sh   # Live daemon integration test runner
    └── wearable/                    # Watch app (Compose for Wear)
        └── src/main/java/.../
            ├── choices/             # Watch choices view
            └── tiles/               # Wear OS tile layout

Security

• Bearer token stored in phone's secure storage only (Keychain / EncryptedSharedPreferences)
• Token never transmitted to or stored on the watch
• All daemon communication over LAN/VPN (not exposed to internet)
• Watch delegates all authenticated requests through the phone