Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

7.1 KB
Raw Blame

Harness for iOS and Android

A viewer onto the machines this device has linked — one harness at a time, on a phone.

Start with the mobile team handoff for recent changes, the code map, validation and outstanding product decisions.

flutter pub get
flutter analyze          # 0 issues outside third_party/xterm
env -u TMUX flutter test
flutter run              # -d <your device>
flutter build ios --debug --no-codesign
flutter build apk --debug

Standalone runtime, monorepo tests

harness_mobile is standalone. It used to be a thin shell over path: ../desktop, which meant every desktop-only concern was a phone concern too: the app pulled in window_manager, file_selector, desktop_drop, sqlite3 and go_router, and the phone build was pinned to a Flutter app whose targets are macOS and Linux.

Run the full tests from mobile/ inside this repository: encryption protocol checks read CLI source, and the branch-history UI tests use a desktop font fixture. Automated app interaction uses only the offline sample and simulator; tests must not contact real accounts or daemons.

The app it runs now lives under lib/, in the same folders the desktop app uses for it:

lib/core/ models, config, platform, file store, crash log
lib/state/ AppNotifier — machines, agents, connections, panes, the account's desk
lib/api/, lib/ws/ REST to the backend, and the relay socket per machine
lib/auth/, lib/viewer/ SSO, device linking, and the viewer's stand-ins for the harness CLI
lib/e2ee/ the end-to-end encryption this app terminates itself
lib/terminal/, lib/widgets/ the xterm session, the terminal panel and its chrome
lib/shared/, lib/logging/ design system, file logs
third_party/xterm/ the vendored, patched xterm 4.0.0 (see its README.autonomous.md)

Two folders are this package's own, and have no counterpart on the desktop:

  • lib/phone/ — Focus, Find, New, voice input, approvals, onboarding and settings. PhoneShell owns one navigation stack rooted in AgentHome, with the full-screen terminal in TerminalPage.
  • lib/p2p/ — the phone's second wire to each machine. The terminal-v1 WebRTC data channel the harness CLI opens with werift on the desktop's behalf, so a terminal rides p2p or TURN when it can and the relay only when it must.

lib/demo/ provides the offline sample runtime. test/render/ captures the phone screens; integration_test/tour_test.dart opens SampleApp directly for the simulator walkthrough.

The account’s swarms are the desk’s, here too

The account’s swarms are stored on the backend (/api/desk). lib/state/desk_sync.dart models that shared document; lib/state/phone_desk.dart handles the phone's reads and explicit writes. The phone's swarms are temporary terminal containers for the pager, not a projection of the account’s swarms. Swiping must never rewrite the shared desk.

The phone follows desk updates over machine relay sockets and polls every 15 seconds in the foreground. Creating or deleting a harness updates its desk membership; explicit swarm operations also live in PhoneDesk. The current swarm and position remain device-local. lib/phone/desk_groups.dart resolves the swarm’s harnesses for navigation.

Swarm (Settings ▸ Experimental)

lib/swarm/ brings a Swarm (the desktop's collaborative tab, not the desk groups above) to the phone: what needs the person first (decisions, the Product Manager's tags, work waiting on them), the Swarms and their projects, a project's conversations, posting with @mentions, and decisions answered with one tap. Reads and writes go straight to the backend using the phone's own sign-in (AppNotifier.swarmRequest), so posting and answering decisions work while every account machine is offline. Command retries keep the same operation ID, including after a bearer refresh or a fallback through an account machine (super_tabs, end-to-end encrypted). Writes fall back only when the direct transport or server is unavailable; authentication, access and rate-limit refusals stand. The backend enforces what the signed-in person may read and change. Operations that run on a computer still need that computer, and regular terminals keep their end-to-end encrypted path through the machine. model.dart and parts.dart are copies of the desktop's, held to them by test/swarm/desktop_parity_test.dart.

  • Cost. One SwarmSession per signed-in account while Swarm is on. In the foreground it reads what needs the person every 15 seconds, and an open Swarm's changes (first load, then /changes) every 5 seconds while a screen shows it. In the background it reads nothing.
  • Notices are local only: a foreground read that finds something new posts one while no Swarm screen is open (Home, a terminal). They say who asks and in which project, never the question or the message (swarm_notices.dart), because a locked phone may show them; notices to a closed or backgrounded app need push from the backend.
  • Choices. swarm_choices.dart holds the six UX answers (the way in, the first screen, a project's layout, posting, notices, Undo), each the recommended one until the app's owner decides.

integration_test/swarm_local_review_test.dart walks the real shell's ways in (Settings ▸ Experimental, the mark on Home, Find) and these screens on a simulator against an isolated local backend (fake SSO, in-memory MongoDB and Redis, no daemon), through the app's own Swarm path to a stand-in machine, for review screenshots. It skips without SWARM_LOCAL_BACKEND and reads only 127.0.0.1.

It is a VIEWER build, always

No harness CLI runs beside this app and no agent is ever hosted here. It holds its own SSO session and terminates the E2EE to each machine itself (lib/viewer/, lib/e2ee/) — where the desktop hands both to the CLI on its own computer. kViewerMode (lib/core/viewer_mode.dart) is true on iOS and Android unconditionally, so AppNotifier always has its ViewerServices, and the desktop's side of every branch on that is gone from this package rather than skipped: first-run provisioning, the self-updater (an app the store updates installs nothing), finding and supervising a local harness CLI, signing in through it or a browser, and the grid's presets, splits and keyboard rail.

Keeping in step with ../desktop

Much of lib/ originated in desktop/lib/, but the copies now differ substantially. Mobile removes desktop routing, local CLI supervision and transport, grid controls and local file access. It also owns its authentication, encryption and phone-specific lifecycle handling.

Port shared protocol and model fixes deliberately. Check core/agent_git_context.dart, e2ee/envelope.dart, state/app_state.dart and their regression tests when upstream adds RPCs or agent fields. test/encrypted_down_types_test.dart compares the phone's encryption rules with the CLI's source so a new machine request cannot silently leave unencrypted.

third_party/xterm/ is patched code: preserve its mobile input, rendering and accessibility changes. Never commit local signing edits to ios/Runner.xcodeproj/project.pbxproj.