# govijr/terminal-phone architecture

> Architecture diagram of the GitHub repository govijr/terminal-phone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/govijr/terminal-phone
- Repository: https://github.com/govijr/terminal-phone

## Overview

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: [`Sources/TerminalPhone/PhoneCLI.swift`](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneCLI.swift) (Command dispatcher), [`Sources/TerminalPhone/PhoneViewer.swift`](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneViewer.swift) (Interactive viewer), [`Sources/TerminalPhone/PhoneRenderer.swift`](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneRenderer.swift) (Terminal graphics), [`Sources/TerminalPhone/PhoneLiveSession.swift`](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneLiveSession.swift) (Simulator live link)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and terminal"]
  node_cli["Command dispatcher<br/>[PhoneCLI.swift]"]
  node_split["Terminal splits"]
  node_viewer["Interactive viewer<br/>[PhoneViewer.swift]"]
  node_terminal["Terminal graphics"]
  node_profile["Terminal profile"]
  node_writer["Terminal writer"]
end

subgraph group_devices["Phone runtime"]
  node_store[("Phone settings<br/>[Simulator.swift]")]
  node_simulator["Simulator control<br/>[Simulator.swift]"]
  node_device["iPhone discovery<br/>[PhoneDevices.swift]"]
  node_wda["WebDriverAgent client"]
  node_simlink["Simulator live link"]
  node_devicelink["iPhone live link"]
  node_companion["Simulator companion"]
  node_viewerworker["Viewer worker"]
end

subgraph group_agents["Agent control"]
  node_agentcli["Agent CLI commands"]
  node_mcp["MCP server"]
  node_agenthost["Agent host"]
  node_agentsession["Agent sessions"]
  node_agenttransport["Agent transport"]
  node_simagent["Simulator agent link"]
  node_agentworker["Agent worker"]
end

subgraph group_workflows["App workflows"]
  node_flow["Flow execution<br/>[PhoneFlow.swift]"]
  node_actionlog[("Action history")]
  node_run["Build and launch<br/>[PhoneCLI+Run.swift]"]
  node_record["Recording"]
  node_media["App Store media"]
  node_appstore["Media formatting"]
  node_logs["App log tail<br/>[PhoneLogTail.swift]"]
end

node_user(("User or agent"))

node_user -->|"runs commands"| node_cli
node_cli -->|"loads phone"| node_store
node_cli -->|"boots simulator"| node_simulator
node_cli -->|"lists devices"| node_device
node_cli -->|"opens viewer"| node_viewer
node_cli -->|"opens split"| node_split
node_viewer -->|"renders frames"| node_terminal
node_terminal -->|"selects protocol"| node_profile
node_terminal -->|"writes graphics"| node_writer
node_viewer -->|"streams simulator"| node_simlink
node_viewer -->|"streams iPhone"| node_devicelink
node_simlink -->|"opens socket"| node_companion
node_simlink -->|"starts worker"| node_viewerworker
node_devicelink -->|"sends device input"| node_wda
node_device -->|"connects client"| node_wda
node_user -->|"requests agent actions"| node_agentcli
node_cli -->|"starts agent host"| node_agenthost
node_agentcli -.->|"runs observe act"| node_agentsession
node_mcp -.->|"dispatches tools"| node_agenthost
node_agenthost -.->|"uses transport"| node_agenttransport
node_agentsession -.->|"controls simulator"| node_simagent
node_simagent -->|"starts worker"| node_agentworker
node_cli -->|"runs flow tests"| node_flow
node_flow -->|"records actions"| node_actionlog
node_cli -->|"builds and launches"| node_run
node_cli -->|"records session"| node_record
node_record -->|"logs input"| node_actionlog
node_cli -->|"exports media"| node_media
node_media -->|"formats exports"| node_appstore
node_cli -->|"shows app logs"| node_logs

