claude-tmux 1.2.0

A manager for multiple Claude Code instances with tmux

Features

• Worktree Isolation: Each agent gets its own git worktree, preventing branch conflicts
• TUI Dashboard: Real-time status monitoring with vim-style navigation
• Attention System: Jump between panes needing user input (permission requests, notifications, questions)
• Plugin Integration: Claude Code hooks track agent state in a shared SQLite database
• tmux Bindings: Quick navigation with customizable keybindings

Requirements

• Python 3.12+
• tmux
• uv (recommended) or pip
• git

Installation

From GitHub (Recommended)

Install the plugin directly from GitHub using Claude Code's marketplace:

claude /install-plugin burstMembrane/claude-tmux

Then install the CLI tools:

# With uv (recommended)
uv tool install claude-tmux

# Or with pip
pip install claude-tmux

From PyPI

If you prefer to install everything via PyPI:

# Install CLI tools
uv tool install claude-tmux

# Run guided setup to install the plugin
claude-tmux setup

The setup command copies the bundled plugin to Claude Code and optionally configures tmux bindings and the MCP server.

Quick Start

# Create a new agent with a worktree
claude-tmux new feature-auth

# List all agents
claude-tmux ls

# Attach to an agent's tmux window
claude-tmux attach feature-auth

# Launch the TUI dashboard
claude-tmux ui

# Jump to next pane needing attention
claude-tmux next-attention

# Merge and cleanup when done
claude-tmux merge feature-auth

TUI Dashboard

Launch with claude-tmux ui for an interactive dashboard.

Navigation:

Key	Action
j/k	Move cursor down/up
g/G	Jump to top/bottom
Enter	Switch to agent pane
/	Search agents
A	Toggle attention-only filter
p	Toggle preview pane
n	Create new agent
x	Kill selected agent
?	Show all keybindings
q	Quit

Environment Variables:

Variable	Default	Description
CLAUDE_TMUX_TUI_PREVIEW	true	Show preview pane on startup
CLAUDE_TMUX_TUI_PERSIST	true	Keep TUI open after jumping to agent

tmux Integration

Add to your .tmux.conf:

# Popup TUI dashboard
bind-key M-u display-popup -E -w 90% -h 85% "ctmux ui"

# Generate all recommended bindings
claude-tmux bindings >> ~/.tmux.conf

Plugin Setup

The Claude Code plugin tracks agent state automatically via lifecycle hooks.

If you installed the plugin from GitHub (/install-plugin), it's already configured. Use this section only if you installed via PyPI and need to run claude-tmux setup.

Guided Setup

claude-tmux setup

This command:

1. Checks prerequisites (tmux, claude, git, Python 3.12+)
2. Copies the bundled plugin to Claude Code
3. Configures tmux key bindings (optional)
4. Installs MCP server globally (optional)
5. Builds macOS desktop notifier (optional, macOS only)
6. Verifies the installation

Options:

Flag	Description
--yes, -y	Skip confirmation prompts
--skip-bindings	Don't install tmux key bindings
--skip-mcp	Don't install MCP server
--skip-notifier	Don't build macOS notifier
--reinstall	Reinstall even if already installed

Uninstall

claude-tmux uninstall

Removes the plugin from Claude Code and optionally removes tmux bindings.

Flag	Description
--yes, -y	Skip confirmation prompts
--keep-bindings	Don't remove tmux key bindings

CLI Reference

# Setup
claude-tmux setup            # Install plugin and configure
claude-tmux uninstall        # Remove plugin
claude-tmux doctor           # Validate environment

# Agent Management
claude-tmux new <name>       # Create agent with optional worktree
claude-tmux kill <name>      # Stop agent
claude-tmux attach <name>    # Switch to agent window
claude-tmux ls               # List agents with status
claude-tmux merge <name>     # Squash-merge worktree and cleanup

# Navigation
claude-tmux next-attention   # Jump to next attention pane
claude-tmux prev-attention   # Jump to previous attention pane
claude-tmux next-done        # Jump to next completed pane

# Utilities
claude-tmux reconcile        # Clean up stale agents
claude-tmux events           # View event log
claude-tmux bindings         # Generate tmux keybindings

Development

See CLAUDE.md for architecture details, coding standards, and contributor guidelines.

make install      # Install dependencies
make test         # Run tests
make typecheck    # Run mypy
make pre-commit   # Run all checks

License

MIT