Chat

Chat

Two modes share the same sidebar item: Rich Chat (real-time ACP streaming with iMessage-style bubbles) and Terminal (the hermes chat CLI rendered with full ANSI color in an embedded terminal). Switch between them in the chat toolbar.

Rich Chat

Streams tokens, thoughts, and tool calls live via the ACP subprocess. No DB polling — when Hermes emits a message chunk, you see it immediately.

What it renders:

• Rust-tinted bubbles in the v2.5 design (UnevenRoundedRectangle for the user; bordered card with a sparkles gradient avatar for the assistant). User text in ScarfColor.onAccent; assistant in ScarfColor.foregroundPrimary over ScarfColor.backgroundSecondary.
• Markdown content (links, lists, code blocks, tables).
• Reasoning / thinking chunks in a warning-tinted disclosure block ("REASONING" uppercase label) above the answer.
• Tool calls as inline cards with kind-tinted borders + uppercase tracked labels (READ / EDIT / EXECUTE / FETCH / BROWSER) using ScarfColor.success / info / warning / Tool.web / Tool.search. Expanded JSON in a bordered backgroundSecondary panel.
• Permission requests as modal sheets — Hermes asks before executing risky tools; you choose Allow / Deny. Numbered keyboard shortcuts (v2.5+): 1–9 bind to the option buttons on Mac (visible "1. " / "2. " prefixes); approve / deny without reaching for the mouse. iOS shows the same numbered hints as a hierarchy cue without the keyboard binding.
• Per-turn stopwatch (v2.5+) — wall-clock duration of each completed assistant turn renders as a compact pill (4.2s / 1m 12s) on the bubble's metadata footer (Mac) or below the bubble (iOS). Resumed sessions loaded from state.db show no pill — timing is captured live only.
• Git branch chip (v2.5+) — chat header shows the project's current git branch as a tinted chip alongside the project name (e.g. 📂 myproject · main). One SSH git rev-parse --abbrev-ref HEAD per session start; nil-out gracefully on non-git dirs / missing git / SSH errors. Backed by GitBranchService.
• /compress — when Hermes advertises the command via availableCommands, a one-click focus sheet appears in the toolbar.
• /steer <prompt> (v2.5+) — non-interruptive mid-run guidance. Surfaces in the slash menu as a special command; sending it doesn't flip the "Agent working…" indicator (the agent's still on its current turn) and shows a transient toast above the composer: "Guidance queued — applies after the next tool call."
• Slash-command menu — type / and a floating menu appears above the input with every command Hermes has advertised via ACP's available_commands_update, any user-defined quick_commands: from ~/.hermes/config.yaml, and any project-scoped slash commands (v2.5+) from <project>/.scarf/slash-commands/. See Slash Commands. ↑/↓ to navigate, Tab or Enter to complete, Esc to dismiss. Commands with argument hints (e.g. /compress <topic>) insert a trailing space so you can start typing the argument immediately.

Session lifecycle:

• Each new conversation creates a session via session/new (cwd = your local working directory if you set one).
• Resume an old conversation: pick from the session picker; Scarf calls session/load or session/resume depending on the state.
• Auto-reconnect — if the subprocess dies, Scarf attempts a session/resume to pick up where it left off.

Resilience (v2.5.2+, iOS-at-parity). Both Mac and iOS recover automatically when the SSH socket drops, the phone sleeps, or the network changes — Hermes keeps writing to state.db on the remote during the outage, and Scarf reattaches via session/resume (with session/load fallback) on a 5-attempt 1→2→4→8→16 s exponential backoff. After a successful reconnect, reconcileWithDB merges any messages the agent persisted while you were offline and a "Resynced N new messages" toast surfaces what changed.

• iOS specifically gains a yellow Reconnecting (n/5)… banner during recovery and a red No network banner while reachability is unsatisfied (driven by NWPathMonitor).
• iOS observes scene-phase transitions through ScarfGoCoordinator so a chat tab that was unmounted while you were on Dashboard still picks up the background → active edge and verifies channel health on resume.
• Composer drafts persist across force-quit, keyed by (serverID, sessionID) in UserDefaults; a 7-day janitor at app launch prunes stale slots.

Pagination (v2.5.2+). Initial load fetches the most recent 200 messages for a session (500 on the Mac Sessions detail view). Sessions with more on-disk history surface a "Load earlier messages" button at the top of the transcript. Pagination is keyed by message id (monotonic) so streaming-chunk timestamps that collide on the same millisecond never split a page.

Offline-tolerant snapshots (v2.5.2+). When a fresh remote state.db snapshot pull fails, Scarf falls back to the last cached copy at ~/Library/Caches/scarf/snapshots/<server-id>/state.db so Dashboard and Sessions stay viewable. The chat history reload path explicitly opts out of this fallback (forceFresh: true) — falling back there would silently hide messages the agent streamed during the outage.

