Window navigation past prev/next: jump by number, a window switcher, and Go to Attention across windows

[anadale]

Following up on #591 (previous_window / next_window): @umputun asked me to take the rest of the window story to a discussion, so here it is. I have been running that "rest" as a script over window list / window select / tree for a while, so below is what it does, where it falls short, and what I'd ask for instead. Three separate items; the third is the one I actually miss most.

The script is ~150 lines of POSIX sh + jq, wired through custom commands:

command "Pick Window"             cmd+opt+=        "$HOME/.local/bin/agterm-window-nav.sh" pick
command "Go to Attention Window"  cmd+opt+shift+=  "$HOME/.local/bin/agterm-window-nav.sh" attention
command "Window 1"                cmd+1            "$HOME/.local/bin/agterm-window-nav.sh" goto 1
…
command "Window 9"                cmd+9            "$HOME/.local/bin/agterm-window-nav.sh" goto 9

Happy to post it whole if any of this is worth a cookbook recipe rather than a built-in.

1. A shortcut straight to a window

What the script does. A window's number is its position in agtermctl window list, i.e. the bundle order, closed windows included. So ⌘3 is always the same window, no matter which one is frontmost, and the numbers do not shift when a window closes; ⌘N on a closed window reopens it, since window select already does that. Numbers move only when a bundle is deleted for good (delete_window). I tried "relative to the current window" first and threw it out within a day: a number that floats is not an address, you have to look before you press.

Why I'd rather have it built in. Nine command lines for nine /bin/sh round trips is the obvious part. The less obvious one is that the step and the jump now disagree about closed windows: window go --to next|prev walks the open set and treats a closed bundle as not a stop, which is right for a step, while a numbered jump wants the address to keep working after the window closes, otherwise ⌘3 silently becomes ⌘2. Both are consistent with "window select stays the verb that opens a closed one"; they just answer different questions, and I'd rather that split be a design decision than an accident of two implementations.

Shape, deferring to the author. The keymap has no arguments for built-ins, so this is either nine tokens (window_1 … window_9, ugly but honest) or one token with a numeric suffix parsed off. On the control side window go --to 3 reads naturally next to --to next|prev, the only question being whether a number is allowed to reopen a closed window, and my vote is yes, for the reason above.

2. A window switcher with a real shortcut column

What the script does. pick over the windows: ⌘N on the left, ● in place of the number on the current window, the window name, then a ◆N badge when the window has sessions needing attention, with the subtitle spelling out up to two of them (◆ api blocked 2m, worker done 5m) and folding the rest into +N.

Where it breaks. pick has no columns, so the shortcut gutter is padded with spaces, hand-tuned for one palette font size; change the font size in Settings and the names stop lining up. The subtitle line cannot be aligned at all, it is set in a smaller font. It works, it is just not something anyone should tune by hand.

The ask. A native window list with the shortcut rendered by the palette rather than typed into the label. Whether that is a palette next to the session and attention ones, or a hold-and-tap switcher like Ctrl-Tab (its two-line rows already have the shape), I don't mind. The one thing I'd keep from the script is the current window pinned with ● and the ◆N badge with the attention sessions in the subtitle, since that is what makes the list worth opening instead of just stepping. One thing the script cannot do and I'd want: open with the current window selected, so ↑/↓ from where you are reads as "the window above / below this one" and ⏎ on an untouched list is a no-op rather than a jump to the first row; pick has no way to choose the initial row, --query only re-ranks.

3. Go to Attention across windows

This is the real gap. Everything that answers "who needs me" is scoped to one window: ⌃⇧I, the title-bar bell, ⌃⌥↑/↓, the Dock menu, auto-follow. With one window per project, an agent blocking in another window is invisible from where you sit until you happen to switch there. The docs say as much ("for the last-active window"), so this is a scope decision rather than a bug; I'd just like the attention list to have the other scope too.

What the script does. Same picker as (2), but windows with attention come first, the one with the most recent request on top, the rest in slot order behind them. So ⏎ with nothing typed lands in the window AND the session that asked for you most recently, LIFO, which for me is the right order: the newest request is the one whose context is still warm in the agent, the oldest one has been waiting anyway. The session currently on screen in the active window is left out, you can already see it, the picker is for what you can't. After the pick it switches to the window, selects the session and reveals the pane that set the status, the same landing a click in the bell popover gives you.

The ask. An attention list whose rows are sessions from every open window, most recent request first, each row saying which window it lives in, with the selected row raising that window, selecting the session and revealing its pane, exactly what the bell popover does within a window today. Whether this is a second list, or ⌃⇧I covering all windows when more than one is open, is the author's call. Two things I'd leave out on purpose: closed windows, which have no statuses to show, and the notification badge, which per #256 stays outside the attention set. I'm also not asking for ⌃⌥↑/↓ to cross windows; a keystroke that raises another window mid-typing is a different conversation.

Ordering, one open question. Within a window the attention list goes blocked → active → completed and only then newest-first. Across windows I'd go by time alone and drop active from the list: the question this list answers is "who asked me last", and an active session hasn't asked. If the author would rather keep the status order as the first key I'd take that too, as long as the newest blocked stays on top.

Environment

agterm 0.27.1, macOS 26.6, three to six open windows on a normal day.

[umputun]

taking the third one, passing on the first two, and yes to the recipe.

attention across windows. This is a real gap. I'll widen ⌃⇧I and the title-bar bell to every open window when more than one is open, rows carrying the window name, a pick raising that window and selecting the session with the same pane reveal the attention list does today. No second list and no new token. On ordering I'm keeping the existing attention-list order across windows, blocked → active → completed and newest inside each group, as one combined sort rather than per-window lists stacked. The newest blocked still ends up on top, which is the part you cared about. The session on screen stays in the list, same as the per-window list today, since a blocked scratch or split pane can be hidden behind what you are looking at.

jump by number. Passing. The address by slot over window list / window select is exactly the kind of glue I keep in user space (#270 has the reasoning), and nine keymap tokens or a numeric suffix grammar for one workflow is past the minimum I ship built in. window go stays open-only as documented in #591.

window switcher. Also passing. File ▸ Open Window lists every window in slot order with a checkmark on open ones, and the attention half comes from the item above. A chosen initial row is a useful separate improvement to pick, file it as its own ask, a --select would serve every recipe, not just this one.

pls post the script as a cookbook recipe, cookbook/CONTRIBUTING.md has the format. It is the right home for the numbered jump and the picker.

[umputun]

merged in #596. ⌃⇧I and the title-bar bell now list sessions needing attention across every open window, blocked → active → completed and newest first within each group, each row's subtitle starting with its window name once more than one is open. Picking a session in another window brings that window forward, selects the session and, for blocked/completed rows, reveals the pane that set the status; active rows preserve pane selection. The Dock menu and ⌃⌥↑/↓ stay per window. It goes out with the next release.

[umputun]

the picker's initial row is in as well, #597: agtermctl pick --select ID opens with that item highlighted and scrolled into view, so a window or session picker can start on the current one and Return on an untouched list stays put. The id must name a supplied item, and a --query that filters it out leaves the first visible row highlighted. This will be available in the next release.

[anadale]

Thank you for the fast response. I'll submit the PR with the recipe shortly.