Run multiple Claude Code sessions in tmux simultaneously. Use a popup selector to see the status and live preview of each session, and jump to any session with one click. https://github.com/craftzdog/tmux-claude-session-manager… A tmux plugin that lets you launch independent Claude Code sessions in multiple project directories, each running in its own tmux window. Press prefix + u to open an fzf selector listing all running Claude sessions, each tagged with live status (working, waiting for permission, idle), and see a screen preview.

craftzdog/tmux-claude-session-manager

Source: https://github.com/craftzdog/tmux-claude-session-manager

tmux-claude-session-manager

screenshot (https://youtu.be/NnTV6r4l5D0)

Run many Claude Code (https://claude.com/claude-code) sessions across your projects, each in its own tmux session — then list them, see which are done vs. still working, and jump to one from a single popup.

If you launch Claude per-directory (one nested session per project), you quickly end up with a dozen of them and no way to tell which are finished without opening each one.

This plugin gives you:

• 🔢 A central picker (prefix + u) listing every running Claude session.
• 🟢 Live status per session — working / waiting / idle — driven by Claude Code hooks, so you instantly see which need you.
• 👁️ A live preview of each session’s screen right in the picker.
• 🎯 Smart jump — selecting a session switches your client to the window it was launched from, then resumes it in a popup over it.
• 🚀 A launcher (prefix + y) that opens/attaches a Claude session for the current directory.
• ❌ Quick kill (ctrl-x) of finished sessions from the picker.

Status is optional: without the hooks the picker still lists, previews, jumps, and kills — sessions just show ? instead of a color.

Prerequisites

• tmux ≥ 3.2 (for display-popup)
• fzf (https://github.com/junegunn/fzf) — the picker UI
• Claude Code (https://claude.com/claude-code) CLI (the claude command)
• bash; macOS or Linux

Install (tpm)

Add to ~/.tmux.conf (or ~/.config/tmux/tmux.conf):

set -g @plugin 'craftzdog/tmux-claude-session-manager'

Then hit prefix + I to install.

Keybinding note: by default the plugin binds prefix + y (launch) and prefix + u (list). If your config binds those elsewhere, either change the options below, or make sure the plugin loads after your own bindings (put run '~/.tmux/plugins/tpm/tpm' after them) so the one you want wins.

Manual install

git clone https://github.com/craftzdog/tmux-claude-session-manager ~/clone/path

Add to ~/.tmux.conf, then reload (prefix + r or tmux source ~/.tmux.conf):

run-shell ~/clone/path/claude_session_manager.tmux

Usage

Inside the picker:

Sessions needing your attention (waiting, idle) sort to the top.

Status setup (optional, recommended)

Status comes from Claude Code hooks (https://code.claude.com/docs/en/hooks) that stamp each session’s state onto its tmux session.

Add the following to your Claude Code settings (~/.claude/settings.json), merging into any existing hooks block. Adjust the path if your plugins live elsewhere (e.g. ~/.tmux/plugins/...):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.config/tmux/plugins/tmux-claude-session-manager/scripts/state.sh working"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.config/tmux/plugins/tmux-claude-session-manager/scripts/state.sh waiting"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "AskUserQuestion",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.config/tmux/plugins/tmux-claude-session-manager/scripts/state.sh waiting"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.config/tmux/plugins/tmux-claude-session-manager/scripts/state.sh idle"
          }
        ]
      }
    ]
  }
}

The state machine:

Claude Code reloads hooks dynamically — no restart needed. Sessions that are already running start reporting status on their next event once the hooks are added.

Options

Set any of these before the plugin loads (defaults shown):

set -g @claude_launch_key 'y'          # prefix key: launch/open for current dir
set -g @claude_list_key 'u'            # prefix key: open the picker
set -g @claude_command 'claude'        # command run in new sessions
set -g @claude_session_prefix 'claude-' # tmux session name prefix
set -g @claude_popup_width '90%'       # popup width
set -g @claude_popup_height '90%'      # popup height

How it works

• The launcher creates a detached claude- tmux session running claude, records the window it came from in @claude_origin, and attaches to it in a popup.
• The hooks set @claude_state / @claude_state_at on each session as Claude works.
• The picker lists sessions matching the prefix, reads their state and a live capture-pane preview, and on selection moves your client to the session’s origin window before resuming it in the popup.
• Pressing prefix + u from inside a session popup detaches that popup first (closing it), then reopens the picker full-size on the outer host client — so you never end up with a cramped popup-in-popup.

License

MIT © Takuya Matsuyama