Repository navigation
feat: cycle to the next agent pane needing attention - #37
Merged
Merged
Conversation
Add a `cycle` command bound to `prefix + C-n` (configurable) that jumps to the highest-priority agent pane needing attention and walks through the rest on repeated presses. Ranking, highest attention first: waiting-question/waiting-input > idle > new > running > unknown. Within a tier, the pane in its state longest comes first (FIFO), so a long-waiting pane is never starved by newer arrivals. Seen/unseen: cycling tracks which panes you have already looked at. A pane is seen once it has been active since entering its current state (ordinary tmux navigation acknowledges panes too), and becomes unseen again when its state changes. Unseen panes are offered before seen ones, so repeated presses sweep everything new first, then continue through the rest and wrap; cycling never dead-ends. Unseen idle panes get a distinct filled-circle glyph (blue where colors are available) in the status line and choosers. Implementation: a reader-side ledger under ~/.local/state/coding-agents-tmux/cycle-state derived from the displayed status at read time, so it covers all agents with no writer/plugin changes and no state-file schema change. Ranking is pure and unit-tested (rankPanesForCycle / pickNextCyclePane). Status/menu/popup share one seen/unseen source of truth via getPaneStatusSymbol; the CLI now emits the resolved glyph in `list --compact`, letting the tmux menu script drop its duplicate bash symbol table. A 5th tmux key binding is wired through the plugin entry, buildTmuxSnippet, and tmux-config / install-tmux, with a matching @coding-agents-tmux-status-color-unseen option.
corwinm
approved these changes
Oct 4, 2026
corwinm
left a comment
corwinm
left a comment
Owner
There was a problem hiding this comment.
This looks great! Looks very useful.
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
A
cyclecommand onprefix + C-nthat jumps to the agent pane that mostneeds you. Press again to walk the rest.
Why
With several agents across panes,
menu/popupmake you open a list andpick. Most of the time I just want "take me to whatever needs me next."
How
Each press jumps to the next pane in this order:
looked at it, because only answering clears it.
Within each group, the pane that's been in its state longest goes first, so a
long-waiting pane never gets starved by newer ones.
A pane is seen once it's been active since entering its current state
(normal tmux navigation counts), and goes back to unseen when its state
changes. Presses go through the waiting and unseen panes first, then continue
through the seen panes and wrap. It never dead-ends.
Unseen idle panes get a filled blue circle, so finished work you haven't
reviewed stands out. Once seen it drops to the normal hollow idle glyph.
Example of how new "unseen" shows up in the popup
Status line: waiting pane, unseen idle in blue, running.
After switching to the "unseen" pane
The seen/unseen state is a small reader-side ledger under
~/.local/state/coding-agents-tmux/cycle-state, derived from the displayedstatus at read time. That means it works for every agent with no plugin/writer
changes and no state-file schema change.
Also: the status/menu/popup glyph now comes from one place
(
getPaneStatusSymbol).list --compactemits the resolved glyph, sotmux-menu-switch.shdrops its duplicate bash symbol table.Config
@coding-agents-tmux-cycle-key(defaultC-n,offto disable)@coding-agents-tmux-status-color-unseen(defaultcolour39)Notes for review
C-nis free on stock tmux, but it's a common rebind. Happy to change thedefault.
and they're harmless. I can follow up if you want it tidier.
Testing
Ranking tiers, FIFO within a tier, unseen-before-seen, waiting-ahead-of-seen,
full rotation and wrap, current pane absent, ledger transitions, e2e
cycleagainst fake tmux, the compact glyph field, and snippet/bind-key assertions.
All checks pass. Two pre-existing tests (
detectOpenCodeVersion, the Pirefresh-failure test) flake under parallel
node --testand pass inisolation. Neither touches this code.
Live-verified on a clean checkout of
main+ this branch with an emptyledger. Presses walk waiting → unseen idle → running, then continue through
seen panes.