(idea) Responsive pane tabs for mobile: show tmux panes as tabs on narrow screens

[generev]

Problem

When a tmux session has multiple panes (e.g. 3–4 AI agents running side by side), the current agentboard view renders the entire session layout. On desktop this is fine, but on a phone the panes become tiny and hard to read or interact with.

Proposed Solution

Detect screen width and switch behavior at a breakpoint (e.g. 768px):

• Desktop (wide): keep the current behavior — render the full session layout with all panes visible
• Mobile (narrow): instead of the cramped split view, display each pane as a full-screen tab, with a tab bar showing pane titles (e.g. [Claude] [Codex] [Gemini] [Cmd]), each tab filling the full screen

Tab names would come from tmux pane titles (#{pane_title}), which many setups already configure meaningfully.

Why this seems feasible (based on a quick read of the code)

A few things in the existing architecture make this look relatively approachable:

• The WebSocket terminal-attach message already has a tmuxTarget field that accepts session:window.pane format, the protocol can already address individual panes, the frontend just never populates this field
• useMobileLayout and the 767px breakpoint are already used throughout, no new responsive infrastructure needed
• The horizontal session tab UI on mobile already exists as a pattern to build on

The main missing pieces appear to be: (1) backend calling tmux list-panes to discover panes per window, and (2) a pane tab switcher in the mobile UI that sets tmuxTarget accordingly.

Relation to #59

Different from #59 (tiling): that proposes reimplementing split-screen natively in the browser; this is purely a presentation adaptation for small screens using the pane layout that already exists in tmux.

Happy to take a stab at a PR if this direction sounds good.

[gbasin]

sounds cool, probably feasible. we are currently overriding the window titles and not touching pane titles, right? worth double checking since I don't use split panes myself.

also yea I think you can call list-panes instead of list-windows how we do now, from claude:

The Key Insight: One list-panes -s Replaces list-windows                                                                                                                                                                
                                                                                                                                                                                                                          
  The current discovery calls tmux list-windows -t agentboard -F ... (SessionManager.ts:352). The most efficient approach is to replace it with a single:                                                                 
                                                                                                                                                                                                                          
  tmux list-panes -s -t agentboard -F '#{window_id}\t#{window_name}\t#{pane_id}\t#{pane_index}\t#{pane_title}\t#{pane_current_path}\t#{pane_start_command}\t#{window_activity}\t#{window_creation_time}\t#{pane_active}'
                                                                                                                                                                                                                          
  The -s flag lists all panes across all windows in one call. You get one row per pane, grouped by window. A 3-pane window produces 3 rows sharing the same window_id. This means:                                        

  - No extra tmux calls - you get pane data as part of the existing discovery cycle                                                                                                                                       
  - Replaces the current list-windows call, not supplements it - same cost, more data                                                                                                                                     
  - No N+1 problem - you don't need list-panes per window                                                                                                                                                                 
                                                                                                                                                                                                                          
  Where to Call It                                                                                                                                                                                                        
                                                                                                                                                                                                                          
  Same place the current listWindowOutput() runs (SessionManager.ts:352-364). The refresh cycle already fires on interval, on enter-key, and on client request. No new call sites needed.                                 
                                                                                                                                                                                                                          
  What Changes

  1. SessionManager.ts - listWindowsForSession() parses the new format, groups rows by window_id, and builds pane arrays:

  // Session type gets:
  panes?: { id: string; index: number; title: string; active: boolean }[]
  paneCount: number  // 1 = no tabs needed on mobile

  2. The existing flow already handles the rest:
  - tmuxTarget in terminal-attach already accepts session:window.pane format
  - Both PtyTerminalProxy.switchTo() and PipePaneTerminalProxy.switchTo() pass the target through to tmux, which natively understands pane specifiers
  - One fix needed: extractWindowId() in TerminalProxyBase.ts:133 currently strips pane info - it needs to stop doing that (or only strip it where window-level identity is needed)

  3. Mobile frontend - When paneCount > 1 && isMobileLayout, render a tab bar above the terminal. Tab tap sends terminal-attach with tmuxTarget: "agentboard:@1.2" instead of "agentboard:@1".

  What You Don't Need

  - No separate API endpoint for pane discovery
  - No additional polling or WebSocket messages
  - No changes to the PTY/pipe proxy architecture
  - Desktop rendering doesn't change at all (tmux already composites multi-pane layouts)

  The total backend delta is essentially: change the format string in WINDOW_LIST_FORMAT, update parseWindow() to group by window and emit pane arrays, and relax extractWindowId(). Everything else is frontend.

[generev]

Double-checked — agentboard only touches window names (rename-window, new-window -n), never pane titles. Pane titles are set by the running processes themselves.

Tested with a 3-pane window running Claude, Codex, and Gemini side by side. Pane titles are present via #{pane_title}, set by each process independently.

One thing I noticed: the composited rendering in the web terminal doesn't match the actual tmux layout — my local terminal has Claude on the left full-height with Codex top-right and Gemini bottom-right, but agentboard renders Gemini spanning the entire bottom half. Likely a column-width mismatch between the xterm.js instance and the tmux pane dimensions. Rendering one pane at a time would sidestep this issue entirely.

[screenshot: local terminal]

[screenshot: agentboard web]

Also, for tab labels I'd lean toward simple pane index (1, 2, 3) rather than #{pane_title} — each process sets its own title with different conventions so it can look inconsistent.

Your analysis on list-panes -s replacing list-windows looks right to me. Happy to start on a PR if this direction works.

[generev]

One more thought: given that the composited rendering already misaligns pane layouts on desktop (as shown above), pane tabs might be useful on desktop too, not just mobile. Maybe as an optional toggle or a default when pane count > 1. That way users always get a clean full-size view of each pane regardless of screen size.

[gbasin]

Cool, I like it :)

[generev]

Pane isolation — investigation notes

I spent some time exploring this. The discovery/UI side is straightforward, but pane rendering isolation turned out to be an architectural constraint I hadn't anticipated. Documenting the paths I tried in case it saves someone time.

TL;DR: Discovery and UI are straightforward; the hard part is getting per-pane streaming with full fidelity, which likely requires tmux control mode.

What works well:

• list-panes -s replaces list-windows seamlessly — one call gets all panes grouped by window, without additional tmux queries
• The frontend can wire tmuxTarget to session:@window.paneIndex and the WebSocket attach path accepts it natively
• Pane tab UI is straightforward once discovery data is available

The hurdle: pane rendering isolation

In testing, I didn't find a clean way to extract a single pane's output as a real-time stream with full fidelity without affecting the layout. This appears to be a limitation of standard PTY streaming (not specific to this project).

Approach	Status	Result
PTY + switch-client -t pane	Tested	Doesn't isolate — just selects the pane for input. Pane remains embedded within the full composited window view.
pipe-pane mode	Tested	Isolates the stream, but loses the composited "All" view. Observed color-fidelity issues on reattach and no scrollback access.
tmux control mode (-CC)	Researched	The most promising path — per-pane tagged output with full fidelity (how iTerm2 does it); however, it requires a control-mode protocol parser, which is a substantial development investment.

Summary:

tmux composites panes into a single terminal stream by design. Extracting one pane's output in real-time without disturbing the layout likely requires reimplementing a portion of tmux's internal multiplexing logic. Control mode appears to be the most promising path to support both composited view and per-pane streaming, but it would require substantial architectural work.

[gbasin]

ouch yea thanks for digging into it. tbh control mode might not be that hard to get working in theory but the models will have a hard time iterating with subtle issues related to scrolling on mobile, I bet. feel free to try :)