# awizemann/harness architecture

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

- Interactive diagram: https://gitdiagram.com/awizemann/harness
- Repository: https://github.com/awizemann/harness

## Overview

Harness is a native macOS user-testing tool: a developer configures an app, goal, and persona; Harness launches or builds the target, an AI agent observes and acts across iOS Simulator, macOS, or Web, and the run produces an outcome, replayable action history, and friction report. The GUI and CLI support autonomous runs; the standalone MCP server also exposes autonomous runs and direct, step-level UI sessions. The graph follows README-described capabilities and sampled composition/orchestration seams; several feature implementations are unsampled, so their internal call relationships are omitted.

Main entry points: [`Harness/Domain/RunCoordinator.swift`](https://github.com/awizemann/harness/blob/main/Harness/Domain/RunCoordinator.swift) (Run coordinator), [`Harness/Platforms/PlatformAdapter.swift`](https://github.com/awizemann/harness/blob/main/Harness/Platforms/PlatformAdapter.swift) (Platform adapter), [`Harness/App/HarnessApp.swift`](https://github.com/awizemann/harness/blob/main/Harness/App/HarnessApp.swift) (Harness GUI), [`HarnessMCP/ToolHandlers.swift`](https://github.com/awizemann/harness/blob/main/HarnessMCP/ToolHandlers.swift) (MCP tool handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Setup and authoring"]
  node_desktop["Harness GUI<br/>[HarnessApp.swift]"]
  node_appconfig["App and settings"]
  node_goalpersona["Goal and persona"]
  node_actions["Actions and chains"]
end

subgraph group_runtime["Run runtime"]
  node_container["Dependency container<br/>[AppContainer.swift]"]
  node_runcoord["Run coordinator"]
  node_agentloop["Agent loop<br/>[AgentLoop.swift]"]
  node_tools["Agent tools<br/>[AgentTools.swift]"]
  node_llmfactory["Model client factory"]
  node_llmproviders["LLM providers"]
end

subgraph group_platforms["Target platforms"]
  node_platformfacade["Platform adapter"]
  node_iosdriver["iOS Simulator driver"]
  node_wdastack["WebDriverAgent client<br/>[WDAClient.swift]"]
  node_macdriver["macOS app driver"]
  node_webdriver["Web app driver"]
  node_uisessions["Direct UI sessions"]
end

subgraph group_artifacts["Run artifacts"]
  node_history[("Run history")]
  node_logger["Run logs<br/>[RunLogger.swift]"]
  node_replay["Run replay"]
  node_friction["Friction reports"]
end

subgraph group_interfaces["External interfaces"]
  node_mcp["MCP server<br/>[MCPServer.swift]"]
  node_mcptools["MCP tool handlers<br/>[ToolHandlers.swift]"]
  node_cli["CLI runner"]
end

node_developer(("Developer"))
node_externalagent(("External agent"))
node_targetapp["Test target"]
node_modelservice["Model service"]

node_developer -->|"configures and starts"| node_desktop
node_desktop -.->|"manages targets"| node_appconfig
node_desktop -.->|"submits goal"| node_goalpersona
node_desktop -->|"uses composition root"| node_container
node_container -->|"constructs per-run"| node_runcoord
node_runcoord -->|"orchestrates"| node_agentloop
node_runcoord -->|"prepares and drives"| node_platformfacade
node_agentloop -.->|"issues tool calls"| node_tools
node_container -->|"selects client"| node_llmfactory
node_llmfactory -->|"creates provider client"| node_llmproviders
node_llmproviders -.->|"requests decisions"| node_modelservice
node_platformfacade -->|"dispatches by platform"| node_iosdriver
node_platformfacade -->|"dispatches by platform"| node_macdriver
node_platformfacade -->|"dispatches by platform"| node_webdriver
node_iosdriver -.->|"uses WDA"| node_wdastack
node_iosdriver -->|"drives simulator target"| node_targetapp
node_macdriver -->|"drives macOS target"| node_targetapp
node_webdriver -->|"drives WebKit target"| node_targetapp
node_runcoord -->|"persists run records"| node_history
node_runcoord -->|"appends run events"| node_logger
node_history -.->|"supplies run history"| node_replay
node_history -.->|"supplies run findings"| node_friction
node_externalagent -->|"sends MCP requests"| node_mcp
node_mcp -->|"dispatches tools"| node_mcptools
node_mcptools -->|"reads and updates"| node_history
node_mcptools -->|"starts autonomous runs"| node_runcoord
node_mcptools -.->|"starts UI sessions"| node_uisessions
node_uisessions -->|"prepares platform"| node_platformfacade
node_developer -->|"starts dev runs"| node_cli
node_cli -.->|"runs coordinator"| node_runcoord

click node_desktop "https://github.com/awizemann/harness/blob/main/Harness/App/HarnessApp.swift"
click node_appconfig "https://github.com/awizemann/harness/tree/main/Harness/Features/Applications"
click node_goalpersona "https://github.com/awizemann/harness/tree/main/Harness/Features/GoalInput"
click node_actions "https://github.com/awizemann/harness/tree/main/Harness/Features/Actions"
click node_container "https://github.com/awizemann/harness/blob/main/Harness/App/AppContainer.swift"
click node_runcoord "https://github.com/awizemann/harness/blob/main/Harness/Domain/RunCoordinator.swift"
click node_agentloop "https://github.com/awizemann/harness/blob/main/Harness/Domain/AgentLoop.swift"
click node_tools "https://github.com/awizemann/harness/blob/main/Harness/Tools/AgentTools.swift"
click node_llmfactory "https://github.com/awizemann/harness/blob/main/Harness/Services/LLMClientFactory.swift"
click node_llmproviders "https://github.com/awizemann/harness/tree/main/Harness/Services"
click node_platformfacade "https://github.com/awizemann/harness/blob/main/Harness/Platforms/PlatformAdapter.swift"
click node_iosdriver "https://github.com/awizemann/harness/blob/main/Harness/Platforms/iOS/IOSPlatformAdapter.swift"
click node_wdastack "https://github.com/awizemann/harness/blob/main/Harness/Services/WDAClient.swift"
click node_macdriver "https://github.com/awizemann/harness/blob/main/Harness/Platforms/MacOS/MacOSPlatformAdapter.swift"
click node_webdriver "https://github.com/awizemann/harness/blob/main/Harness/Platforms/Web/WebPlatformAdapter.swift"
click node_uisessions "https://github.com/awizemann/harness/blob/main/Harness/UISessions/UISessionSupervisor.swift"
click node_history "https://github.com/awizemann/harness/blob/main/Harness/Services/RunHistoryStore.swift"
click node_logger "https://github.com/awizemann/harness/blob/main/Harness/Services/RunLogger.swift"
click node_replay "https://github.com/awizemann/harness/tree/main/Harness/Features/RunReplay"
click node_friction "https://github.com/awizemann/harness/tree/main/Harness/Features/FrictionReport"
click node_mcp "https://github.com/awizemann/harness/blob/main/HarnessMCP/MCPServer.swift"
click node_mcptools "https://github.com/awizemann/harness/blob/main/HarnessMCP/ToolHandlers.swift"
click node_cli "https://github.com/awizemann/harness/blob/main/HarnessCLI/HarnessRunner.swift"

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_desktop,node_appconfig,node_goalpersona,node_actions toneBlue
class node_container,node_runcoord,node_agentloop,node_tools,node_llmfactory,node_llmproviders toneAmber
class node_platformfacade,node_iosdriver,node_wdastack,node_macdriver,node_webdriver,node_uisessions toneMint
class node_history,node_logger,node_replay,node_friction toneRose
class node_mcp,node_mcptools,node_cli,node_developer,node_externalagent,node_targetapp,node_modelservice toneIndigo
```

## Components

### Setup and authoring

- [Harness GUI](https://github.com/awizemann/harness/blob/main/Harness/App/HarnessApp.swift): `Harness/App/HarnessApp.swift`
- [App and settings](https://github.com/awizemann/harness/tree/main/Harness/Features/Applications): `Harness/Features/Applications`
- [Goal and persona](https://github.com/awizemann/harness/tree/main/Harness/Features/GoalInput): `Harness/Features/GoalInput`
- [Actions and chains](https://github.com/awizemann/harness/tree/main/Harness/Features/Actions): `Harness/Features/Actions`

### Run runtime

- [Dependency container](https://github.com/awizemann/harness/blob/main/Harness/App/AppContainer.swift): `Harness/App/AppContainer.swift`
- [Run coordinator](https://github.com/awizemann/harness/blob/main/Harness/Domain/RunCoordinator.swift): `Harness/Domain/RunCoordinator.swift`
- [Agent loop](https://github.com/awizemann/harness/blob/main/Harness/Domain/AgentLoop.swift): `Harness/Domain/AgentLoop.swift`
- [Agent tools](https://github.com/awizemann/harness/blob/main/Harness/Tools/AgentTools.swift): `Harness/Tools/AgentTools.swift`
- [Model client factory](https://github.com/awizemann/harness/blob/main/Harness/Services/LLMClientFactory.swift): `Harness/Services/LLMClientFactory.swift`
- [LLM providers](https://github.com/awizemann/harness/tree/main/Harness/Services): `Harness/Services`

### Target platforms

- [Platform adapter](https://github.com/awizemann/harness/blob/main/Harness/Platforms/PlatformAdapter.swift): `Harness/Platforms/PlatformAdapter.swift`
- [iOS Simulator driver](https://github.com/awizemann/harness/blob/main/Harness/Platforms/iOS/IOSPlatformAdapter.swift): `Harness/Platforms/iOS/IOSPlatformAdapter.swift`
- [WebDriverAgent client](https://github.com/awizemann/harness/blob/main/Harness/Services/WDAClient.swift): `Harness/Services/WDAClient.swift`
- [macOS app driver](https://github.com/awizemann/harness/blob/main/Harness/Platforms/MacOS/MacOSPlatformAdapter.swift): `Harness/Platforms/MacOS/MacOSPlatformAdapter.swift`
- [Web app driver](https://github.com/awizemann/harness/blob/main/Harness/Platforms/Web/WebPlatformAdapter.swift): `Harness/Platforms/Web/WebPlatformAdapter.swift`
- [Direct UI sessions](https://github.com/awizemann/harness/blob/main/Harness/UISessions/UISessionSupervisor.swift): `Harness/UISessions/UISessionSupervisor.swift`

### Run artifacts

- [Run history](https://github.com/awizemann/harness/blob/main/Harness/Services/RunHistoryStore.swift): `Harness/Services/RunHistoryStore.swift`
- [Run logs](https://github.com/awizemann/harness/blob/main/Harness/Services/RunLogger.swift): `Harness/Services/RunLogger.swift`
- [Run replay](https://github.com/awizemann/harness/tree/main/Harness/Features/RunReplay): `Harness/Features/RunReplay`
- [Friction reports](https://github.com/awizemann/harness/tree/main/Harness/Features/FrictionReport): `Harness/Features/FrictionReport`

### External interfaces

- [MCP server](https://github.com/awizemann/harness/blob/main/HarnessMCP/MCPServer.swift): `HarnessMCP/MCPServer.swift`
- [MCP tool handlers](https://github.com/awizemann/harness/blob/main/HarnessMCP/ToolHandlers.swift): `HarnessMCP/ToolHandlers.swift`
- [CLI runner](https://github.com/awizemann/harness/blob/main/HarnessCLI/HarnessRunner.swift): `HarnessCLI/HarnessRunner.swift`

### Other components

- **Developer**
- **External agent**
- **Test target**
- **Model service**

## Connections

- Developer → Harness GUI: configures and starts (evidence: `README.md`)
- Harness GUI → App and settings: manages targets
- Harness GUI → Goal and persona: submits goal
- Harness GUI → Dependency container: uses composition root (evidence: `Harness/App/AppContainer.swift`)
- Dependency container → Run coordinator: constructs per-run (evidence: `Harness/App/AppContainer.swift`)
- Run coordinator → Agent loop: orchestrates (evidence: `Harness/Domain/RunCoordinator.swift`)
- Run coordinator → Platform adapter: prepares and drives (evidence: `Harness/Domain/RunCoordinator.swift`)
- Agent loop → Agent tools: issues tool calls
- Dependency container → Model client factory: selects client (evidence: `Harness/App/AppContainer.swift`)
- Model client factory → LLM providers: creates provider client (evidence: `Harness/Services/LLMClientFactory.swift`)
- LLM providers → Model service: requests decisions
- Platform adapter → iOS Simulator driver: dispatches by platform (evidence: `Harness/Platforms/PlatformAdapter.swift`)
- Platform adapter → macOS app driver: dispatches by platform (evidence: `Harness/Platforms/PlatformAdapter.swift`)
- Platform adapter → Web app driver: dispatches by platform (evidence: `Harness/Platforms/PlatformAdapter.swift`)
- iOS Simulator driver → WebDriverAgent client: uses WDA
- iOS Simulator driver → Test target: drives simulator target (evidence: `README.md`)
- macOS app driver → Test target: drives macOS target (evidence: `README.md`)
- Web app driver → Test target: drives WebKit target (evidence: `README.md`)
- Run coordinator → Run history: persists run records (evidence: `Harness/Domain/RunCoordinator.swift`)
- Run coordinator → Run logs: appends run events (evidence: `Harness/Domain/RunCoordinator.swift`)
- Run history → Run replay: supplies run history
- Run history → Friction reports: supplies run findings
- External agent → MCP server: sends MCP requests (evidence: `README.md`)
- MCP server → MCP tool handlers: dispatches tools (evidence: `HarnessMCP/MCPServer.swift`)
- MCP tool handlers → Run history: reads and updates (evidence: `HarnessMCP/ToolHandlers.swift`)
- MCP tool handlers → Run coordinator: starts autonomous runs (evidence: `HarnessMCP/ToolHandlers.swift`)
- MCP tool handlers → Direct UI sessions: starts UI sessions
- Direct UI sessions → Platform adapter: prepares platform (evidence: `Harness/UISessions/UISessionSupervisor.swift`)
- Developer → CLI runner: starts dev runs (evidence: `README.md`)
- CLI runner → Run coordinator: runs coordinator (evidence: `HarnessCLI/HarnessRunner.swift`)
