This plugin addresses the challenge of managing numerous Claude Code sessions across diverse projects by integrating seamlessly with tmux. It provides users, particularly developers and researchers running multiple AI agents, with a centralized interface to monitor session status, preview output, and quickly navigate or terminate agents, thereby streamlining complex workflows.

How It Works

The system leverages tmux for session management and fzf for an interactive picker. It queries the claude agents --json command to obtain real-time status (working, waiting, idle) for each running Claude agent. A key innovation is its ability to identify and track agents by their unique process ID, rather than solely by tmux session names. This allows for granular control over multiple agents within the same project or those launched in standard terminal panes. The plugin utilizes tmux popups for an integrated user experience, allowing users to jump directly into an agent's context.

Quick Start & Requirements

• Primary Install: Via tmux Package Manager (tpm). Add set -g @plugin 'craftzdog/tmux-claude-session-manager' to your ~/.tmux.conf (or ~/.config/tmux/tmux.conf) and run prefix + I. A manual git clone installation method is also available.
• Prerequisites:
  • tmux version 3.2+
  • fzf
  • jq
  • Claude Code version 2.1.139+
  • bash
  • macOS or Linux
• Keybindings: Default bindings are prefix + y (launch/attach) and prefix + u (list picker).

Highlighted Details

• Central Picker (prefix + u): A unified interface listing all Claude agents with live status and screen previews.
• Live Status Monitoring: Real-time agent states (working/waiting/idle) are directly sourced from claude agents --json.
• Smart Jump: Seamlessly navigates to the tmux window of a selected agent, resuming it in a popup.
• Agent Launcher (prefix + y): Quickly initiates or re-attaches to a Claude session for the current directory.
• Quick Kill (ctrl-x): Allows immediate termination of agents directly from the picker.

Maintenance & Community

The provided README does not detail specific community channels (e.g., Discord, Slack), roadmap information, or notable contributors beyond the author, Takuya Matsuyama.

Licensing & Compatibility

• License: MIT License.
• Compatibility: The permissive MIT license generally allows for commercial use and integration with closed-source projects without significant restrictions.

Limitations & Caveats

Functionality is dependent on the specific output format of claude agents --json and the availability of tmux features like display-popup. The "age" column in the picker reflects the transcript's modification time (mtime), not necessarily the agent's last active moment. The README does not specify known bugs or unsupported platforms.