Scarf macOS Companion App

Scarf provides a sidebar-based UI that mirrors the Hermes surface area. The main functional areas are:

Monitor

• Dashboard: System health, token usage, and cost tracking.
• Insights: Usage analytics, token breakdowns, and activity heatmaps.
• Sessions Browser: Conversation history with search, tool inspection, and JSONL export.
• Activity Feed: Tool execution logs.

Interact

• Live Chat: Supports Rich Chat (real-time streaming, markdown, tool visualization) and Terminal mode (hermes chat via SwiftTerm).
• Memory Viewer/Editor: Live editing of MEMORY.md and USER.md.
• Skills Browser: Browse and install skills from the Skills Hub (official, GitHub, etc.).

Configure

• Platforms: Messaging platform setup.
• Personalities: Edit SOUL.md and switch active personalities.
• Quick Commands: Custom shell shortcuts with safety detection.
• Credential Pools: Per-provider rotation strategies (fill_first, round_robin, least_used, random).
• Plugins: Install via Git URL or owner/repo into ~/.hermes/plugins/.
• Profiles: Manage isolated Hermes instances.

Manage

• Tools: Enable/disable toolsets per platform.
• MCP Servers: Manage Model Context Protocol connections.
• Gateway Control: Start/stop/restart the messaging gateway.
• Cron Manager: Manage scheduled jobs.
• Log Viewer: Real-time tailing of agent.log, errors.log, and gateway.log with filtering.

The UI Kit is composed of several React components that mirror the visual rhythm and navigation hierarchy of the original SwiftUI application. Note that this kit is cosmetic only; it replicates visuals but does not include the Swift business logic.

Component Mapping

The macOS App Suite uses a centralized set of 11 standards to maintain consistency across all apps (InControl, ShabuBox, Threader, Modeler, etc.). These standards cover everything from low-level data persistence to high-level AI integration and design principles.

Core Standards Modules:

• 01 Architecture: MVVM-F pattern, AppCoordinator, and directory layouts.
• 02 SwiftData: Persistence, schema versioning, and Skeleton Records.
• 03 Storage & Sandboxing: iCloud, NSFileCoordinator, and path security.
• 04 Swift Conventions: Swift 6 concurrency and os.Logger usage.
• 05 Design System: Visual principles, material tiers, and typography.
• 06 Editor Patterns: Tabbed editor architecture and Quick Entry.
• 07 AI Integration: Native-first AI and LLM protocol layers.
• 08 Data Integrity: Backup/restore parity and CloudKit sync safety.
• 09 Performance: Component extraction and state ownership.
• 10 Testing: Swift Testing framework and protocol mocking.
• 11 Multiplatform: iOS companion apps and shared libraries.

An AUDIT_CHECKLIST.md is provided to perform gap detection for each project.

The v2.8.0 release for iOS (WS-9) focuses on providing read-only mirrors of existing Mac features to ensure parity.

Included Features:

• Goal Pill & Queue Chip: Added to the projectContextBar. These are read-only badges; tapping them is a no-op.
• Kanban Detail Sheet: Includes chips, banners, diagnostics blocks, and a tap sheet (via ScarfGoKanbanDetailSheet.swift).
• Curator Archived Section: Adds visibility to archived items in the CuratorView.swift surface.
• Settings Extensions: Adds platform configuration and capability injection to SettingsView.platformsSection.
• v0.13 Features Badge: A badge and informational sheet indicating active v0.13 features.

Key Limitations (Read-Only Surface):

• No Write Access: You cannot send /goal or /queue commands from the iOS chat composer, nor can you use Verify/Reject buttons on Kanban, or Archive/Restore on Curator.
• No Settings Editing: Allowlist and platform toggles cannot be edited directly on iOS; they are extensions of the existing view.
• No Live Curator Updates: Updates rely on manual pull-to-refresh or existing .task invocations; there is no active 'watch' surface.
• No Deep Linking: The v0.13 features sheet is text-only and does not support routing to other tabs.

Scarf provides several modules to manage the Hermes agent:

• Dashboard: Overview of system health (model, provider, connection), active sessions, token usage/cost, and recent activity.
• Sessions Browser: List and search (via SQLite FTS5) conversation history. Includes metadata like tool calls, cost, and duration, and supports session lineage tracking.
• Activity Feed: Real-time monitoring of tool executions. Entries show tool name, kind, arguments, and results, color-coded by type (read/edit/execute/fetch).
• Live Chat: Interface to send messages to Hermes via ACP, streaming responses and inline tool calls.
• Memory Viewer/Editor: View and edit MEMORY.md and USER.md with markdown rendering.
• Skills Browser: Tree view of available skills by category.
• Cron Manager: Manage scheduled jobs, view status, next/last run times, and job output.
• Log Viewer: Real-time tailing and filtering of errors.log and gateway.log.
• Menu Bar Presence: Status icon showing Hermes state (running/idle/error) and quick access to recent sessions.

As of the current version (v2.5), ScarfGo provides the following capabilities:

• Onboarding: An 8-step process to connect to a host. This involves generating or importing an Ed25519 key, displaying the public key for you to add to the remote server's ~/.ssh/authorized_keys, and performing a test probe.
• Dashboard: Displays session counts, message counts, tool-call counts, token totals, and the last 5 sessions. Data is retrieved by performing a sqlite3 .backup on the remote ~/.hermes/state.db and downloading it via SFTP.
• Chat: Real-time ACP (Agent Communication Protocol) over a dedicated SSH exec channel. Supports Markdown, tool-call cards, permission sheets, reasoning disclosure, and streaming. (Note: There is no embedded terminal).
• Memory: Ability to read and write MEMORY.md, USER.md, and SOUL.md files.
• Cron: Manage scheduled jobs. You can list jobs, toggle them, edit schedules/prompts/skills/delivery routes, add new jobs, or delete them. Jobs are written atomically to ~/.hermes/cron/jobs.json.
• Skills: Read-only browsing of skill categories and individual skill files.
• Settings: Read-only view of the remote config.yaml.

Scarf (Mac) and ScarfGo (iOS) both connect to the same Hermes host and share the same data, but they serve different primary purposes.

• Scarf (Mac) is a full-featured management and authoring client. It is the canonical tool for deep configuration (full YAML editing), template/skill authoring, log triage, gateway debugging, and operations work.
• ScarfGo (iOS) is a "monitor + steer" client. It is optimized for running chats, monitoring sessions/memory/jobs, and approving/denying permissions on the go.

Key functional differences include:

• Settings: Mac allows full YAML editing; iOS provides "Quick Edits" for 7 specific keys via a shell-out command.
• Authoring: Mac supports template and skill authoring; iOS is read-only for skills and does not support templates.
• Operations: Mac includes health views, logs viewers, and messaging gateway status; iOS lacks these due to filesystem and UX constraints.