Automatic mode switching from the active herdr pane

[vgreg]

Goal

Make PadIO switch mode automatically based on which app is running in the active herdr pane, so controller bindings follow the app under the cursor without a manual mode pick.

Primary use case: navigation plus voice control of AI agents from an Xbox controller, with herdr (in Ghostty) replacing tmux. Herdr has three navigation levels (workspaces, tabs, panes) plus whatever app runs in each pane.

Design

Herdr's navigation levels live in profile.global for the Ghostty profile, so workspace/tab/pane bindings are always live. The app running in the focused pane selects the mode. No changes to the profile resolution cascade are needed.

herdr (socket API)                    bridge                    PadIO
─────────────────────                 ──────                    ─────
events.subscribe pane.focused  ──┐
                                 ├──> resolve leaf ──> write ──> DispatchSource watch
poll pane.process_info (~3Hz)  ──┘    process name    context     → context → mode

Herdr side (from its docs): newline-delimited JSON over a Unix socket at ~/.config/herdr/herdr.sock (or HERDR_SOCKET_PATH). events.subscribe supports pane.focused; pane.process_info returns the shell pid, foreground process group id, and foreground processes with pid, name and argv/cmdline.

PadIO side: today mode is set only by controller input (ControllerManager.switchMode, reachable from executeAction's .setMode case and the mode picker). Profile selection reads exactly one external signal, the frontmost bundle ID (ControllerManager.refreshActiveProfile). There is no URL scheme, socket, XPC or command listener. PadIO needs a new inbound channel.

Decisions already made

• Channel: a watched file, ~/.config/padio/context, holding a single token. Reuses the DispatchSource pattern already proven in ConfigLoader (MappingConfig.swift:309). No entitlements, no networking, no Info.plist changes.
• Policy lives in PadIO. The bridge reports a raw process name; PadIO's config maps it to a mode via context_modes. All user configuration stays in one file.
• No-match leaves the mode alone. If the context token has no context_modes entry, the current mode is kept. It does not fall back to default_mode.
• Manual override sticks. External context applies only when the token changes. A mode picked by hand stays until the context token changes.
• Hidden modes. Because context-driven modes can be numerous (one per app), the mode picker needs to show only a chosen few (e.g. media, zsh). Hidden modes stay reachable via setMode and external context.
• Bridge ships as a herdr plugin using [[startup]], so install is herdr plugin install <owner>/<repo> with no launchd agent to manage. It talks to the socket directly rather than relying on the plugin [[events]] hook, whose docs only demonstrate worktree.created.

Known gap

Launching an app from the shell inside an already-focused pane fires no event: pane.focused does not fire, and pane.updated is documented as firing on terminal-title changes (excluding spinner-only churn), not on foreground-process changes. Hence the ~3Hz poll of pane.process_info on the focused pane alongside the event subscription, so both pane switches and in-pane launches go through one code path.

Sequence

• PadIO track: PadIO: external context channel (watched ~/.config/padio/context) #8 (context channel) → PadIO: context_modes resolution (context token to mode) #9 (context_modes resolution)
• herdr track: herdr: live socket probe to validate API assumptions #11 (socket probe) → herdr bridge plugin: watch focused pane, write context token #12 (bridge plugin)
• PadIO: hidden modes, trim the mode picker list #10 (hidden modes) is independent of both and can be done at any point
• Docs: context_modes, hidden modes, herdr integration #13 (docs) last, once the config format has actually settled

The two tracks are independent and can proceed in parallel. Everything except #11 and #12 is unblocked today; those two need a live herdr session.

Caveat

All herdr detail here comes from reading its published docs, not from a live session. The probe sub-issue validates the field names and subscription semantics before the bridge is built.

[vgreg]

Provenance

Filed 2026-08-01 from a design discussion, not from a written report. Context for anyone (including a future agent) picking this up:

Where it came from. The main use case for PadIO is navigation plus voice control of AI agents from an Xbox controller. The setup recently moved off tmux to herdr running in Ghostty. Since herdr has three navigation levels plus whatever app runs in each pane, manually picking a PadIO mode per pane defeats the point.

How the herdr side was researched. Entirely from the published docs, fetched 2026-08-01: /docs/socket-api/, /docs/cli-reference/, /docs/configuration/, /docs/plugins/. No live session was available. That is why #11 exists and why #12 is blocked on it. Treat every herdr API detail in these issues as unverified until #11 closes.

How the PadIO side was researched. Direct reading of the current main (58631cb). The claim that PadIO has no external input channel is from grepping for URL schemes, sockets, XPC and distributed-notification listeners across the Swift sources: the only hit is HapticController observing system beeps. Line references in the sub-issues are against that commit and may drift.

Design decisions that were made deliberately and should not be quietly reversed while implementing:

1. The app in the pane selects the mode, not the profile. herdr's own navigation lives in profile.global for Ghostty so it is always available. This is why no change to the resolution cascade is needed.
2. Policy lives in PadIO's config, not in the bridge. The bridge reports a raw process name; context_modes maps it. Keeps all user configuration in one file.
3. No match on the context token leaves the mode alone rather than falling back to default_mode. This is what makes many app-specific modes safe.
4. A manually picked mode sticks until the context token changes.
5. Hidden modes exist because (3) and (4) encourage a large mode list, while only a couple of modes are ever picked by hand.

Not yet decided, and flagged in the relevant sub-issues rather than here: denylist vs allowlist for hidden modes (#10), separate repo vs subdirectory for the bridge plugin (#12), and whether the bridge clears the context file on exit (#12).

[vgreg]

Design updated after the probe (#11)

The probe refuted the central assumption. Two changes to the plan above:

pane.focused is not a focus signal. herdr re-emits focus state for every pane on a ~105 ms timer: 94 pane_focused events across 17 distinct panes in 10 s with no user interaction, while the actual focused pane never changed. The event-driven half of the diagram is gone. The bridge polls pane.current instead, at ~5 Hz, which costs 0.14 ms per call.

The known gap has closed by itself. Polling pane.current covers launching an app inside an already-focused pane, so the separate pane.process_info poll the original design needed is unnecessary. One loop, one call, both cases. The bridge is simpler than planned.

Two bonuses: pane.current already carries an agent field (herdr detects claude itself), so agent panes need no process inspection at all; and for non-agent panes the leaf-picking heuristic is replaced by an exact rule, argv0 of the process where pid == foreground_process_group_id.

The revised flow:

herdr                                bridge                     PadIO
─────                                ──────                     ─────
poll pane.current @5Hz  ──>  agent field, else argv0   ──> write ──> DispatchSource watch
                             where pid == pgid          context      → context → mode

Nothing changes for #8, #9 or #10; the PadIO side of the design was unaffected.

[vgreg]

All six sub-issues are closed.

PadIO (#8, #9, #10, merged as #14/#15/#16): ~/.config/padio/context is watched via ContextObserver, context_modes maps a token to a mode under the four agreed rules, and hidden_modes trims the picker and the mode cycle.

Bridge (#12): vgreg/herdr-padio, a stdlib-only Python herdr plugin. Polls pane.current at 5 Hz and resolves the token from herdr's agent field, falling back to argv0 of the process whose pid == foreground_process_group_id.

Docs (#13, merged as #17): a new Automatic Modes page framing the context file as a general extension point, with herdr as one producer.

The probe (#11) earned its place. It refuted the design's central assumption before anything was built: pane.focused is not a focus signal on herdr 0.7.5, so the planned event-driven bridge would have thrashed the mode ~10 times a second across 17 panes. Reported upstream as herdrdev/herdr#2177. The replacement is simpler than the original plan, since polling pane.current covers pane switches and in-pane launches through one call.

Not yet exercised end to end: herdr invokes a plugin's [[startup]] command on session restore, so the bridge starts on the next herdr restart. Everything below that hop is verified against the live session.

[vgreg]

Correction: the claim that pane.focused is not a focus signal is wrong. It is accurate; what was measured was events.subscribe replaying retained history (herdrdev/herdr#1270). Full correction and evidence in #11. The polling design is unchanged and still correct, for a different reason.