claude-tmux-hop

Claude Tmux Hop

Quickly hop between Claude Code sessions running in tmux panes.

Features

• Priority-based cycling: Jump to panes waiting for input first, then idle, then active
• Jump-back: Return to previous pane across sessions/windows with Alt+Space
• Auto-hop: Optionally auto-switch to panes when they need attention
• System notifications: Display OS notification when panes need attention (macOS/Linux/Windows)
• Terminal focus: Automatically bring terminal to foreground when panes need attention (macOS/Linux/Windows)
• Auto-registration: Claude Code hooks automatically track pane states
• Auto-discovery: Existing Claude Code sessions are detected on plugin load
• In-memory state: Uses tmux pane options - no files, auto-cleanup when panes close
• Cross-session navigation: Works across all tmux sessions
• Status bar integration: Show pane counts with customizable icons
• Popup picker: Interactive fzf-based picker with time-in-state display (requires fzf)

Requirements

• tmux 3.0+
• Python 3.10+
• Claude Code

Installation

1. Install Claude Code Plugin

claude plugin marketplace add unsafe9/claude-tmux-hop
claude plugin install claude-tmux-hop

2. Install Tmux Plugin (via TPM)

Add to ~/.tmux.conf:

set -g @plugin 'unsafe9/claude-tmux-hop'

Then press prefix + I to install.

Any existing Claude Code sessions will be automatically discovered and registered as idle on plugin load.

Usage

Key Bindings

Key	Action
prefix + Space	Cycle to next Claude Code pane
prefix + C-f	Open picker menu
C-Space	Jump back to previous pane (no prefix)

Configuration

Add to ~/.tmux.conf:

# Customize cycle key (default: Space)
set -g @hop-cycle-key 'Space'

# Customize picker key (default: C-f)
set -g @hop-picker-key 'C-f'

# Customize back key (default: C-Space, root binding - no prefix)
set -g @hop-back-key 'C-Space'

# Cycle mode (default: priority)
# - priority: cycle within highest-priority group only
# - flat: cycle through all panes in priority order
set -g @hop-cycle-mode 'priority'

# Auto-hop: automatically switch to panes when they enter specific states
# Disabled by default. Set to comma-separated states to enable.
set -g @hop-auto 'waiting'           # Auto-switch when a pane needs input
# set -g @hop-auto 'waiting,idle'    # Also switch when tasks complete

# Priority-only mode (default: on)
# Only auto-hop if no other pane has equal or higher priority
set -g @hop-auto-priority-only 'on'  # Don't hop if another pane is already waiting
# set -g @hop-auto-priority-only 'off'  # Always hop regardless of other panes

# System notification: display OS notification when pane state changes
# Disabled by default. Set to comma-separated states to enable.
set -g @hop-notify 'waiting'         # Notify when a pane needs input
# set -g @hop-notify 'waiting,idle'  # Also notify when tasks complete

# Terminal focus: bring terminal app to foreground when pane state changes
# Disabled by default. Set to comma-separated states to enable.
set -g @hop-focus-app 'waiting'      # Focus terminal when a pane needs input

# Terminal app override (auto-detected from TERM_PROGRAM by default)
# set -g @hop-terminal-app 'iTerm'   # Explicitly set terminal app name

# Note: On macOS, iTerm2 and Terminal.app will focus the specific tab/window
# containing the tmux session, not just bring the app to foreground.

# Status bar integration - show pane counts in status bar
set -g status-right '#{E:@hop-status} | %H:%M'

# Status format (default: "{waiting:󰂜} {idle:󰄬}")
# Syntax: {state:icon} shows "icon count" when count > 0
set -g @hop-status-format '{waiting:󰂜} {idle:󰄬} {active:󰑮}'  # Include active
# set -g @hop-status-format '{waiting:W} {idle:I} {active:A}'  # ASCII icons

CLI Commands

The CLI is bundled within each plugin and invoked automatically by tmux keybindings and Claude Code hooks. For debugging, invoke from the plugin directory:

# From tmux plugin directory (e.g., ~/.tmux/plugins/claude-tmux-hop)
./bin/claude-tmux-hop list      # List all Claude Code panes
./bin/claude-tmux-hop doctor    # Check environment

How It Works

Pane States

State	Trigger	Priority
waiting	User input required	Highest
idle	Task complete	Medium
active	Working	Lowest

Cycling Behavior

Controlled by @hop-cycle-mode (default: priority):

Priority mode (set -g @hop-cycle-mode 'priority'):

1. If waiting panes exist, cycle only through waiting panes (oldest first)
2. If no waiting, cycle through idle panes (newest first)
3. If no idle, cycle through active panes (newest first)

Flat mode (set -g @hop-cycle-mode 'flat'):

• Cycle through all panes in priority order (waiting → idle → active)
• Within each priority level, sorted by timestamp

State Storage