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

docs: index v2.0.2 release + correct ControlPath documentation after #19/PR #20 fix

Alan Wizemann
2026-04-20 15:57:34 -07:00
parent 7aeb1ff17f
commit 9760761dc8
5 changed files with 16 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Hermes-Paths.md
+2 -1
@@ -29,6 +29,7 @@ Chat does not go through the filesystem. It is a subprocess: `hermes acp` (local
| Path | What lives here |
|---|---|
| `~/Library/Caches/scarf/snapshots/<server-id>/` | Atomic `state.db` snapshots pulled from remote servers via `sqlite3 .backup` |
| `/tmp/scarf-ssh-<uid>/` | SSH ControlMaster sockets (per-host `%C` hash). Mode 0700; per-uid suffix isolates between local users. Lives under `/tmp` to stay within macOS' 104-byte Unix domain socket path limit. |
| `~/Library/Preferences/com.scarf.app.plist` | App preferences + the server registry |
## Log line format
@@ -36,4 +37,4 @@ Chat does not go through the filesystem. It is a subprocess: `hermes acp` (local
Hermes log lines may carry an optional `[session_id]` tag between the level and the logger name. `HermesLogService.parseLine` treats the session tag as an optional capture group, so older untagged lines still parse correctly.
---
_Last updated: 2026-04-20 — Scarf v2.0.1_
_Last updated: 2026-04-20 — Scarf v2.0.2_
Home.md
+2 -2
@@ -2,7 +2,7 @@
A native macOS companion app for the [Hermes AI agent](https://github.com/hermes-ai/hermes-agent). Full visibility into what Hermes is doing, when, and what it creates — across one local install or many remote ones.
**Latest release:** [v2.0.1](https://github.com/awizemann/scarf/releases/tag/v2.0.1)
**Latest release:** [v2.0.2](https://github.com/awizemann/scarf/releases/tag/v2.0.2)
**Targets Hermes:** v0.9.0 (v2026.4.13)
## Quick links
@@ -30,4 +30,4 @@ Scarf 2.0 is a multi-window app — one window per Hermes server, local or remot
Open-source (MIT), 160+ stars, actively maintained. See [Roadmap](Roadmap) for what's coming.
---
_Last updated: 2026-04-20 — Scarf v2.0.1_
_Last updated: 2026-04-20 — Scarf v2.0.2_
Release-Notes-Index.md
+3 -2
@@ -4,7 +4,8 @@ Every Scarf release in chronological order. The notes themselves live in `releas
| Version | Date | GitHub release | Notes file |
|---|---|---|---|
| **v2.0.1** | 2026-04-20 | [v2.0.1](https://github.com/awizemann/scarf/releases/tag/v2.0.1) | [`releases/v2.0.1/RELEASE_NOTES.md`](https://github.com/awizemann/scarf/blob/main/releases/v2.0.1/RELEASE_NOTES.md) |
| **v2.0.2** | 2026-04-20 | [v2.0.2](https://github.com/awizemann/scarf/releases/tag/v2.0.2) | [`releases/v2.0.2/RELEASE_NOTES.md`](https://github.com/awizemann/scarf/blob/main/releases/v2.0.2/RELEASE_NOTES.md) |
| v2.0.1 | 2026-04-20 | [v2.0.1 (draft)](https://github.com/awizemann/scarf/releases/tag/v2.0.1) | [`releases/v2.0.1/RELEASE_NOTES.md`](https://github.com/awizemann/scarf/blob/main/releases/v2.0.1/RELEASE_NOTES.md) |
| **v2.0.0** | 2026-04 | [v2.0.0](https://github.com/awizemann/scarf/releases/tag/v2.0.0) | [`releases/v2.0.0/RELEASE_NOTES.md`](https://github.com/awizemann/scarf/blob/main/releases/v2.0.0/RELEASE_NOTES.md) |
| **v1.6.2** | 2026-04 | [v1.6.2](https://github.com/awizemann/scarf/releases/tag/v1.6.2) | [`releases/v1.6.2/RELEASE_NOTES.md`](https://github.com/awizemann/scarf/blob/main/releases/v1.6.2/RELEASE_NOTES.md) |
| **v1.6.1** | 2026-04 | [v1.6.1](https://github.com/awizemann/scarf/releases/tag/v1.6.1) | [`releases/v1.6.1/RELEASE_NOTES.md`](https://github.com/awizemann/scarf/blob/main/releases/v1.6.1/RELEASE_NOTES.md) |
@@ -30,4 +31,4 @@ When `scripts/release.sh <version>` completes a full (non-draft) release, this p
This is one of the [wiki update triggers](Wiki-Maintenance) that future Claude Code sessions will follow automatically.
---
_Last updated: 2026-04-20 — Scarf v2.0.1_
_Last updated: 2026-04-20 — Scarf v2.0.2_
Transport-Layer.md
+5 -3
@@ -66,7 +66,7 @@ The SSH option set is constructed by `sshArgs(extra:)`:
```
-o ControlMaster=auto
-o ControlPath=~/Library/Caches/scarf/ssh/%C
-o ControlPath=/tmp/scarf-ssh-<uid>/%C
-o ControlPersist=600 # keep alive 600s after last use
-o ServerAliveInterval=30 # keepalive every 30s
-o ServerAliveCountMax=3 # disconnect after 3 missed
@@ -76,7 +76,9 @@ The SSH option set is constructed by `sshArgs(extra:)`:
-o BatchMode=yes # ssh-agent only; never prompt
```
`%C` hashes `(host, user, port)` — multiple Scarf windows for the same host share one socket. `closeControlMaster()` issues `ssh -O exit` for clean shutdown.
`%C` hashes `(local user, host, port, remote user)` — multiple Scarf windows for the same host share one socket. `closeControlMaster()` issues `ssh -O exit` for clean shutdown.
The socket dir lives under `/tmp` (not `~/Library/Caches/`) because macOS' Unix domain socket path limit (`sun_path` in `<sys/un.h>`) is 104 bytes including NUL, and the Caches path plus `%C`'s 64-char hash exceeds that for users with longer `$HOME` strings (issue [#19](https://github.com/awizemann/scarf/issues/19), fixed in v2.0.2). The per-uid suffix isolates sockets between local users in the shared `/tmp`, and `ensureControlDir` enforces 0700 perms via POSIX `mkdir(0700)` plus an `lstat` ownership check (refuses to use a pre-existing dir owned by someone else). Stale sockets older than 30 minutes are swept on app launch via `SSHTransport.sweepStaleControlSockets` so crashed-master orphans don't accumulate until reboot.
### Path handling
@@ -121,4 +123,4 @@ sqlite3 '/tmp/scarf-snapshot-XYZ.db' "PRAGMA journal_mode=DELETE;"
See [Servers & Remote](Servers-and-Remote) for setup and troubleshooting.
---
_Last updated: 2026-04-20 — Scarf v2.0.1_
_Last updated: 2026-04-20 — Scarf v2.0.2_
Uninstalling.md
+4 -3
@@ -14,11 +14,12 @@ That's the minimum. Scarf is gone.
If you want a complete uninstall, also remove:
```bash
rm -rf ~/Library/Caches/scarf # remote SQLite snapshots, ssh ControlMaster sockets
rm -rf ~/Library/Caches/scarf # remote SQLite snapshots
rm -rf /tmp/scarf-ssh-$(id -u) # ssh ControlMaster sockets (auto-cleared on reboot)
rm -f ~/Library/Preferences/com.scarf.app.plist # app preferences + server registry
```
The cache holds atomic SQLite snapshots pulled from remote Hermes hosts and SSH ControlMaster sockets — both are safe to delete; Scarf rebuilds them on demand.
The Caches dir holds atomic SQLite snapshots pulled from remote Hermes hosts. The `/tmp` dir holds SSH ControlMaster sockets — both are safe to delete; Scarf rebuilds them on demand. (As of v2.0.2 the ssh sockets live under `/tmp` rather than Caches, to stay within the 104-byte macOS Unix domain socket path limit. Older versions kept them at `~/Library/Caches/scarf/ssh/`.)
## What Scarf does NOT touch
@@ -35,4 +36,4 @@ To uninstall Hermes itself, follow the Hermes documentation — that's a separat
Just for completeness: the GitHub wiki at <https://github.com/awizemann/scarf/wiki> is a separate git repo from the main one. Uninstalling the app has no effect on the wiki.
---
_Last updated: 2026-04-20 — Scarf v2.0.1_
_Last updated: 2026-04-20 — Scarf v2.0.2_