Voice mode controls: PTT (push-to-talk), TTS playback, STT transcription preferences live in Settings → Voice. The chat toolbar exposes the basic toggles.

Chat density preferences (v2.5.1+, Mac)

Settings → Display → Chat density has three Scarf-local controls that change how the chat is rendered. They're independent of the Hermes config flags one section below (Show Reasoning, Show Cost, Compact) — those gate what Hermes EMITS, these gate how Scarf RENDERS what was emitted.

• Tool calls — Full card (today's expandable card per call), Compact chip (one-line tappable chip per call — kind icon + function name + status dot — opening the right-pane inspector with the same details), Hidden (per-call rows skipped; the always-visible group summary pill stays and becomes tappable so the inspector is still one click away).
• Reasoning — Disclosure box (today's yellow box), Inline (italic) (italic faded caption text inline above the reply with a small brain prefix — same data, far less vertical space), Hidden (reasoning text not rendered; per-message token count stays visible in the bubble's metadata footer).
• Chat font size — 85% to 130% slider (5% step) applied at the chat root via .environment(\.dynamicTypeSize, ...) so the message list, input bar, session info bar, and inspector pane scale together.

Defaults match today's UI exactly so existing users see no change until they opt in. Per-turn stopwatch, per-message tokens, finish reason, and timestamp stay in the bubble metadata footer in every density mode; SessionInfoBar's input/output/reasoning tokens, USD cost, model, project, and git branch are unaffected. See issues #47 and #48 for the original asks and the full preservation audit.

Streaming performance (v2.5.1)

Pre-2.5.1 long chats progressively bogged down because every streamed ACP token rebuilt the full message-group array AND every MessageGroupView / RichMessageBubble re-evaluated its body. v2.5.1 caps per-chunk work at O(1) for settled groups via Equatable + .equatable() short-circuits, plus a trailing-group patch helper that replaces the per-chunk full rebuild. ScarfGo's chat (different rendering path — LazyVStack directly over controller.vm.messages) gained an iOS-equivalent MessageBubble: Equatable. Issue #46.

iOS keyboard dismissal (v2.5.1+)

Pre-fix the chat composer's TextField had no keyboard dismissal at all — the keyboard would rise and stick, hiding the system tab bar (which iOS auto-hides while a keyboard is up) and trapping users in the Chat tab. v2.5.1 adds two redundant dismissal paths:

• .scrollDismissesKeyboard(.interactively) on the message list — drag the messages downward to collapse the keyboard with the gesture.
• A keyboard.chevron.compact.down button in the keyboard accessory toolbar above the system keyboard.

Either dismisses the keyboard, the system tab bar reappears, and the user can switch tabs again. Issue #51.

Terminal mode

The full hermes chat CLI rendered in an embedded SwiftTerm terminal:

• ANSI color and Rich formatting work as in your shell.
• WhatsApp / Signal pairing flows render their QR codes here for scanning.
• Useful when you need a feature only the CLI exposes (e.g. obscure flags, daemon management).

Cancellation

The Stop button sends session/cancel over the JSON-RPC channel. The model stops generating; any in-flight tool call completes. You can immediately send another prompt without restarting the session.

Mac 3-pane chat (v2.5)

The Mac chat surface re-laid out as a three-pane composition:

• Left pane — sessions sidebar (search + project filter + the 50 most recent sessions). Right-click any row for Rename / Delete (when Hermes advertises those CLIs).
• Middle pane — transcript (the bubbles, reasoning, tool cards described above) + composer.
• Right pane — live inspector. Surfaces git branch, project chip, model + reasoning effort, total tokens / API calls / tool calls, and the current MCP server status.

iPhone keeps a single-column transcript — three panes don't translate to phone-width screens. iPad inherits the Mac layout via SwiftUI's adaptive sizing but hasn't been polished yet (deferred per Platform Differences).

Multi-server chat

Each Mac window is bound to one server, so chat in window A talks to local Hermes while window B talks to a remote one. ScarfGo uses a single-window TabView; switching servers from the Servers list rebuilds the tab root against the new context. Sessions don't cross windows / contexts — they live on the server they were created on.

Troubleshooting

• "Spinning forever, no response" — check the Logs view for ACP errors. Common causes: missing ANTHROPIC_API_KEY (Scarf attaches a hint), rate limit, or hermes binary not on $PATH.
• Connection lost — Rich Chat surfaces this banner; click Reconnect to call session/resume.
• Permission sheet doesn't appear — make sure Hermes's approval_mode in config.yaml is set so it asks (not auto-approve).

Related pages

• ACP Subprocess for the protocol internals.
• Memory & Skills for editing what Hermes knows about you.
• Settings — Voice tab for TTS/STT configuration (Settings is documented there).

---

Last updated: 2026-04-27 — Scarf v2.5.1 (chat density preferences + streaming O(n)-per-token fix + iOS keyboard dismissal)