Heeler: an iOS agent console for herdr over SSH

The gap Heeler fills between a long-running agent and a phone

Coding agents are long-running processes. You start one, it works, it stops and waits for a decision, and nothing tells you. If you are away from the machine, the agent sits idle until you get back to a terminal. Heeler's answer is a native iOS console: one list of every agent on every machine you have paired, sorted so that blocked agents come first, filterable by host, and updated live. The README describes it as "a native dashboard of every coding agent running on your machines, sorted by who needs you."

The audience is narrow and specific. You need herdr running on the remote side, SSH access to that machine, and an iPhone or iPad on iOS 18 or later. Heeler is not a general SSH client that happens to show agents, and it is not a way to run agents without herdr. The README lists the prerequisites plainly: Node 20 or newer, herdr 0.7.5 or newer, and an OpenSSH server with Remote Login enabled. If you run agents in a browser tab or a desktop IDE and never leave the desk, Heeler has nothing to add.

How Heeler talks to herdr: stream-local channels, not a server

The transport is the part worth understanding before installing anything. Heeler does not ship a daemon, a proxy, or a cloud service. It speaks herdr's JSON API over SSH. Each request opens a direct-streamlocal channel onto a Unix socket at herdr.sock, and one long-lived channel carries the event stream that keeps the console current. Interactive terminals are a third path: Heeler runs herdr agent attach --takeover on an SSH PTY.

That design has a direct consequence. The SSH server must allow stream-local forwarding, which the README notes is the OpenSSH default and says onboarding calls out when it is disabled. If your sshd_config turns it off, or a hardened bastion strips it, the app cannot reach the socket and the console stays empty. The payoff is that there is nothing new to expose: no port to open, no extra package on the host, no server-side change beyond installing the herdr plugin.

For machines that are not routable, Heeler supports an SSH Jump Host, and the README points to two guides, one a step-by-step VPS jump host setup and one covering architecture, security boundaries, and a VPS runbook. It also states that keys are verified at both hops. The repository keeps the reasoning in docs/adr/, and the README admits the transport story "is not obvious", which is a fair warning that this is the part to read rather than skim.

Installing the herdr plugin and pairing a machine by QR code

On the machine that already runs herdr, install the Heeler plugin and invoke its pairing action. The README gives both commands verbatim:

herdr plugin install ZingerLittleBee/Heeler/plugin --ref main --yes
herdr plugin action invoke heeler.pair

The second command prints a Pairing Code as a QR code. Scan it from the Heeler app and the machine is added as a Host. According to the README, the code carries the addresses, the host key fingerprint, and SSH key enrollment, which means the fingerprint is pinned at pairing time rather than trusted on first connection.

Key handling is worth noting because it is unusual for a mobile client: the README states that keys are generated on device and that private keys stay in the Keychain. The same plugin delivers encrypted notifications once you enable them for that Host in the app.

If you would rather build the app yourself, the Makefile is the entry point. Its header comment lists the two common flows, and the targets read from the connected device:

make install
make install-ipad

Both build Debug and deploy to the first physical iPhone or iPad that devicectl reports, unless you override DEVICE or DEVICE_IPAD with a UUID. For a simulator run, the Makefile exposes sim and sim-ipad targets with SIM and SIM_IPAD variables defaulting to an iPhone 17 and an iPad Pro 13-inch (M5).

The Composer, Direct Input, and the libghostty terminal

Typing into an agent from a phone is the part most mobile terminals get wrong, and Heeler splits the problem in two. The Composer is a local draft area: you write with the full iOS keyboard, including autocorrect, IME, and dictation, and send the complete message once. Nothing reaches the agent until you press Send. The tools keyboard adds agent control keys, agent Skills, reusable Snippets, and terminal appearance controls.

The terminal itself is rendered by libghostty through libghostty-spm, with the README listing native scrollback, momentum touch scrolling that also drives full-screen TUIs, long-press selection, takeover of a stale terminal owner, and web links collected quietly for later. A separate Terminal view opens a plain shell in the agent's directory, with Text and Keys modes and one reused tab per Workspace.

Attachments go over SFTP, up to 64 MiB per photo or file, and the app inserts the resulting path into the draft rather than pasting bytes. Two other features are easy to miss in the feature list: Worktrees, which starts an agent on a clean checkout of the workspace's repo, and appearance options covering System, Light, or Dark, 30 terminal themes with separate light and dark slots, bundled JetBrains Mono and IBM Plex Mono, and pinch to zoom.

