Click a session, focus the pane it runs in
Explore this workspace.
Technical background
A session running in a herdr or shefrd pane is raised in place instead of opening a browser. Three places are tried nearest first: a tab in this window, then the multiplexer pane, then the session registry on the web. Everything goes through the registry's own herdr endpoints, so no second address is configured and nothing invokes a binary.
The problem
"Focus tab" could only ever mean a tab in this window, and most sessions are not in one. Measured on the machine this was built on: 15 of 15 listed sessions had a multiplexer pane and no tab here, so every click fell through to the "there is nothing to focus" branch and opened a browser instead.
How it works
Three places are tried nearest first, because each is more disruptive than the last: a tab in this window, then the herdr/shefrd pane the session is running in, then the session registry on the web. Both pane calls go through the registry itself — GET /api/herdr/panes and POST /api/herdr/focus — which already holds a socket to every multiplexer server. The join is the session id, matched against the pane rows' own.
Try it
- Open Settings → Claude → Clicking a session and confirm "Focus panes in herdr / shefrd" is on. It depends on the click action being Focus, and is disabled otherwise.
- Press Test connection on the same page. It reports the pane count beside the session count.
- Click a row in the panel for a session running in a multiplexer. The row carries a columns icon naming its pane.
Settings
claude.shefrd.enabled:trueAsk the multiplexer to raise a session's pane when there is no tab here for it.
Details
- There is deliberately no second address to configure.
claude.stithURLis the whole of it, so the registry URL and a shefrd URL cannot drift apart — and it is the same pair of endpointstabby-links'shefrd.jsonmanifest uses, kept identical on purpose. - It is a separate service from the registry client, which documents at the top of its own file that it never mutates registry state. A focus POST does.
focus()returns how it failed rather than a boolean. "No pane" means the session is somewhere else entirely and a browser is the honest answer; "failed" means the pane is real and something transient went wrong. The fallbacks differ.- The timeout is its own constant rather than the poll's, which is tuned against a two-second interval where failing fast is right. An aborted focus looks exactly like a click that did nothing. Measured: listing 45–110ms for 44 panes, focus 120ms.
What this does not claim
- It does nothing for a session on another machine — there is no pane here to raise, and that case still opens the registry in a browser.
- The automated test never talks to the real registry, and must not: the point of the service is a command that moves someone's desktop. It drives an HTTP server the test owns. The live path was exercised once by hand, recording which pane was focused first and putting it back.
- Nothing verifies that raising a pane also raises the window containing it; that is the multiplexer's business, not this.