madeye / madeye/gterm

Discussion: native dashboard for herdr agents over SSH (Herd view)

Open
#36 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.