How awizemann/scarf works
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 iOS ScarfGo · scarf macOS app · RichChatViewModel.swift Chat and sessions · ServerContext.swift Server context
Components 19
Host connection
- Server context
scarf/Packages/ScarfCore/Sources/ScarfCore/Models/ServerContext.swift - Local / SSH transport
scarf/Packages/ScarfCore/Sources/ScarfCore/Transport - Version capabilities
scarf/Packages/ScarfCore/Sources/ScarfCore/Services/HermesCapabilities.swift
Agent workflows
- Chat and sessions
scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/RichChatViewModel.swift - ACP client
scarf/Packages/ScarfCore/Sources/ScarfCore/ACP/ACPClient.swift - Projects
scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels/ProjectsViewModel.swift - Project context
scarf/scarf/Core/Services/ProjectAgentContextService.swift - Live voice
scarf/Packages/ScarfCore/Sources/ScarfCore/VoiceLive/VoiceConversationEngine.swift - Voice controller
scarf/scarf/Features/VoiceLive/VoiceLiveController.swift
Management and insight
- Skills, memory, cron
scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels - Dashboards and logs
scarf/Packages/ScarfCore/Sources/ScarfCore/ViewModels - MCP servers
scarf/scarf/Features/MCPServers/ViewModels/MCPLoginController.swift - Settings and gateways
scarf/Packages/ScarfCore/Sources/ScarfCore/Models/HermesProfileRoutes.swift
Other components
- User
- Hermes host
- Hermes state
- Hermes CLI
Connections 24
- User → macOS app: uses
- User → ScarfGo: uses
- macOS app → Server context: selects host
scarf/scarf/Features/VoiceLive/VoiceLiveController.swift - ScarfGo → Server context: selects host
scarf/Scarf iOS/Webhooks/WebhooksView.swift - Server context → Local / SSH transport: creates
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
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
scarf/scarf/Core/Services/ProjectAgentContextService.swift - Chat and sessions → Live voice: hosts voice turns
scarf/Packages/ScarfCore/Sources/ScarfCore/VoiceLive/VoiceConversationEngine.swift - Voice controller → Live voice: starts engine
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
scarf/scarf/Features/Settings/Views/Components/ProfileRoutesSection.swift