Build and Run

Build and Run

Scarf is a single Xcode target with one SPM dependency (Sparkle). No CocoaPods, no Carthage, no submodules.

Prerequisites

• macOS 14.6+ (Sonoma) on the dev machine.
• Xcode 16.0+.
• Hermes at ~/.hermes/ (so the local server window has something to point at — see First Run).

Open in Xcode

git clone https://github.com/awizemann/scarf.git
cd scarf
open scarf/scarf.xcodeproj

The project uses PBXFileSystemSynchronizedRootGroup — Xcode auto-discovers any new file you drop into the source tree. You don't need to manually add files to the target.

Build with ⌘B; run with ⌘R.

Build from the command line

Debug build:

xcodebuild -project scarf/scarf.xcodeproj -scheme scarf -configuration Debug build

Universal release build (matches what the release script produces):

xcodebuild -project scarf/scarf.xcodeproj -scheme scarf \
  -configuration Release \
  -arch arm64 -arch x86_64 ONLY_ACTIVE_ARCH=NO build

Project layout

scarf/                       repo root
  CLAUDE.md                  project instructions for Claude Code
  CONTRIBUTING.md
  README.md
  releases/v<ver>/           per-version notes + appcast entry
  scripts/
    release.sh               full release pipeline
    wiki.sh                  this wiki helper
    ExportOptions.plist
  scarf/                     Xcode project root
    scarf.xcodeproj
    docs/                    internal dev notes (PRD, Discovery, ARCH)
    standards/               read-only reference standards
    scarf/                   APP TARGET — start here
      scarfApp.swift         @main App
      ContentView.swift      window root
      Core/
        Services/            9 services
        Models/              13+ models
        Transport/           4 transport files
        Persistence/         ServerRegistry
        Utilities/           markdown helpers
      Features/              25 feature modules
      Navigation/            AppCoordinator + SidebarView
      Assets.xcassets
      Info.plist
      scarf.entitlements
    scarfTests/
    scarfUITests/

Swift 6 concurrency

The project compiles with strict concurrency on. Two non-negotiables (detail in CLAUDE.md):

• @MainActor is the default isolation. Services use nonisolated async methods and route results back to MainActor for UI updates.
• All closures captured by Task, Task.detached, or withCheckedThrowingContinuation must be @Sendable. Don't capture non-Sendable types across concurrency boundaries.

What to look at first

1. scarfApp.swift — App entry point, multi-window setup, ContextBoundRoot injecting the ServerContext and friends.
2. Navigation/AppCoordinator.swift — single source of truth for navigation.
3. Core/Models/ServerContext.swift — the unified handle to a Hermes install.
4. Core/Transport/ — local vs. SSH abstraction.
5. Any feature module under Features/ for the MVVM-F shape.

Running tests

xcodebuild test -project scarf/scarf.xcodeproj -scheme scarf

See Testing for what is and isn't tested.

Releasing

Don't run xcodebuild archive / notarytool / gh release create by hand — use the release script. See Release Process.

---

Last updated: 2026-04-20 — Scarf v2.0.1