gooneyryan/scarf
1
0
Fork 0
mirror of https://github.com/awizemann/scarf.git synced 2026-05-10 10:36:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(wiki): add ScarfGo page with M7/M8/M9 roadmap + pass-1 Known Issues

Alan Wizemann
2026-04-24 12:47:30 +02:00
parent f65fd5df4d
commit 39ae516381
3 changed files with 109 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Home.md
+1
@@ -13,6 +13,7 @@ A native macOS companion app for the [Hermes AI agent](https://github.com/hermes
- [Project Templates](Project-Templates) — `.scarftemplate` bundles, install / export / author
- [Architecture Overview](Architecture-Overview) — MVVM-F, services, transport
- [Servers & Remote](Servers-and-Remote) — adding remote Hermes hosts over SSH
- [ScarfGo](ScarfGo) — the iPhone companion (on-the-go agent management)
- [Localization](Localization) — supported languages + how to contribute a new one
- [Release Notes Index](Release-Notes-Index) — every version's notes
- [Wiki Maintenance](Wiki-Maintenance) — how this wiki is edited and kept in sync
Roadmap.md
+1
@@ -18,6 +18,7 @@ These are the unblocked candidates for 2.1 / 2.2:
## Medium-term
- **[ScarfGo](ScarfGo) — iPhone companion.** On-the-go remote agent management. Pre-TestFlight dogfood as of 2026-04-24 — see the dedicated page for full roadmap (M7 stabilization → M8 UX density → M9 multi-server + push + project-chat → M10 TestFlight) and [Known Issues](ScarfGo#known-issues).
- **Custom commands palette.** A ⌘K-style palette for quick actions across all sidebar sections.
- **Better Insights.** Rolling heatmaps, drill-downs from any chart, exportable summaries.
- **Voice mode polish.** Speaker selection, partial-results display, better handling of long-form dictation.
ScarfGo.md
+107
@@ -0,0 +1,107 @@
# ScarfGo — the iOS companion
ScarfGo is the on-the-go iPhone companion to [Scarf](Home). Its scope is deliberately narrower than the Mac app: **remotely manage and interact with a running Hermes agent** from your phone. It is **not** a feature-parity port — Mac handles the full operator surface; ScarfGo handles what's valuable away from a desk.
**Current state:** pre-TestFlight dogfood. M6 milestone merged; pass-1 smoke test has completed against a local Hermes install. See [Known Issues](#known-issues) below before filing bugs.
**Tech stack:**
- **Transport:** pure-Swift SSH via [Citadel](https://github.com/orlandos-nl/Citadel) 0.12.x — no OpenSSH client subprocess (iOS sandbox).
- **Shared core:** `ScarfCore` SPM package — Models / Transport / Services / ViewModels portable across macOS and iOS, unit-tested on Linux in CI.
- **iOS-only code:** `ScarfIOS` package (Citadel glue, Keychain key storage) + `Scarf iOS/` SwiftUI views.
- **Target:** iPhone, iOS 18+. iPad / macCatalyst deferred.
## What's shipped today (M6)
| Feature | Behavior |
|---|---|
| **Onboarding** | 8-step: host form → generate or import Ed25519 → show public key → you add to `~/.ssh/authorized_keys` → test probe → done. Single server v1 — multi-server in M9. |
| **Dashboard** | Session count, message count, tool-call count, token totals, last 5 sessions. Pulled from remote `~/.hermes/state.db` via `sqlite3 .backup` + SFTP download (WAL-safe snapshot). |
| **Chat** | Real-time ACP over a dedicated SSH exec channel. Markdown, tool-call cards, permission sheets, reasoning disclosure, streaming. **No** embedded terminal — rich chat only. |
| **Memory** | Read + write MEMORY.md, USER.md, SOUL.md (SOUL is in the Personalities feature on Mac; on iOS we fold it in here because you rarely want them separately on a phone). |
| **Cron** | List jobs, toggle enabled/disabled, edit schedule / prompt / skills / delivery route, add new, swipe-to-delete. Writes `~/.hermes/cron/jobs.json` atomically. |
| **Skills** | Read-only browse — categories + skill files per skill. |
| **Settings** | Read-only view of `config.yaml` grouped by section. Editing deferred — see M9. |
## Deliberately not on ScarfGo
- **Analytics features** (Activity, Logs, Health, Insights) — belong on the Mac where screen real-estate supports them.
- **Full-surface configuration** (CredentialPools, Gateway, Templates, MCP Servers, Platforms, Plugins, Profiles, Personalities, Tools, Webhooks, QuickCommands) — config flows live on the Mac. On the go you want to run and interact, not configure.
- **Terminal mode** (embedded SwiftTerm) — out of scope for a chat-first companion.
- **Local Hermes** — iOS can't spawn subprocesses (sandbox). ScarfGo is remote-only by design.
## Roadmap
### M7 — Stabilization (pre-TestFlight)
Bug fixes only, no new features. Unblocks the first internal TestFlight build. See the full issue list in [Known Issues](#known-issues).
### M8 — UX density pass
ScarfGo is a developer tool; it needs to show more on-screen than Apple's spacious defaults. Research-driven changes:
- Migrate root navigation from "Dashboard-is-hub" to a `TabView` with `.sidebarAdaptable` style — Chat, Dashboard, Memory, More. Primary nav stops hiding below the fold.
- Clamp Dynamic Type at scene root: `.dynamicTypeSize(.xSmall ... .accessibility2)`. Semantic fonts + `@ScaledMetric`.
- Tighten list density — `.listRowSpacing(0)` + 6pt vertical insets + `.defaultMinListRowHeight(36)`, preserving 44pt hit targets via `.contentShape(Rectangle()).frame(minHeight: 44)`.
- Chat code blocks: horizontal scroll inside bubble, never wrap, `maxHeight: 240` + Expand.
- Chat tool calls: `DisclosureGroup` collapsed; title = action + elapsed ms.
- Chat scroll anchoring: iOS 18 `.defaultScrollAnchor(.bottom, for: .sizeChanges)` + suspend auto-follow on user scroll-up + "↓ new messages" pill.
- Message/row actions via `.contextMenu` — not visible buttons.
- Sheets with custom peek detents (`.presentationDetents([.height(180), .large])`) — never `.medium`.
### M9 — On-the-go essentials
Features that only make sense on mobile, in priority order:
1. **Multi-server support.** Root becomes a server list (nickname + host + status pill). Each server has two actions: **Disconnect** (soft — closes live transport, keeps Keychain key + config, one-tap to reconnect) and **Forget** (destructive — wipes credentials, re-onboards). The underlying transport factory is already `ServerID`-keyed; changes are storage layer + root nav + onboarding entry point.
2. **Project-scoped chat.** The `+` button in Chat opens a picker: "Quick chat" (default) or "In project…" — SFTP-read `~/.hermes/scarf/projects.json`, pick one, SFTP-write the scarf-managed project-context block into `<project>/AGENTS.md`, spawn `hermes acp` with `cwd = project.path`. After session id comes back, SFTP-write the attribution row into `session_project_map.json`. Unlocks the iOS parity of `ProjectAgentContextService` + `SessionAttributionService`.
3. **Session resume.** Dashboard's Recent Sessions list becomes tappable — taps call `ACPClient.loadSession(id:)` instead of starting a new session. Resume a conversation that was started on a Mac, continue it on the phone.
4. **APNs push — cron completion + pending permissions.** Notification for "your cron just ran" or "your agent needs approval to run X." The client half is ~200 LOC; the Hermes-side sender is a separate upstream feature.
5. **Lock-screen quick-approve.** Notification action button for "Approve" / "Deny" on pending permissions so the agent keeps running while you're away from the app.
6. **Scoped Settings editor.** Not a generic YAML round-trip editor — a curated set of high-value fields (model / provider / approval mode / max turns / display toggles) that save via `hermes config set <key> <value>` over SSH exec. Hermes owns the YAML round-trip; Scarf just picks values.
### M10 — TestFlight
App Store Connect + provisioning profile + internal TestFlight group of 1 (Alan). Public TestFlight after 2–3 real sessions on a real iPhone without crashes.
## Known Issues
All tracked from the 2026-04-24 pass-1 smoke test. This list is the truth about what's broken today — filed publicly in the interest of transparency. A ✅ means the fix has already landed on the `scarf-mobile-development` branch.
### Blocking TestFlight — must fix in M7
| # | Summary | Scope | Status |
|---|---|---|---|
| 1 | **Primary navigation hidden below Dashboard fold.** Chat / Memory / Cron / Skills / Settings links live as the 4th section in a `List` — users can't reach any feature without scrolling. Needs `TabView` root (see M8). | ScarfGo | Open (deferred to M8) |
| 2 | **Non-retryable provider errors → perpetual spinner.** If Hermes returns HTTP 404 from the LLM provider, the iOS UI shows "Agent is working…" forever. The error is flowing through ACP stderr but isn't surfaced to the user. Needs a banner with retry / settings affordance. | ScarfGo | Open |
| 3 | **No connecting feedback when entering Chat.** 1-second load is silent — no spinner, no "Connecting to agent…". | ScarfGo | Open |
| 4 | **`isAgentWorking` doesn't clear after primary response.** Spinner flips off only on the ACP `promptComplete` event; auxiliary post-work (title generation) delays it. Main response is long since done. Fix: clear on assistant-stream-end, keep a subtle secondary indicator for post-work. | ScarfGo | Open |
| 5 | **ACP command missing PATH prefix.** SSH exec runs a non-interactive shell whose PATH is `/usr/bin:/bin:/usr/sbin:/sbin`. `~/.local/bin/hermes` (pipx default) wasn't on PATH; ACP died with `command not found: hermes`. Fixed by prepending common install locations to PATH. | ScarfGo | ✅ Fixed |
| 6 | **SFTP `~` tilde not expanded.** Every Memory / Cron / Skills / Settings read used paths like `~/.hermes/memories/MEMORY.md`. SFTP treats `~` as a literal character, not a home-dir alias, so every read silently returned nil. Fixed: added cached `resolveHome()` on `ConnectionHolder` + a `resolveSFTPPath()` helper applied to every SFTP entry point. This was the root cause of multiple "empty content" bugs. | ScarfGo | ✅ Fixed |
| 7 | **No loading state on Memory editor.** The editor _has_ a ProgressView code path, but since SFTP silently returned nil, `isLoading` flipped false instantly with empty content — no spinner, no error, just blank. Exposed by #6. | ScarfGo | Needs follow-up after #6 |
| 8 | **`ServerContext.readText` swallows errors with `try?`.** Masks transport failures as "empty file." Refactor to throw or return `Result`. | Cross-platform | Open |
| 9 | **TextEditor keyboard obscures cursor on bottom edit.** Tapping near the bottom of Memory editor scrolls content under the keyboard; cursor invisible. Needs `ScrollView` + `ScrollViewReader` + keyboard-aware padding. | ScarfGo | Open |
| 10 | **Save confirmation not visible.** The "Saved" pill is coded but positioned at `.bottom` with only 16pt padding — keyboard covers it, auto-dismisses after 1.5s. Reposition or raise above keyboard via `.safeAreaInset(edge: .bottom)`. | ScarfGo | Open |
| 11 | **Cron schedule + next-run shown as machine formats.** List shows `0 */6 * * *` and `2026-04-24T18:00:00+02:00`. Needs a `CronScheduleFormatter` in ScarfCore (common patterns → human readable) + `.relative(presentation: .numeric)` for next-run. Fix both macOS and ScarfGo simultaneously. | Cross-platform | Open |
| 12 | **"Disconnect" is factory reset.** Button wipes Keychain key + config, forcing re-onboarding including key regeneration + re-append to `authorized_keys`. Interim fix: rename to "Forget this server" with destructive red styling + confirmation alert. Proper fix: soft Disconnect vs. hard Forget (M9 multi-server). | ScarfGo | Open (rename pending) |
### Cross-platform (fix on Mac too)
- **Model picker accepts unknown models for a given provider.** Configured `nous` provider + `claude-haiku-4-5-20251001` — Nous doesn't serve that model, runtime 404. Validate model ID against the provider's catalog at save time. Affects all providers with finite catalogs (Nous Portal, OpenAI Codex, Qwen OAuth). This is the underlying cause of bug #2.
### Hermes-side (upstream, not ours)
- Auxiliary `title_generation` appears to hang when the main provider returns a 404 — likely retries the failed call. Worth filing upstream; causes bug #4 to manifest.
## Reporting issues
- **Bugs:** <https://github.com/awizemann/scarf/issues> — tag with `component: ios` / `component: scarfgo`.
- **Feature requests:** same, tag with `feature: ios`.
- **Security / credential handling concerns:** use the repo's security policy.
## For contributors
See [Architecture Overview](Architecture-Overview) for how ScarfCore + ScarfIOS fit together. The `scarf-mobile-development` branch is the working branch; pass-1 and all M7 fixes land there first, merge to `main` once M7 closes.
---
_Last updated: 2026-04-24 — post pass-1 smoke test_