multipane-tmux-jump-plan.md

Cross-Pane Jumping for tmux-jump

Summary

Modify tmux-jump to highlight matching characters across all visible panes in the current window, not just the current pane. When a user selects a highlighted key, the plugin will switch to the target pane (if different) and jump to that position.

Files to Modify

• scripts/tmux-jump.rb - Core logic (main changes)
• scripts/tmux-jump.sh - Add environment variable for optional toggle
• scripts/utils.sh - Add helper for new config option

Implementation Plan

1. Add New Data Structures

Add a PaneInfo struct to track per-pane state:

PaneInfo = Struct.new(
  :pane_id, :pane_tty, :pane_mode, :cursor_y, :cursor_x,
  :alternate_on, :scroll_position, :pane_height, :pane_top, :pane_left,
  :screen_content, :saved_screen
)

Add a GlobalPosition struct to track positions across panes:

GlobalPosition = Struct.new(:pane_info, :local_position, :global_key_index)

2. Implement get_all_visible_panes

Use tmux list-panes -F to get all panes in the current window with their properties. Sort panes top-to-bottom, left-to-right for consistent key ordering.

3. Implement capture_all_pane_contents

Iterate through all panes and call tmux capture-pane for each, storing content in PaneInfo.screen_content.

4. Implement find_all_positions

For each pane, call existing positions_of() and wrap results in GlobalPosition structs. Assign global key indices sequentially across all panes.

5. Implement recover_all_screens_after

Generalize the existing screen recovery logic to handle multiple panes:

• Save screen state for each pane (alternate screen or normal)
• After the block, restore all panes to their original states

6. Implement draw_keys_onto_all_panes

Group positions by pane, then render to each pane's TTY. All panes get dimmed (GRAY) with RED highlights on matching positions.

7. Implement perform_jump

def perform_jump(selected_position, current_pane_id)
  target_pane = selected_position.pane_info

  # Switch pane if needed
  if target_pane.pane_id != current_pane_id
    `tmux select-pane -t #{target_pane.pane_id}`
  end

  # Enter copy-mode and navigate to position
  `tmux copy-mode -t #{target_pane.pane_id}`
  # ... existing cursor movement logic using target_pane properties
end

8. Update main Function

Replace single-pane flow with multi-pane flow:

1. Read the jump character from temp file
2. Get all visible panes via get_all_visible_panes
3. Capture content from all panes
4. Find all positions across all panes
5. Prompt user with recover_all_screens_after + prompt_global_position_index!
6. Call perform_jump with selected position

9. Update prompt_position_index!

Modify to work with GlobalPosition array:

• Draw keys onto all panes (not just current)
• Recursive selection logic remains similar but operates on global positions

10. Add Configuration Toggle (Optional)

Add @jump-cross-pane option (default: "on") to allow users to disable cross-pane behavior if desired.

Edge Cases

1. Single pane window - Works identically to current behavior
2. Different alternate screen states - Each pane tracked/restored independently
3. Large number of matches - Existing multi-character key system handles this
4. Copy mode in other panes - Preserved; only cancel in target pane when jumping

Verification

1. Open tmux with 2-4 panes containing different content
2. Activate tmux-jump (prefix + j)
3. Type a character that appears in multiple panes
4. Verify all matching positions across all panes are highlighted
5. Select a key for a position in a different pane
6. Verify the plugin switches to that pane and positions cursor correctly
7. Test screen restoration - all panes should return to normal after selection or cancel