Hermes Version Compatibility

Scarf reads Hermes's SQLite database directly and parses CLI output from hermes status, hermes doctor, hermes tools, hermes sessions, hermes gateway, and hermes pairing. It also speaks ACP (hermes acp) for chat. Compatibility comes from automatic schema detection plus tolerant parsing.

Currently targeted

Scarf 2.6.x targets Hermes v0.12.0 (v2026.4.30), bumped from Scarf 2.5's v0.11.0 target. v0.12.0 is the recommended minimum to get every v2.6 feature lit up: the autonomous Curator (sidebar / panel) needs hermes curator, multimodal image input in chat needs ACP's prompt_capabilities.image, the 5 new inference providers (GMI Cloud, Azure AI Foundry, LM Studio first-class, MiniMax OAuth, Tencent TokenHub) need their entries in the v0.12 HERMES_OVERLAYS map, the read-only Kanban needs hermes kanban list --json, the Skills v0.12 surface (URL install, reload, OFF pill) needs hermes skills install <url> / audit and skills.disabled in config.yaml, cron --workdir needs the v0.12 cron schema, and auxiliary.curator is a new aux task that replaces the removed flush_memories task. Every one of these surfaces is capability-gated through HermesCapabilities (parses semver + YYYY.M.D from hermes --version once per server) — on a v0.11 host, Scarf 2.6 looks identical to Scarf 2.5.2 and the new affordances are hidden. auxiliary.flush_memories is preserved on v0.11 hosts (inverse gate via hasFlushMemoriesAux).

The v2.5 baseline still applies: /steer, messages.reasoning_content / sessions.api_call_count columns, SKILL.md frontmatter chips, and hermes memory reset all require v0.11+. On earlier Hermes releases, Scarf 2.6 still runs — /steer is harmless on older agents (treated as an unknown command), v0.11 DB columns silently degrade to nil/0 via HermesDataService.hasV011Schema, and the new skills (design-md, spotify) only appear if installed.

Verified versions

Hermes	Date	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
v0.10.0	2026-04-16	Verified (Tool Gateway introduced)
v0.11.0	2026-04-23	Verified
v0.12.0	2026-04-30	Verified — current target (Curator, multimodal ACP, 5 new providers, Teams + Yuanbao, Kanban, Skills URL install / disable / curator pin, cron --workdir, auxiliary.curator, prompt_caching.cache_ttl, redaction toggle, runtime metadata footer, Piper TTS, Vercel terminal)

How compatibility is maintained

SQLite schema detection. HermesDataService probes for v0.7+ columns (reasoning_tokens, actual_cost_usd, cost_status, billing_provider) and v0.11+ columns (sessions.api_call_count, messages.reasoning_content) at open time. The v0.11 flag (hasV011Schema) only flips true when both new columns are present — partial-migration DBs (sessions migrated, messages not yet) stay on the v0.7 path to avoid runtime "no such column" errors. When absent, model fields stay nil/0 and the views render placeholders. Older databases keep working; newer columns light up automatically once the database has them.

Log line format. Hermes log lines may carry an optional [session_id] tag between the level and the logger name. HermesLogService.parseLine treats the tag as an optional capture group, so older untagged lines still parse.

ACP capability gates. Rich Chat checks for session/list and session/resume support; if Hermes doesn't advertise them, the resume / picker UI degrades gracefully (you can still chat, just with reduced session navigation).

CLI output parsing. Where Scarf parses hermes CLI output (Health, Tools, Pairing), the parsers tolerate field reordering and unknown lines.

HERMES_OVERLAYS mirror. ModelCatalogService.overlayOnlyProviders mirrors the 6 overlay-only entries from hermes-agent/hermes_cli/providers.py (Nous Portal, OpenAI Codex, Qwen OAuth, Google Gemini CLI, GitHub Copilot ACP, Arcee). When Hermes adds a new overlay-only provider, Scarf needs a release to surface it in the picker — but existing overlays silently pick up base-URL and auth-type refinements without a Scarf release, because only the identity is mirrored, not the full overlay struct.

