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)
- Notification inbox: Browse panes waiting for input or sitting idle in an fzf popup and jump to them
- Auto-registration: Claude Code hooks automatically track pane states, wait reasons, and task summaries
- Auto-discovery: Existing Claude Code sessions are detected on plugin load
- In-memory state: Pane state lives in tmux pane options - 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)
- Window auto-rename: Optionally rename windows to
<state-icon> <directory name> so state stays visible at a glance
- Conductor (opt-in): A persistent orchestrator Claude session in a popup that dispatches tasks to your other panes
- Claude Code skills:
hop-status (session overview), hop-config (inspect/edit options), hop-dispatch (route a task to another pane)
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 |
prefix + i | Open notification inbox (fzf popup, menu fallback) |
C-Space | Jump back to previous pane (no prefix) |
prefix + y | Open conductor popup (only when conductor is enabled) |
prefix + Y | Respawn conductor and open popup (only when conductor is enabled) |
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'
# Customize notification inbox key (default: i)
# Opens an fzf popup (display-menu fallback) listing all tracked panes
# (waiting/idle first, then active) as aligned columns (icon, session:window,
# project, branch, time, wait reason, task); enter switches to that pane,
# ctrl-x dismisses current notifications (active panes stay).
set -g @hop-inbox-key 'i'
# 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 macOS bundle ID / TERM_PROGRAM by default)
# set -g @hop-terminal-app 'iTerm' # Explicitly set terminal app name
# set -g @hop-terminal-app 'Ghostty' # Use this if tmux still detects Terminal.app
# Note: On macOS, iTerm2 and Terminal.app focus the specific tab/window
# containing the tmux session. Ghostty focuses the running app process without
# launching a new blank window.
# Status bar integration - show pane counts in status bar
set -g status-right '#{E:@hop-status} | %H:%M'
