Noureddine RAMDI / Scarf: a native Swift companion app for Hermes AI with smooth multimodal input and real-time monitoring

Created Mon, 04 May 2026 10:23:01 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
935 Words
github-stars swift macos ios ai-agent ssh sqlite swiftui concurrency

awizemann/scarf

Scarf tackles the common developer frustration of managing AI agents through command line interfaces and raw state files by providing a native macOS and iOS companion app for the Hermes AI agent. It wraps Hermes’s CLI and SQLite state database in a SwiftUI GUI, enabling multi-window chat sessions, skill browsing, cron job editing, and real-time monitoring — all with a responsive UI that avoids the usual sluggishness caused by heavy image processing or database queries.

native macOS and iOS GUI for the Hermes AI agent

At its core, Scarf is a native application written in Swift for macOS 14.6+ (Sonoma) and iOS 18.0+ (via the companion app ScarfGo). It connects to Hermes AI agents running locally or remotely via SSH, using Citadel on iOS for a pure-Swift SSH implementation.

The app provides a graphical layer over Hermes’s CLI and SQLite state database, which means it parses command outputs like hermes status and reads Hermes’s state.db for session and skill data. This approach ensures it can support real-time features such as a dashboard displaying Hermes’s operational status and session progress.

Key functionalities include multi-window chat for interacting with Hermes agents, browsing and managing AI skills, editing scheduled cron jobs that control autonomous agent behaviors, and observing a live dashboard that leverages atomic SQLite snapshot reads to avoid data inconsistencies.

The app requires Hermes agent v0.6.0 or newer, with v0.12.0+ recommended to unlock advanced features like autonomous Curator, multimodal image input, new provider integrations, and extended gateway support.

concurrency patterns and state synchronization under the hood

What distinguishes Scarf is its handling of UI responsiveness, especially when dealing with multimodal inputs like images. SwiftUI’s MainActor can become a bottleneck if expensive tasks like image encoding run on the main thread, causing UI jank. Scarf sidesteps this by offloading JPEG image downsampling and encoding (to 1568px JPEGs) onto a background actor detached from the MainActor. This concurrency pattern prevents blocking and keeps typing and UI interactions smooth.

For state synchronization, Scarf reads Hermes’s SQLite database snapshots atomically, ensuring consistent dashboard data without partial reads. This is essential for real-time monitoring where stale or corrupted data could mislead users.

The app also addresses common SwiftUI state management issues such as typing lag and draft leakage by applying fixes to how state updates propagate in the UI.

Connectivity-wise, Scarf uses SSH to communicate with Hermes instances, supporting both local and remote hosts. It includes capability gating that gracefully enables or disables features depending on the connected Hermes version, maintaining compatibility across releases.

quick start

remote setup requirements

The remote host must have:

  1. SSH access — key-based authentication via your local ssh-agent. Scarf does not prompt for passphrases; you must run ssh-add once in the Terminal before connecting.

  2. sqlite3 installed and available in the remote $PATH for atomic DB snapshots. On Ubuntu/Debian, install it with apt install sqlite3; on RHEL/Fedora, use yum install sqlite; on Alpine, apk add sqlite.

  3. pgrep available in the remote $PATH. It is used by the Dashboard to check if Hermes is running. This is standard on most distros; if missing, install procps.

  4. Read access to ~/.hermes/ by the SSH user. When Hermes runs under a different user (systemd service or Docker), ensure the SSH user can read config.yaml and state.db. This can be done by SSHing as the Hermes user, adjusting permissions and groups accordingly, or specifying the Hermes data directory explicitly in the server settings.

requirements summary

  • macOS 14.6+ (Sonoma) for Scarf
  • iOS 18.0+ for ScarfGo (TestFlight available from v2.5)
  • Xcode 16.0+ to build from source
  • Hermes agent v0.6.0+ installed at ~/.hermes/ on the target hosts, with v0.12.0+ recommended for full feature support

This setup ensures proper SSH connectivity, atomic state snapshotting, and CLI command availability.

verdict

Scarf is a well-crafted native Swift app that fills a practical gap: providing a friendly, performant UI for interacting with the Hermes AI agent. Its careful concurrency design for image encoding and robust SQLite state synchronization show attention to real-world SwiftUI challenges.

The tradeoff is that it depends heavily on Hermes’s CLI and database schema, which means any upstream changes to Hermes require corresponding updates in Scarf. Also, the SSH-based connectivity and remote setup requirements add complexity for casual users.

That said, if you’re running Hermes AI agents and want a polished macOS/iOS companion that supports multimodal input and real-time dashboards without UI lag, Scarf is worth exploring. The clear remote prerequisites and capability gating make it suitable for production environments where stability and compatibility matter.

For developers interested in Swift concurrency patterns and native UI integration with CLI-based AI systems, Scarf offers useful patterns and insights worth studying.

→ GitHub Repo: awizemann/scarf ⭐ 374 · Swift