# awizemann/scarf architecture

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

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

## Overview

Scarf is a native macOS and iOS client for inspecting and managing Hermes AI agents locally or over SSH. The main workflow is selecting a host, connecting through its transport, and using the app’s chat or management surfaces to inspect Hermes state or invoke supported actions. The graph includes the documented project, session, skills, memory, cron, MCP, and voice capabilities. Several feature links are README-level; sampled code verifies transport selection, project-context refresh, and voice delegation, but not every UI-to-service call.

Main entry points: [`scarf/Scarf iOS`](https://github.com/awizemann/scarf/tree/main/scarf/Scarf%20iOS) (ScarfGo), [`scarf/scarf`](https://github.com/awizemann/scarf/tree/main/scarf/scarf) (macOS app), [`scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/RichChatViewModel.swift`](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/RichChatViewModel.swift) (Chat and sessions), [`scarf/Packages/ScarfCore/Sources/ScarfCore/Models/ServerContext.swift`](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Models/ServerContext.swift) (Server context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Native clients"]
  node_mac["macOS app"]
  node_ios["ScarfGo"]
end

subgraph group_connection["Host connection"]
  node_server_context["Server context"]
  node_transport["Local / SSH transport"]
  node_capabilities["Version capabilities"]
end

subgraph group_agent["Agent workflows"]
  node_chat["Chat and sessions"]
  node_acp["ACP client<br/>[ACPClient.swift]"]
  node_projects["Projects"]
  node_project_context["Project context"]
  node_voice["Live voice"]
  node_voice_controller["Voice controller"]
end

subgraph group_operations["Management and insight"]
  node_skills_memory_cron["Skills, memory, cron"]
  node_dashboard_insights["Dashboards and logs"]
  node_mcp["MCP servers"]
  node_settings["Settings and gateways"]
end

node_user(("User"))
node_hermes_host(("Hermes host"))
node_hermes_state["Hermes state"]
node_hermes_cli["Hermes CLI"]

node_user -->|"uses"| node_mac
node_user -->|"uses"| node_ios
node_mac -.->|"selects host"| node_server_context
node_ios -.->|"selects host"| node_server_context
node_server_context -->|"creates"| node_transport
node_transport -->|"connects"| node_hermes_host
node_hermes_host -->|"reads state"| node_hermes_state
node_hermes_cli -->|"runs actions"| node_hermes_host
node_mac -->|"manages via"| node_hermes_cli
node_ios -->|"manages via"| node_hermes_cli
node_mac -.->|"adapts UI"| node_capabilities
node_ios -.->|"adapts UI"| node_capabilities
node_mac -.->|"starts chat"| node_chat
node_ios -.->|"starts chat"| node_chat
node_chat -->|"sends turns"| node_acp
node_ios -->|"browses projects"| node_projects
node_projects -.->|"refreshes context"| node_project_context
node_project_context -->|"writes context"| node_hermes_state
node_chat -->|"hosts voice turns"| node_voice
node_voice_controller -->|"starts engine"| node_voice
node_ios -->|"manages content"| node_skills_memory_cron
node_mac -->|"views activity"| node_dashboard_insights
node_ios -.->|"manages MCP"| node_mcp
node_mac -.->|"configures agent"| node_settings

click node_mac "https://github.com/awizemann/scarf/tree/main/scarf/scarf"
click node_ios "https://github.com/awizemann/scarf/tree/main/scarf/Scarf%20iOS"
click node_server_context "https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Models/ServerContext.swift"
click node_transport "https://github.com/awizemann/scarf/tree/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Transport"
click node_capabilities "https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Services/HermesCapabilities.swift"
click node_chat "https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/RichChatViewModel.swift"
click node_acp "https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ACP/ACPClient.swift"
click node_projects "https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/ProjectsViewModel.swift"
click node_project_context "https://github.com/awizemann/scarf/blob/main/scarf/scarf/Core/Services/ProjectAgentContextService.swift"
click node_voice "https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/VoiceLive/VoiceConversationEngine.swift"
click node_voice_controller "https://github.com/awizemann/scarf/blob/main/scarf/scarf/Features/VoiceLive/VoiceLiveController.swift"
click node_skills_memory_cron "https://github.com/awizemann/scarf/tree/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels"
click node_dashboard_insights "https://github.com/awizemann/scarf/tree/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels"
click node_mcp "https://github.com/awizemann/scarf/blob/main/scarf/scarf/Features/MCPServers/ViewModels/MCPLoginController.swift"
click node_settings "https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesProfileRoutes.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_mac,node_ios,node_user toneBlue
class node_server_context,node_transport,node_capabilities toneAmber
class node_chat,node_acp,node_projects,node_project_context,node_voice,node_voice_controller toneMint
class node_skills_memory_cron,node_dashboard_insights,node_mcp,node_settings toneRose
class node_hermes_host,node_hermes_state,node_hermes_cli toneIndigo
```

## Components

### Native clients

- [macOS app](https://github.com/awizemann/scarf/tree/main/scarf/scarf): `scarf/scarf`
- [ScarfGo](https://github.com/awizemann/scarf/tree/main/scarf/Scarf%20iOS): `scarf/Scarf iOS`

### Host connection

- [Server context](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Models/ServerContext.swift): `scarf/Packages/ScarfCore/Sources/ScarfCore/Models/ServerContext.swift`
- [Local / SSH transport](https://github.com/awizemann/scarf/tree/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Transport): `scarf/Packages/ScarfCore/Sources/ScarfCore/Transport`
- [Version capabilities](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Services/HermesCapabilities.swift): `scarf/Packages/ScarfCore/Sources/ScarfCore/Services/HermesCapabilities.swift`

### Agent workflows

- [Chat and sessions](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/RichChatViewModel.swift): `scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/RichChatViewModel.swift`
- [ACP client](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ACP/ACPClient.swift): `scarf/Packages/ScarfCore/Sources/ScarfCore/ACP/ACPClient.swift`
- [Projects](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/ProjectsViewModel.swift): `scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/ProjectsViewModel.swift`
- [Project context](https://github.com/awizemann/scarf/blob/main/scarf/scarf/Core/Services/ProjectAgentContextService.swift): `scarf/scarf/Core/Services/ProjectAgentContextService.swift`
- [Live voice](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/VoiceLive/VoiceConversationEngine.swift): `scarf/Packages/ScarfCore/Sources/ScarfCore/VoiceLive/VoiceConversationEngine.swift`
- [Voice controller](https://github.com/awizemann/scarf/blob/main/scarf/scarf/Features/VoiceLive/VoiceLiveController.swift): `scarf/scarf/Features/VoiceLive/VoiceLiveController.swift`

### Management and insight

- [Skills, memory, cron](https://github.com/awizemann/scarf/tree/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels): `scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels`
- [Dashboards and logs](https://github.com/awizemann/scarf/tree/main/scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels): `scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels`
- [MCP servers](https://github.com/awizemann/scarf/blob/main/scarf/scarf/Features/MCPServers/ViewModels/MCPLoginController.swift): `scarf/scarf/Features/MCPServers/ViewModels/MCPLoginController.swift`
- [Settings and gateways](https://github.com/awizemann/scarf/blob/main/scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesProfileRoutes.swift): `scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesProfileRoutes.swift`

### Other components

- **User**
- **Hermes host**
- **Hermes state**
- **Hermes CLI**

## Connections

- User → macOS app: uses
- User → ScarfGo: uses
- macOS app → Server context: selects host (evidence: `scarf/scarf/Features/VoiceLive/VoiceLiveController.swift`)
- ScarfGo → Server context: selects host (evidence: `scarf/Scarf iOS/Webhooks/WebhooksView.swift`)
- Server context → Local / SSH transport: creates (evidence: `scarf/Packages/ScarfCore/Sources/ScarfCore/Models/ServerContext.swift`)
- Local / SSH transport → Hermes host: connects
- Hermes host → Hermes state: reads state
- Hermes CLI → Hermes host: runs actions
- macOS app → Hermes CLI: manages via
- ScarfGo → Hermes CLI: manages via
- macOS app → Version capabilities: adapts UI (evidence: `scarf/scarf/Core/Services/ProjectAgentContextService.swift`)
- ScarfGo → Version capabilities: adapts UI
- macOS app → Chat and sessions: starts chat
- ScarfGo → Chat and sessions: starts chat
- Chat and sessions → ACP client: sends turns
- ScarfGo → Projects: browses projects
- Projects → Project context: refreshes context
- Project context → Hermes state: writes context (evidence: `scarf/scarf/Core/Services/ProjectAgentContextService.swift`)
- Chat and sessions → Live voice: hosts voice turns (evidence: `scarf/Packages/ScarfCore/Sources/ScarfCore/VoiceLive/VoiceConversationEngine.swift`)
- Voice controller → Live voice: starts engine (evidence: `scarf/scarf/Features/VoiceLive/VoiceLiveController.swift`)
- ScarfGo → Skills, memory, cron: manages content
- macOS app → Dashboards and logs: views activity
- ScarfGo → MCP servers: manages MCP
- macOS app → Settings and gateways: configures agent (evidence: `scarf/scarf/Features/Settings/Views/Components/ProfileRoutesSection.swift`)