Notifications, Live Activities, and what the relay can see

Push is where a client like this usually leaks data. Heeler's README states that notifications fire when an agent goes Blocked or Done, that they are end-to-end encrypted, and that the relay can never read the content, with PRIVACY.md as the reference. Live Activities put a lock-screen or Dynamic Island banner that tracks agents in real time.

The honest reading is that this is a claim about the relay's visibility, not a claim that no metadata exists. The README does not describe what the relay operator can observe about timing, device tokens, or which host an event came from. If your threat model includes a push provider seeing when your agents transition state, PRIVACY.md is the document to read before enabling notifications, and the app does not require them: the console works over SSH alone. The plugin is what delivers the encrypted notifications, so notification support and plugin installation are coupled.

Where Heeler is the wrong tool

The hard constraint is herdr. Heeler is a companion app, and its own description says so. If your agents run under a different orchestrator, or you launch them by hand in tmux, there is no adapter layer here and the console will show nothing. There is no documented generic SSH mode that lists arbitrary processes.

The second constraint is platform. The repository is Swift with SwiftUI, targeting iOS 18 and later on iPhone and iPad. There is no Android client, no web UI, and no desktop app in the top-level layout, which contains Sources/, Tests/, Packages/, plugin/, relay/, and docs/ but no cross-platform front end. If your team is not on Apple hardware, this is not a candidate regardless of how well the herdr integration fits.

The third is distribution. The README states the app is on the App Store but "not yet available in every country or region", and that where it is missing the TestFlight build stays available. Availability can therefore depend on your storefront, and TestFlight builds expire, so a regional gap is a real operational issue rather than a footnote. Finally, the project is young: the most recent release listed is v0.1.8, and the README's own status section still carries that regional caveat.

Alternatives and how they differ in approach

The nearest alternative in spirit is a general-purpose iOS SSH client such as Termius or Blink, paired with tmux or a persistent shell on the server. The difference is architectural rather than cosmetic. Those apps give you a terminal and nothing above it: you attach, you look at scrollback, you decide for yourself which session needs attention. Heeler adds a status layer that only exists because herdr exposes a JSON API and an event stream, which is what makes a sorted, live console possible at all. A generic SSH client cannot produce that list because it has no structured view of the agents.

The other alternative is herdr's own tooling on a laptop. That gives you the same information without a phone, and it is the right answer if you are usually at the machine. Heeler's value is specifically the case where you are not, and the push notification and Live Activity features exist only to serve that case. If you never leave the desk, the terminal rendering in Heeler is a convenience, not a reason to install anything.

Licence, maintenance, and what upgrading actually costs

Heeler is Apache-2.0, and the repository carries a LICENSE file at the top level. Apache-2.0 is a permissive licence with an explicit patent grant and a requirement to preserve notices, but it also means the App Store build and any self-built binary are the same code under the same terms. Nothing here is legal advice; if you plan to redistribute a modified build, read the licence text and the NOTICE handling yourself.

The maintenance signal is straightforward. The repository is not archived, and the last push was on 2026-09-16, one day before this writing. Releases are frequent and small: v0.1.6 on 2026-09-08, v0.1.7 on 2026-09-12, v0.1.8 on 2026-09-13. The version numbers still sit in 0.1.x, so expect interface churn rather than a frozen API.

Upgrade cost has two parts. The app updates through the App Store or TestFlight, which is cheap. The server side is not automatic: the plugin is installed with a --ref main flag in the README's command, so it tracks the main branch unless you pin it, and the README's prerequisites already name herdr 0.7.5 as the floor. HeelerSSH is not pulled from a package registry either: the Makefile has ssh-artifacts and verify-ssh-artifacts targets that rebuild and verify pinned XCFrameworks, which tells you the SSH layer is vendored and versioned inside the repository rather than resolved at build time.

Editorial conclusion

Adopt Heeler if you already run herdr 0.7.5 or newer on machines you can reach over SSH and want agent status plus a usable terminal on an iPhone or iPad. Do not adopt it if you need a non-Apple client, a browser UI, or a way to control agents without herdr installed, because Heeler speaks herdr's JSON API and nothing else. Before relying on it, verify that your SSH server permits stream-local forwarding, that the app is listed in your App Store region or that you can join TestFlight, and whether the plugin's heeler.pair enrollment path fits your key policy.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. ZingerLittleBee/Heeler on GitHub