How govijr/terminal-phone works
terminal-phone is a macOS terminal interface for viewing and interacting with iOS simulators and paired iPhones, with agent control, app workflows, and media export. The main path is CLI selection/setup → phone connection → interactive viewer and rendering; agents can observe and act through CLI or MCP, while flow, run, logging, and App Store media features provide adjacent workflows. Some agent and feature implementations were not excerpted, so their documented capabilities are shown without speculative internal call chains.
Main entry points: PhoneCLI.swift Command dispatcher · PhoneViewer.swift Interactive viewer · PhoneRenderer.swift Terminal graphics · PhoneLiveSession.swift Simulator live link
Components 29
CLI and terminal
- Command dispatcher
Sources/TerminalPhone/PhoneCLI.swift - Terminal splits
Sources/TerminalPhone/TerminalSplit.swift - Interactive viewer
Sources/TerminalPhone/PhoneViewer.swift - Terminal graphics
Sources/TerminalPhone/PhoneRenderer.swift - Terminal profile
Sources/TerminalUI/TerminalProfile.swift - Terminal writer
Sources/TerminalUI/TerminalWriter.swift
Phone runtime
- Phone settings
Sources/TerminalPhoneCore/Simulator.swift - Simulator control
Sources/TerminalPhoneCore/Simulator.swift - iPhone discovery
Sources/TerminalPhone/PhoneDevices.swift - WebDriverAgent client
Sources/TerminalPhone/WebDriverAgent.swift - Simulator live link
Sources/TerminalPhone/PhoneLiveSession.swift - iPhone live link
Sources/TerminalPhone/DeviceLiveSession.swift - Simulator companion
Sources/TerminalPhone/PhoneCompanion.swift - Viewer worker
resources/phone-viewer-worker.py
Agent control
- Agent CLI commands
Sources/TerminalPhone/PhoneCLI+Agent.swift - MCP server
Sources/TerminalPhone/PhoneMCPServer.swift - Agent host
Sources/TerminalPhone/PhoneAgentHost.swift - Agent sessions
Sources/TerminalPhoneCore/PhoneAgentSession.swift - Agent transport
Sources/TerminalPhoneCore/PhoneAgentTransport.swift - Simulator agent link
Sources/TerminalPhone/SimulatorAgentConnection.swift - Agent worker
resources/phone-agent-worker.py
App workflows
- Flow execution
Sources/TerminalPhoneCore/PhoneFlow.swift - Action history
Sources/TerminalPhoneCore/PhoneActionLog.swift - Build and launch
Sources/TerminalPhone/PhoneCLI+Run.swift - Recording
Sources/TerminalPhone/PhoneRecording.swift - App Store media
Sources/TerminalPhone/PhoneMediaExport.swift - Media formatting
Sources/TerminalPhoneCore/AppStoreMedia.swift - App log tail
Sources/TerminalPhone/PhoneLogTail.swift
Other components
- User or agent
Connections 30
- User or agent → Command dispatcher: runs commands
README.md - Command dispatcher → Phone settings: loads phone
Sources/TerminalPhone/PhoneCLI.swift - Command dispatcher → Simulator control: boots simulator
Sources/TerminalPhone/PhoneCLI.swift - Command dispatcher → iPhone discovery: lists devices
Sources/TerminalPhone/PhoneCLI.swift - Command dispatcher → Interactive viewer: opens viewer
Sources/TerminalPhone/PhoneCLI.swift - Command dispatcher → Terminal splits: opens split
README.md - Interactive viewer → Terminal graphics: renders frames
Sources/TerminalPhone/PhoneViewer.swift - Terminal graphics → Terminal profile: selects protocol
Sources/TerminalPhone/PhoneRenderer.swift - Terminal graphics → Terminal writer: writes graphics
Sources/TerminalPhone/PhoneRenderer.swift - Interactive viewer → Simulator live link: streams simulator
Sources/TerminalPhone/PhoneViewer.swift - Interactive viewer → iPhone live link: streams iPhone
Sources/TerminalPhone/PhoneViewer.swift - Simulator live link → Simulator companion: opens socket
Sources/TerminalPhone/PhoneLiveSession.swift - Simulator live link → Viewer worker: starts worker
Sources/TerminalPhone/PhoneLiveSession.swift - iPhone live link → WebDriverAgent client: sends device input
Sources/TerminalPhone/DeviceLiveSession.swift - iPhone discovery → WebDriverAgent client: connects client
Sources/TerminalPhone/PhoneDevices.swift - User or agent → Agent CLI commands: requests agent actions
README.md - Command dispatcher → Agent host: starts agent host
Sources/TerminalPhone/PhoneCLI.swift - Agent CLI commands → Agent sessions: runs observe act
- MCP server → Agent host: dispatches tools
- Agent host → Agent transport: uses transport
- Agent sessions → Simulator agent link: controls simulator
- Simulator agent link → Agent worker: starts worker
Sources/TerminalPhone/SimulatorAgentConnection.swift - Command dispatcher → Flow execution: runs flow tests
README.md - Flow execution → Action history: records actions
Sources/TerminalPhoneCore/PhoneFlow.swift - Command dispatcher → Build and launch: builds and launches
README.md - Command dispatcher → Recording: records session
README.md - Recording → Action history: logs input
Sources/TerminalPhone/PhoneRecording.swift - Command dispatcher → App Store media: exports media
README.md - App Store media → Media formatting: formats exports
Sources/TerminalPhone/PhoneMediaExport.swift - Command dispatcher → App log tail: shows app logs
README.md