Device-code OAuth flow (v0.10.0+). Nous Portal sign-in goes through hermes auth add nous --no-browser as a subprocess (see NousAuthFlow). Scarf regex-extracts the device-code block from stdout and auto-opens the verification URL via NSWorkspace. On success, it re-reads ~/.hermes/auth.json to confirm providers.nous.access_token landed. Any change to Hermes's To continue: / 1. Open: / 2. If prompted, enter code: output shape would break the parser — low-risk because it's been stable across v0.9 and v0.10, but worth a smoke test on future Hermes releases.

iOS exec channel — non-interactive PATH (v2.5+). CitadelServerTransport runs commands over Citadel's raw exec channel which doesn't source the user's shell rc files, so non-interactive sessions land with a stripped PATH (typically /usr/bin:/bin). pipx installs hermes at ~/.local/bin/hermes, and many sub-tools (git, curl, python) live in homebrew prefixes that the remote sshd would otherwise add via login-shell init. Mac's OpenSSH sshd handles this transparently; Citadel does not. v2.5 inline-prepends PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH" on every iOS-routed runProcess so bare hermes resolves AND any subprocess it spawns can still find its tools. If you install hermes at an unusual path on a remote host (custom virtualenv, system-managed install dir), set the Hermes binary hint field when adding the server to point at the absolute path.

iOS exec output capture (v2.5+). Citadel's executeCommand API throws CommandFailed on any non-zero exit and discards the captured stdout buffer in the throw path. hermes skills browse happens to print its full table and then exit non-zero on some hosts — pre-2.5 iOS got nothing while Mac (Foundation Process) got the full table with exitCode=1. v2.5 drives executeCommandStream directly, drains stdout + stderr regardless of outcome, and recovers the exit code from the CommandFailed catch — feature parity with Mac for any Hermes command that emits useful output before exiting non-zero.

v0.11 CLIs not yet adopted

Hermes v0.11 added a handful of new top-level CLIs Scarf doesn't yet drive directly: hermes plugins, hermes webhook, hermes insights, hermes logs, hermes dashboard, hermes completion. Scarf still reads the underlying files (~/.hermes/plugins/, ~/.hermes/webhooks/, etc.) directly today, which keeps working. Switching to the canonical CLIs is forward-compatible work for v2.6+.

hermes memory reset is surfaced as the Reset memory… toolbar action on Memory views (Mac + iOS) with a destructive-confirmation dialog.

hermes profile is half-adopted as of v2.5.1. Scarf doesn't yet drive hermes profile create / use / delete from in-app UI (still file-based, still local for now), BUT Scarf v2.5.1+ respects the active profile by reading ~/.hermes/active_profile at path-resolution time via HermesProfileResolver. So hermes profile use coder on the host followed by a Scarf relaunch correctly reads ~/.hermes/profiles/coder/state.db, config.yaml, sessions, memory, cron, etc. See Projects & Profiles for the full profile model. In-app profile switching (writing active_profile from a UI control) is a separate v2.6+ feature — handling running ACP processes through a profile switch is more involved than just flipping a file.

What breaks across major Hermes versions

If Hermes ships a major release that changes:

Database schema — columns dropped, table renames — Scarf may need a release. Expected to be infrequent and called out in Hermes release notes.
ACP method names or message shapes — chat would break. Scarf would ship an update with the new methods supported alongside the old.
CLI output format — Health / Tools / Pairing would degrade. Often Scarf can ship a parser update independently.

When in doubt, check the Health view for compatibility warnings (Scarf surfaces the Hermes version it sees and flags mismatches with what it was tested against).

Reporting a compatibility issue

If a new Hermes release breaks something in Scarf, please file an issue including:

Output of hermes --version.
Scarf version (Settings → General → About).
The specific view that's broken and what's wrong.
The relevant log snippet from ~/.hermes/logs/errors.log (filter sensitive content first).

Last updated: 2026-04-27 — Scarf v2.5.1 + Hermes v0.11.0 (active_profile awareness)

Getting Started

ScarfGo (iOS)

User Guide

Architecture

Developer Guide

Reference

Troubleshooting

Slow Chat Startup

Contributing

Release History

Legal & Support

Wiki edited via the local .wiki-worktree/ clone. See Wiki Maintenance for the workflow. Last sync: 2026-04-20.