Discussion: native dashboard for herdr agents over SSH (Herd view)
Nobody has claimed this yet.
- Dominant language
- Swift
- Stars
- 69
- Forks
- 6
- Avg merge
- 7m
- Merged PRs (30d)
- 6
Description
## What
I'd like to add a native **agent dashboard** to gterm so it can act as a mobile control surface for [herdr](https://github.com/ogulcancelik/herdr) (a Rust agent multiplexer people run on their own servers). In one sentence: connect to your VPS over SSH, see every AI agent herdr is running in a native sidebar (idle / working / blocked / done), tap one to focus it in the terminal, and answer permission prompts with native Approve/Deny buttons.
**No cloud relay, no new dependencies, SSH only.**
## Why I'm opening this first
Before any UI lands I'd like to know whether this is a feature you'd consider merging, and any constraints you'd put on it. It is designed from the start to be invisible to non-herdr users: everything is behind a runtime "herdr detected on this host" gate (a version-checked `ping` as the first request); if herdr isn't there, nothing changes.
## How it works (architecture is settled, details open)
- One authenticated SSH connection, **two kinds of child channels**: the existing PTY (herdr's own TUI keeps rendering in the ghostty surface — the terminal experience is untouched) plus **exec child channels** bridging to herdr's Unix-domain JSON socket via `socat STDIO UNIX-CONNECT:` (with a fallback probe chain; herdr may grow `herdr api proxy` upstream — I'll PR that there).
- The native sidebar talks NDJSON JSON-RPC to herdr's API socket (protocol 16, version-gated, lenient decoding — a protocol bump degrades the feature instead of crashing).
- Tap-to-focus is just `agent.focus` over the control channel; herdr moves focus server-side and the TUI in the terminal follows.
- Approvals show the real prompt text (`agent.read`, ANSI stripped) and re-verify the agent is still blocked before injecting any keys. No auto-approve, ever.
- All feature code is hand-written against herdr's published JSON schema (clean-room: gterm stays MIT, herdr's AGPL source is never copied or vendored). Zero new third-party dependencies — rides the existing NIO/NIOSSH stack and SwiftUI.
- Every Herd-view failure is non-fatal: the terminal keeps working if the bridge never comes up.
## Status
Phase 1 (protocol client + SSH exec-channel bridge, no UI) is done and tested: 46 new hermetic unit tests, full suite green, plus a live smoke test against a real VPS (gate, agent list, focus, events). Branch: [`feature/herd-view` on my fork](https://github.com/ebair-admin/gterm/tree/feature/herd-view) (commits are small and per-task).
Planned next: sidebar + session store, then native approvals, then hardening — each behind the detection gate, each with tests.
## Questions
1. Would you take this as a PR (split into small reviewable chunks), or would you rather it stayed a fork?
2. Any UI constraints for the sidebar on iPhone (slide-over drawer) vs iPad (persistent column)?
3. The PTY currently opens a plain login shell — the plan adds an optional per-host "run on connect" string (e.g. `herdr`). Is that acceptable, or do you have a different preference for launch commands?
Happy to adjust scope, naming, or phasing — and no worries if this isn't a fit; a fork works too.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the feature/herd-view branch and its 46 hermetic unit tests for the completed protocol client and SSH exec-channel bridge. The proposed follow-up work is the sidebar and session store, native approvals, and hardening, but the issue first needs maintainer agreement on scope, UI constraints, and launch-command behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- mobile
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 28/100