click node_cli "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneCLI.swift"
click node_split "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/TerminalSplit.swift"
click node_viewer "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneViewer.swift"
click node_terminal "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneRenderer.swift"
click node_profile "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalUI/TerminalProfile.swift"
click node_writer "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalUI/TerminalWriter.swift"
click node_store "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/Simulator.swift"
click node_simulator "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/Simulator.swift"
click node_device "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneDevices.swift"
click node_wda "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/WebDriverAgent.swift"
click node_simlink "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneLiveSession.swift"
click node_devicelink "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/DeviceLiveSession.swift"
click node_companion "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneCompanion.swift"
click node_agentcli "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneCLI%2BAgent.swift"
click node_mcp "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneMCPServer.swift"
click node_agenthost "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneAgentHost.swift"
click node_agentsession "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/PhoneAgentSession.swift"
click node_agenttransport "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/PhoneAgentTransport.swift"
click node_simagent "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/SimulatorAgentConnection.swift"
click node_flow "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/PhoneFlow.swift"
click node_actionlog "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/PhoneActionLog.swift"
click node_run "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneCLI%2BRun.swift"
click node_record "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneRecording.swift"
click node_media "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneMediaExport.swift"
click node_appstore "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/AppStoreMedia.swift"
click node_logs "https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneLogTail.swift"
click node_viewerworker "https://github.com/govijr/terminal-phone/blob/main/resources/phone-viewer-worker.py"
click node_agentworker "https://github.com/govijr/terminal-phone/blob/main/resources/phone-agent-worker.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_split,node_viewer,node_terminal,node_profile,node_writer,node_user toneBlue
class node_store,node_simulator,node_device,node_wda,node_simlink,node_devicelink,node_companion,node_viewerworker toneAmber
class node_agentcli,node_mcp,node_agenthost,node_agentsession,node_agenttransport,node_simagent,node_agentworker toneMint
class node_flow,node_actionlog,node_run,node_record,node_media,node_appstore,node_logs toneRose
```

## Components

### CLI and terminal

- [Command dispatcher](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneCLI.swift): `Sources/TerminalPhone/PhoneCLI.swift`
- [Terminal splits](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/TerminalSplit.swift): `Sources/TerminalPhone/TerminalSplit.swift`
- [Interactive viewer](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneViewer.swift): `Sources/TerminalPhone/PhoneViewer.swift`
- [Terminal graphics](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneRenderer.swift): `Sources/TerminalPhone/PhoneRenderer.swift`
- [Terminal profile](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalUI/TerminalProfile.swift): `Sources/TerminalUI/TerminalProfile.swift`
- [Terminal writer](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalUI/TerminalWriter.swift): `Sources/TerminalUI/TerminalWriter.swift`

### Phone runtime

- [Phone settings](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/Simulator.swift): `Sources/TerminalPhoneCore/Simulator.swift`
- [Simulator control](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/Simulator.swift): `Sources/TerminalPhoneCore/Simulator.swift`
- [iPhone discovery](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneDevices.swift): `Sources/TerminalPhone/PhoneDevices.swift`
- [WebDriverAgent client](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/WebDriverAgent.swift): `Sources/TerminalPhone/WebDriverAgent.swift`
- [Simulator live link](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneLiveSession.swift): `Sources/TerminalPhone/PhoneLiveSession.swift`
- [iPhone live link](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/DeviceLiveSession.swift): `Sources/TerminalPhone/DeviceLiveSession.swift`
- [Simulator companion](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneCompanion.swift): `Sources/TerminalPhone/PhoneCompanion.swift`
- [Viewer worker](https://github.com/govijr/terminal-phone/blob/main/resources/phone-viewer-worker.py): `resources/phone-viewer-worker.py`

### Agent control

- [Agent CLI commands](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneCLI%2BAgent.swift): `Sources/TerminalPhone/PhoneCLI+Agent.swift`
- [MCP server](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneMCPServer.swift): `Sources/TerminalPhone/PhoneMCPServer.swift`
- [Agent host](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneAgentHost.swift): `Sources/TerminalPhone/PhoneAgentHost.swift`
- [Agent sessions](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/PhoneAgentSession.swift): `Sources/TerminalPhoneCore/PhoneAgentSession.swift`
- [Agent transport](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/PhoneAgentTransport.swift): `Sources/TerminalPhoneCore/PhoneAgentTransport.swift`
- [Simulator agent link](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/SimulatorAgentConnection.swift): `Sources/TerminalPhone/SimulatorAgentConnection.swift`
- [Agent worker](https://github.com/govijr/terminal-phone/blob/main/resources/phone-agent-worker.py): `resources/phone-agent-worker.py`

### App workflows

- [Flow execution](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/PhoneFlow.swift): `Sources/TerminalPhoneCore/PhoneFlow.swift`
- [Action history](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/PhoneActionLog.swift): `Sources/TerminalPhoneCore/PhoneActionLog.swift`
- [Build and launch](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneCLI%2BRun.swift): `Sources/TerminalPhone/PhoneCLI+Run.swift`
- [Recording](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneRecording.swift): `Sources/TerminalPhone/PhoneRecording.swift`
- [App Store media](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneMediaExport.swift): `Sources/TerminalPhone/PhoneMediaExport.swift`
- [Media formatting](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhoneCore/AppStoreMedia.swift): `Sources/TerminalPhoneCore/AppStoreMedia.swift`
- [App log tail](https://github.com/govijr/terminal-phone/blob/main/Sources/TerminalPhone/PhoneLogTail.swift): `Sources/TerminalPhone/PhoneLogTail.swift`

### Other components

- **User or agent**

## Connections

- User or agent → Command dispatcher: runs commands (evidence: `README.md`)
- Command dispatcher → Phone settings: loads phone (evidence: `Sources/TerminalPhone/PhoneCLI.swift`)
- Command dispatcher → Simulator control: boots simulator (evidence: `Sources/TerminalPhone/PhoneCLI.swift`)
- Command dispatcher → iPhone discovery: lists devices (evidence: `Sources/TerminalPhone/PhoneCLI.swift`)
- Command dispatcher → Interactive viewer: opens viewer (evidence: `Sources/TerminalPhone/PhoneCLI.swift`)
- Command dispatcher → Terminal splits: opens split (evidence: `README.md`)
- Interactive viewer → Terminal graphics: renders frames (evidence: `Sources/TerminalPhone/PhoneViewer.swift`)
- Terminal graphics → Terminal profile: selects protocol (evidence: `Sources/TerminalPhone/PhoneRenderer.swift`)
- Terminal graphics → Terminal writer: writes graphics (evidence: `Sources/TerminalPhone/PhoneRenderer.swift`)
- Interactive viewer → Simulator live link: streams simulator (evidence: `Sources/TerminalPhone/PhoneViewer.swift`)
- Interactive viewer → iPhone live link: streams iPhone (evidence: `Sources/TerminalPhone/PhoneViewer.swift`)
- Simulator live link → Simulator companion: opens socket (evidence: `Sources/TerminalPhone/PhoneLiveSession.swift`)
- Simulator live link → Viewer worker: starts worker (evidence: `Sources/TerminalPhone/PhoneLiveSession.swift`)
- iPhone live link → WebDriverAgent client: sends device input (evidence: `Sources/TerminalPhone/DeviceLiveSession.swift`)
- iPhone discovery → WebDriverAgent client: connects client (evidence: `Sources/TerminalPhone/PhoneDevices.swift`)
- User or agent → Agent CLI commands: requests agent actions (evidence: `README.md`)
- Command dispatcher → Agent host: starts agent host (evidence: `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 (evidence: `Sources/TerminalPhone/SimulatorAgentConnection.swift`)
- Command dispatcher → Flow execution: runs flow tests (evidence: `README.md`)
- Flow execution → Action history: records actions (evidence: `Sources/TerminalPhoneCore/PhoneFlow.swift`)
- Command dispatcher → Build and launch: builds and launches (evidence: `README.md`)
- Command dispatcher → Recording: records session (evidence: `README.md`)
- Recording → Action history: logs input (evidence: `Sources/TerminalPhone/PhoneRecording.swift`)
- Command dispatcher → App Store media: exports media (evidence: `README.md`)
- App Store media → Media formatting: formats exports (evidence: `Sources/TerminalPhone/PhoneMediaExport.swift`)
- Command dispatcher → App log tail: shows app logs (evidence: `README.md`)
