Scarf

A native macOS companion app for the Hermes AI agent.
Full visibility into what Hermes is doing, when, and what it creates.

What's New in 1.6

• Platforms — Native GUI setup for all 13 messaging platforms, no more hand-editing .env
• Credential Pools — Fixed OAuth flow and API-key handling; pick providers from a catalog
• Model Picker — Hierarchical browser backed by the 111-provider models.dev cache
• Settings tabs — 10 organized tabs covering ~60 previously hidden config fields
• Configure sidebar — New section for Personalities, Quick Commands, Plugins, Webhooks, Profiles

See the full v1.6.0 release notes.

Features

Scarf mirrors Hermes's surface area through a sidebar-based UI. Sections below map 1:1 to the app's sidebar.

Monitor

• Dashboard — System health, token usage, cost tracking, recent sessions with live refresh
• Insights — Usage analytics with token breakdown (including reasoning tokens), cost tracking, model/platform stats, top tools bar chart, activity heatmaps, notable sessions, and time period filtering (7/30/90 days or all time)
• Sessions Browser — Full conversation history with message rendering, model reasoning/thinking display, tool call inspection, full-text search, rename, delete, and JSONL export. Subagent sessions are filtered from the main list and accessible via parent session drill-down
• Activity Feed — Recent tool execution log with filtering by kind and session, detail inspector with pretty-printed arguments and tool output display

Interact

• Live Chat — Two modes: Rich Chat streams responses in real-time via the Agent Client Protocol (ACP) with iMessage-style bubbles, markdown rendering, tool call visualization, thinking/reasoning display, permission request dialogs, and a one-click /compress focus sheet (when Hermes advertises the command); Terminal runs hermes chat with full ANSI color and Rich formatting via SwiftTerm. Both modes support session persistence, resume/continue previous sessions, auto-reconnection with session recovery, and voice mode controls
• Memory Viewer/Editor — View and edit Hermes's MEMORY.md and USER.md with live file-watcher refresh, external memory provider awareness (Honcho, Supermemory, etc.), and profile-scoped memory support with profile picker
• Skills Browser — Browse installed skills by category with file content viewer and required config warnings. New in 1.6: Browse the Skills Hub, search by registry (official, skills.sh, well-known, GitHub, ClawHub, LobeHub), install, check for updates, and uninstall — all from the app

Configure (new in 1.6)

• Platforms — Native GUI setup for all 13 messaging platforms (Telegram, Discord, Slack, WhatsApp, Signal, Email, Matrix, Mattermost, Feishu, iMessage, Home Assistant, Webhook, CLI). Per-platform forms write credentials to ~/.hermes/.env and behavior toggles to ~/.hermes/config.yaml. WhatsApp and Signal pairing use an inline SwiftTerm terminal for QR scan and signal-cli daemon management
• Personalities — List defined personalities, pick the active one, and edit SOUL.md inline with markdown preview
• Quick Commands — Editor for custom /command_name shell shortcuts with dangerous-pattern detection (rm -rf, mkfs, etc.)
• Credential Pools — Per-provider credential rotation with a fixed OAuth flow (URL extraction + browser open + code paste) and proper --type api-key handling. API keys never stored in UI state — only last-4 preview. Strategy picker (fill_first / round_robin / least_used / random)
• Plugins — Install via Git URL or owner/repo, update, remove, enable/disable. Reads ~/.hermes/plugins/ directly for reliable state
• Webhooks — Create, list, test-fire, and remove webhook subscriptions. Detects the "platform not enabled" state and links to gateway setup
• Profiles — Switch between multiple isolated Hermes instances. Create, rename, delete, export (zip), import. Safe-switch warning reminds users to restart Scarf after activating a different profile

Manage

• Tools — Enable/disable toolsets per platform with a connectivity-aware platform menu (green/orange/grey/red dots for connected/configured/offline/error). Fixed in 1.6: all 13 platforms now appear (was previously stuck on CLI)
• MCP Servers — Manage Model Context Protocol servers Hermes connects to. Add via curated presets (GitHub, Linear, Notion, Sentry, Stripe, and more) or fully custom (stdio command + args, or HTTP URL with optional bearer auth). Per-server detail view with enable/disable toggle, environment variable + header editor, tool-include/exclude filters, resources/prompts toggles, request and connect timeouts, OAuth token detection + clearing, and one-click "Test Connection" that runs hermes mcp test and surfaces the discovered tool list. Gateway-restart banner appears after config changes that require a reload
• Gateway Control — Start/stop/restart the messaging gateway, view platform connection status, manage user pairing (approve/revoke)
• Cron Manager — View scheduled jobs with pre-run scripts, delivery failure tracking, timeout info, and [SILENT] job indicators. New in 1.6: full write support — create, edit, pause, resume, run-now, and delete jobs from the app
• Health — Component-level status and diagnostics. New in 1.6: inline "Run Dump" and "Share Debug Report" buttons (the latter with an upload-confirmation dialog before sending to Nous support)
• Log Viewer — Real-time log tailing for agent.log, errors.log, and gateway.log with level filtering, component filter (Gateway / Agent / Tools / CLI / Cron), clickable session-ID pills that filter to a single session, and text search
• Settings — Restructured in 1.6 into a 10-tab layout: General, Display, Agent, Terminal, Browser, Voice, Memory, Aux Models, Security, Advanced. Exposes ~60 previously hidden config fields including all 8 auxiliary model tasks, container limits, full TTS/STT provider settings, human-delay simulation, compression thresholds, logging rotation, checkpoints, website blocklist, Tirith sandbox, and delegation. One-click Backup & Restore via hermes backup / hermes import. Model picker replaces the old free-text model field, backed by the models.dev cache (111 providers, all major models) with a "Custom…" escape hatch

