Skip to content

herdr: Add tmux layouts and numeric pane picker - #20

Merged
Unique-Divine merged 11 commits into
mainfrom
ud/herdr-tmux
Aug 10, 2026
Merged

herdr: Add tmux layouts and numeric pane picker#20
Unique-Divine merged 11 commits into
mainfrom
ud/herdr-tmux

Conversation

@Unique-Divine

Copy link
Copy Markdown
Owner

Add Herdr tmux layouts and numeric pane selection

Add a small herdr-tmux command for the tmux interactions missing from stock
Herdr, then bind those commands through the managed local configuration. The
result preserves Herdr as the terminal owner while restoring even pane layouts
and fast prefix+q pane selection.

Rationale

Directional navigation works for nearby panes, but it becomes cumbersome in
dense or asymmetric layouts. Rebuilding tmux-style behavior through Herdr's
typed socket API keeps pane identity, terminal processes, and scrollback under
Herdr's control and avoids maintaining a fork or routing focus through repeated
directional CLI calls.

The helper remains a narrow local command. Plugin packaging, fuzzy search,
multi-digit selection, and a CLI neighbor-graph fallback remain deferred.

Behavior flow

prefix+= / prefix+Shift+-
  -> export active-tab layout
  -> unzoom and rebuild an even split tree
  -> restore the original focused pane

prefix+q
  -> popup receives active tab and pane context
  -> enumerate and sort panes by (y, x)
  -> read one digit without Enter
  -> revalidate the selected pane
  -> focus its absolute pane ID

Pane layout behavior

The even-layout commands rearrange existing panes rather than replacing their
terminals. A session-scoped lock prevents overlapping layout mutations, and a
failed rebuild attempts to restore the exported layout before reporting the
error.

Numeric pane selection

The popup lists up to ten panes in geometric reading order and marks the active
pane. Descriptions prefer pane labels and agent/title metadata, then fall back
to the CWD basename or pane ID. Escape, invalid input, and the 1.5-second timeout
cancel without changing focus; one-pane tabs and same-pane selections are clean
no-ops.

The selected pane is fetched again immediately before pane.focus. If it was
closed or moved outside the originating tab, the command exits without
redirecting focus elsewhere.

Configuration and packaging

The Rust crate now lives separately under herdr-tmux, with package metadata,
local just recipes, and focused socket/UI tests. The managed Herdr config adds
the layout and picker bindings, a temporary pane-command demo, and bottom-right
in-app notifications.

Key Changes

  1. Add typed socket operations for layout export, pane geometry and metadata,
    absolute focus, moves, zoom, and notifications.
  2. Add balanced even-vertical and even-horizontal layout rebuilding with
    recovery and focus preservation.
  3. Add the raw-terminal numeric picker with deterministic ordering, timeout,
    cancellation, metadata fallback, and stale-target protection.
  4. Bind the commands to prefix+=, prefix+Shift+-, and prefix+q in the
    managed Herdr configuration.
  5. Separate the reusable command crate from personal configuration and document
    its local installation and behavior.

@Unique-Divine
Unique-Divine merged commit 5a41e74 into main Aug 10, 2026
1 check passed
@Unique-Divine
Unique-Divine deleted the ud/herdr-tmux branch August 10, 2026 08:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant