[idea] API to select a saved machine in an attached client (or follow agent.focus across machines)

[chenxin-yan]

This idea was drafted with a coding agent on behalf of @chenxin-yan. It comes from building herdr-micro, a MacroPad-based hardware control deck for Herdr that mirrors agent state on LEDs and routes key presses to agents over the socket API. Findings below were verified live on 0.9.0.

idea / problem

Since 0.9.0 the Herdr UI shows Local and every saved SSH machine in one window with a combined agent list. External automation can now observe and address all of those machines (per-server socket API over an SSH tunnel today; herdr --machine in 0.9.1), but nothing outside the TUI can make the client switch which machine it is viewing.

What I checked on 0.9.0 (client and server, both machines):

• herdr api schema --json has no machine.* methods or events; the server has no knowledge of saved machines (expected, since federation is client-side).
• herdr agent focus <id> on a remote machine's server (run over SSH) focuses the pane on that server, but the local client stays on Local. ~/.local/state/herdr/client/endpoint-selection.json (selected_profile) is unchanged before and after.
• herdr-client.sock speaks the binary client protocol, not the JSON API, so it is not a usable control surface for this.
• @whshang's note in Support multiple remote Herdr servers #515 (Sep 8) describes the same gap for CLI routing; 0.9.1's --machine fixed addressing, but selection is still TUI-only.

For a hardware deck this is the one missing piece. The deck can light an LED for a blocked agent on minipc, and pressing its key can focus that agent on minipc's server, but the screen the user is looking at does not change, so the press appears to do nothing until they click the machine in the sidebar.

requested change

Either of these would close the gap; the first is the smallest.

1. A client-side selection API. Something like herdr machine select <label-or-id> (and local) that tells attached local clients to switch their viewed machine, the same way agent focus / pane move --focus already "move attached clients to the requested pane" within one server since 0.9.1. Exposing the current selection (already present as selected in herdr machine list --json) as an event or a documented read would let tools stay in sync without watching endpoint-selection.json.

2. agent.focus / pane.focus follow across machines. When a focus request arrives at a server that an attached federated client is not currently viewing, the client switches to that machine. This matches the sidebar behavior of clicking an agent on another machine.

Non-goals: no merging of pane IDs or runtime state across servers, no changes to --machine routing semantics.

why you want this

herdr-micro's next milestone is a merged fleet: one deck paging through agents on every saved machine, exactly mirroring the 0.9.0 combined agent list, with no "which machine am I on" state in the deck's config or gestures. Every other operation already works across machines through per-server sockets: reading state, subscribing to pane.agent_status_changed, agent.send_keys, tab.create. Selection is the only operation that has no programmatic path, so "press the key for the blocked agent" can't finish the job when that agent lives on another machine.

More generally, any orchestration or notification tool that wants "jump to the agent that needs me" now needs this, since agents can live on several machines behind one client.

Happy to test a preview build against a Local + one SSH machine setup.

[sharas859]

I would also like this for use with workspace picker/sessionizer. It seems if am on machine A and I have a key bind to open a picker there is no efficient way to straight up open a picker for a different machine or efficiently get to another machine to open a picker there.

[nortuzar]

+1 from another notification use case. I run a Claude Code / Codex hook on each saved machine that sends a macOS notification through my local client. Clicking it runs herdr --machine agent focus . That focuses the pane on the remote server, but the local client stays on whatever machine it was showing, so the click only brings the terminal to the front. Local panes jump correctly with plain herdr agent focus.

Either option here would fix it: herdr machine select [--pane ], or agent focus via --machine also switching the foreground client to that machine. Verified on 0.9.1 (macOS client, Linux servers).

[Aylr]

I would also love this for my own external session picker! I'm happy to do the work if I were approved to submit PRs!

[saif97]

I've built a fzf based session picker based on MRU. This is a big missing piece to use remote machines.

[rebelancap]

+1 from an Alfred workflow use case. I built a fuzzy picker (tab, workspace, path) that jumps to any herdr tab from any app. Local tabs work cleanly via herdr tab focus. For tabs on saved machines, herdr --machine <label> tab focus changes the remote server's focus, but the window stays on whatever machine it was showing. My only fallback is scripting keystrokes into the Go to picker and reading the screen to confirm the selection, which is fragile. Something like herdr machine select <label>, or --machine ... tab focus also switching the attached client, would make this a single API call.

[jswelker]

Agree, this would be a huge help for building custom navigation UIs.

[louwers-bot]

+1 from a PR review dashboard. It has an "Open in Agent" button that opens a pull request as a Herdr worktree, on Local or on a saved machine (it uses herdr --machine <id> worktree create and then workspace focus or worktree open --focus).

On Local, the window switches straight to the worktree. On a saved machine, the worktree is focused on that machine's server, but the window stays on Local, so I have to find the machine and the worktree in the sidebar myself.

Either option from the proposal would fix it for me: herdr machine select <id>, or --machine ... workspace focus / worktree open --focus also switching an attached client to that machine.