scarf

Requirements

• macOS 14.6+ (Sonoma)
• Xcode 16.0+
• Hermes agent v0.6.0+ installed at ~/.hermes/ (v0.8.0 recommended for full feature support)

Compatibility

Scarf reads Hermes's SQLite database and parses CLI output from hermes status, hermes doctor, hermes tools, hermes sessions, hermes gateway, and hermes pairing. Automatic schema detection provides backward compatibility with older databases while supporting new features in newer Hermes versions.

| Hermes Version | Status | |----------------|--------| | v0.6.0 (2026-03-30) | Verified | | v0.7.0 (2026-04-03) | Verified | | v0.8.0 (2026-04-08, latest) | Verified |

If a Hermes update changes the database schema or CLI output format, Scarf may need to be updated. Check the Health view for compatibility warnings.

Install

Pre-built Binary (no Xcode required)

Download the latest universal binary (Apple Silicon + Intel) from Releases:

1. Download Scarf-vX.X.X-Universal.zip
2. Unzip and drag Scarf.app to Applications
3. On first launch, right-click and choose Open (or go to System Settings → Privacy & Security → Open Anyway)

Build from Source

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

Or from the command line:

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

Architecture

Scarf follows the MVVM-Feature pattern with zero external dependencies beyond SwiftTerm:

scarf/
  Core/
    Models/       Plain data structs (HermesSession, HermesMessage, HermesConfig, etc.)
    Services/     Data access (SQLite reader, file I/O, log tailing, file watcher)
  Features/       Self-contained feature modules
    Dashboard/    System overview and stats
    Insights/     Usage analytics and activity patterns
    Sessions/     Conversation browser with rename, delete, export
    Activity/     Tool execution feed with inspector
    Projects/     Agent-generated project dashboards with widget rendering
    Chat/         Rich ACP chat and embedded terminal with voice controls
    Memory/       Memory viewer and editor
    Skills/       Skill browser by category
    Tools/        Toolset management per platform
    Gateway/      Messaging gateway control and pairing
    Cron/         Scheduled job viewer
    Logs/         Real-time log viewer
    Settings/     Structured config editor
  Navigation/     AppCoordinator + SidebarView

Data Sources

Scarf reads Hermes data directly from ~/.hermes/:

| Source | Format | Access | |--------|--------|--------| | state.db | SQLite (WAL mode) | Read-only | | config.yaml | YAML | Read-only | | memories/*.md | Markdown | Read/Write | | cron/jobs.json | JSON | Read-only | | logs/*.log | Text | Read-only | | gateway_state.json | JSON | Read-only | | skills/ | Directory tree | Read-only | | hermes acp | ACP subprocess (JSON-RPC stdio) | Real-time chat | | hermes chat | Terminal subprocess | Interactive | | hermes tools | CLI commands | Enable/Disable | | hermes sessions | CLI commands | Rename/Delete/Export | | hermes gateway | CLI commands | Start/Stop/Restart | | hermes pairing | CLI commands | Approve/Revoke | | .scarf/dashboard.json | JSON (per-project) | Read-only | | scarf/projects.json | JSON (registry) | Read/Write |

The app opens state.db in read-only mode to avoid WAL contention with Hermes. Management actions (tool toggles, session rename/delete/export) go through the Hermes CLI.

Dependencies

| Package | Purpose | |---------|---------| | SwiftTerm | Terminal emulator for the Chat feature |

Everything else uses system frameworks: SQLite3 C API, Foundation JSON, AttributedString markdown, SwiftUI Charts, GCD file watching.

How It Works

Scarf watches ~/.hermes/ for file changes and queries the SQLite database for sessions, messages, and analytics. Views refresh automatically when Hermes writes new data.

The Chat tab has two modes. Rich Chat communicates with Hermes via the Agent Client Protocol (ACP) — a JSON-RPC connection over stdio — streaming responses in real-time with automatic reconnection and session recovery on connection loss. Terminal mode spawns hermes chat in a pseudo-terminal for the full interactive CLI experience with proper ANSI rendering. Sessions persist across navigation in both modes — switch tabs and come back without losing your conversation.

Management actions (renaming sessions, toggling tools, editing memory) call the Hermes CLI or write directly to the appropriate files, keeping Scarf and Hermes in sync.

The app sandbox is disabled because Scarf needs direct access to ~/.hermes/ and the ability to spawn the Hermes binary.

Project Dashboards

Project Dashboards turn Scarf into a customizable monitoring hub for all your projects. You define a simple JSON file in your project folder describing what to display — stat boxes, charts, tables, progress bars, checklists, rich text, and embedded web views — and Scarf renders it as a live-updating dashboard. Your Hermes agent can generate and maintain these dashboards automatically.

What You Can Build

• Development dashboards — test coverage, build status, open issues, sprint progress
• Data project trackers — pipeline metrics, data quality scores, processing throughput
• Deployment monitors — deploy history tables, uptime stats, error rate charts
• Research dashboards — experiment results, key findings, paper status checklists
• Agent activity views — cron job results, content generation stats, task completion rates
• Embedded web apps — local dev servers, HTML reports, Grafana dashboards, any web-based tool your agent generates
• Any project status — if your agent can measure it, Scarf can display it

Quick Start

1. Create the dashboard file

Create .scarf/dashboard.json in any project folder:

{
  "version": 1,
  "title": "My Project",
  "description": "