Project Dashboards

Custom, agent-generated dashboards for any project. Define stat boxes, charts, tables, progress bars, checklists, rich text, and embedded web views in a simple JSON file — Scarf renders them with live refresh. Let your Hermes agent build and maintain project-specific visualizations automatically. See Project Dashboards below for the full schema.

System

• Hermes Process Control — Start, stop, and restart the Hermes agent directly from Scarf
• Menu Bar — Status icon showing Hermes running state with quick actions

Requirements

• macOS 14.6+ (Sonoma)
• Xcode 16.0+
• Hermes agent v0.6.0+ installed at ~/.hermes/ (v0.9.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)	Verified
v0.9.0 (2026-04-13)	Verified (recommended for full 1.6 feature support)

Scarf 1.6 targets Hermes v0.9.0 specifically for the new Platforms, Credentials, Skills Hub, and Cron write features. Earlier Hermes versions remain supported for the monitoring and session features but may not expose every new setup form.

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 build from Releases:

• Scarf-vX.X.X-Universal.zip — Apple Silicon + Intel (recommended)
• Scarf-vX.X.X-ARM64.zip — Apple Silicon only (smaller)

1. Unzip and drag Scarf.app to Applications
2. 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
    MCPServers/   MCP server registry, presets, OAuth, tool filters, test runner
    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
hermes mcp	CLI commands	Add/Remove/Test MCP servers
mcp-tokens/*.json	JSON (per-server OAuth)	Detect/Delete
.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": "Project status at a glance",
  "sections": [
    {
      "title": "Overview",
      "columns": 3,
      "widgets": [
        {
          "type": "stat",
          "title": "Test Coverage",
          "value": "87%",
          "icon": "checkmark.shield",
          "color": "green",
          "subtitle": "+2.1% this week"
        },
        {
          "type": "progress",
          "title": "Sprint Progress",
          "value": 0.73,
          "label": "73% complete",
          "color": "blue"
        },
        {
          "type": "list",
          "title": "Tasks",
          "items": [
            { "text": "Write unit tests", "status": "done" },
            { "text": "Update API docs", "status": "active" },
            { "text": "Deploy to prod", "status": "pending" }
          ]
        }
      ]
    }
  ]
}

2. Register your project

In Scarf, go to Projects in the sidebar and click the + button to add your project folder. Or have your agent add it directly to the registry at ~/.hermes/scarf/projects.json:

{
  "projects": [
    { "name": "my-project", "path": "/Users/you/Developer/my-project" }
  ]
}

3. View in Scarf

Select your project in the Projects sidebar — the dashboard renders immediately. Scarf watches the file for changes and refreshes automatically whenever the JSON is updated.

Widget Types

Type	Description	Key Fields
stat	Key metric with large value display	value, icon, color, subtitle
progress	Progress bar with label	value (0.0–1.0), label, color
text	Rich text block	content, format ("markdown" or "plain")
table	Data table with headers	columns, rows
chart	Line, bar, or pie chart	chartType, series (each with name, color, data)
list	Checklist with status indicators	items (each with text, status: done/active/pending)
webview	Embedded web browser	url, height (default 400)

The webview widget embeds a live web browser directly in your dashboard — perfect for displaying local dev servers, HTML reports, or any web-based tool your agent generates.

When a dashboard includes a webview widget, Scarf adds a tabbed interface: Dashboard shows your normal widgets, Site shows the web content full-canvas with clean margins — using the entire available space in the app. This gives you the best of both worlds: compact metrics at a glance, and a full embedded browser when you need it.

{
  "type": "webview",
  "title": "Project Report",
  "url": "http://localhost:8000/dashboard",
  "height": 500
}

• url: Any URL — typically a local server (http://localhost:...) or file path
• height: Height in points when displayed as an inline widget card (default: 400). The Site tab always uses full available space regardless of this setting.

Colors: red, orange, yellow, green, blue, purple, pink, teal, indigo, mint, brown, gray

Icons: Any SF Symbol name (e.g., checkmark.shield, cpu, doc.text, chart.bar)

Agent-Generated Dashboards

The real power is letting your Hermes agent build and update dashboards automatically. Add instructions like this to your agent's context:

Analyze this project and create a .scarf/dashboard.json dashboard with relevant metrics and status. Use stat widgets for key numbers, charts for trends, tables for structured data, lists for task tracking, and a webview widget if the project has a local web server or HTML reports. Register the project in ~/.hermes/scarf/projects.json if not already registered.

Your agent can update the dashboard as part of cron jobs, after builds, or whenever project state changes. Since Scarf watches the file, updates appear in real-time.

Dashboard Schema Reference

{
  "version": 1,
  "title": "Required — dashboard title",
  "description": "Optional — subtitle text",
  "updatedAt": "Optional — ISO 8601 timestamp",
  "sections": [
    {
      "title": "Section Name",
      "columns": 3,
      "widgets": [{ "type": "...", "title": "..." }]
    }
  ]
}

Each section defines a grid with 1–4 columns. Widgets flow left-to-right, wrapping to new rows. See DASHBOARD_SCHEMA.md for the full schema reference with examples of every widget type.

Contributing

Contributions are welcome. Please open an issue to discuss what you'd like to change before submitting a PR.

1. Fork the repo
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

Support

If you find Scarf useful, consider buying me a coffee.

License

MIT