mirror of https://github.com/awizemann/scarf.git synced 2026-05-10 10:36:35 +00:00

Files

T

Alan Wizemann 18278a3357 Initial release: Scarf — macOS GUI for the Hermes AI agent

Native SwiftUI app providing full visibility into the Hermes AI agent:
- Dashboard with system health, token usage, and cost tracking
- Sessions browser with conversation detail and FTS5 search
- Activity feed with tool call inspector (read/edit/execute/fetch/browser)
- Embedded terminal chat via SwiftTerm with full ANSI/Rich rendering
- Memory viewer/editor with live file-watching refresh
- Skills browser by category with file content viewer
- Cron job viewer with output display
- Real-time log tailing with level filtering
- Settings display with raw config and Finder path links
- Menu bar status icon with quick actions

Architecture: MVVM-Feature, zero dependencies beyond SwiftTerm,
read-only SQLite access, Swift 6 strict concurrency.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-31 02:30:04 -04:00

3.5 KiB

Raw Blame History

Scarf — Product Requirements Document

Overview

Scarf is a native macOS application that provides a graphical interface for the Hermes AI agent. Hermes is a CLI-based AI agent with 40+ tools, multi-platform messaging, autonomous skill creation, persistent memory, and scheduled automation. Scarf gives users visibility into what Hermes is doing, when, and what it creates.

Problem

Hermes operates entirely through CLI with no visual dashboard. Users cannot easily:

See what the agent is currently doing or has done
Browse conversation history across sessions
Monitor tool executions in real-time
Manage memory, skills, or cron jobs visually
Chat with the agent through a native interface

Target User

Developer running Hermes locally on macOS who wants transparency and control over agent activity.

Core Features

1. Dashboard

System health overview (model, provider, connection status)
Active session indicator
Token usage and cost summary (aggregated from session data)
Gateway platform connection status
Recent activity feed

2. Sessions Browser

List all conversation sessions with metadata (source, message count, tool calls, cost, duration)
Full conversation detail view with message rendering
Full-text search across all sessions (via SQLite FTS5)
Session lineage tracking (parent_session_id chains)

3. Activity Feed

Real-time tool execution monitoring (the core transparency feature)
Each entry: tool name, kind, arguments, result preview, timestamp
Filterable by tool type, session, time range
Color-coded by tool kind (read/edit/execute/fetch)

4. Live Chat

Send messages to Hermes via ACP (Agent Client Protocol)
Stream responses with tool calls shown inline
Session management (new, load, resume)

5. Memory Viewer/Editor

Display MEMORY.md and USER.md with markdown rendering
Edit and save changes
Character count vs configured limits

6. Skills Browser

Tree view by category
Skill metadata display
Search and filter

7. Cron Manager

View scheduled jobs with status, next/last run times
View job output
Enable/disable jobs

8. Log Viewer

Real-time log tailing (errors.log, gateway.log)
Level-based filtering and text search

Status icon showing Hermes state (running/idle/error)
Quick access to recent session, new chat

Technical Constraints

macOS 26.2+ (SwiftUI, Swift 6 concurrency)
No external SPM dependencies — uses system SQLite3 C API, Foundation JSON
Reads Hermes data from ~/.hermes/ (requires sandbox disabled)
ACP communication via subprocess stdio JSON-RPC
App sandbox disabled (developer tool needing filesystem access)

Data Sources

Source	Path	Format	Access
Sessions DB	`~/.hermes/state.db`	SQLite (WAL)	Read-only
Session files	`~/.hermes/sessions/*.json`	JSON	Read-only
Config	`~/.hermes/config.yaml`	YAML	Read/Write
Memory	`~/.hermes/memories/*.md`	Markdown	Read/Write
Cron jobs	`~/.hermes/cron/jobs.json`	JSON	Read/Write
Cron output	`~/.hermes/cron/output/`	Text	Read-only
Logs	`~/.hermes/logs/*.log`	Text	Read-only
Gateway state	`~/.hermes/gateway_state.json`	JSON	Read-only
Skills	`~/.hermes/skills/`	Directory tree	Read-only
ACP	`hermes acp` subprocess	JSON-RPC stdio	Bidirectional

Non-Goals (v1)

Config editing UI (read-only display for v1, except memory)
Skill creation or management
Gateway platform management
Multi-user support

3.5 KiB Raw Blame History