claude-tmux 1.2.0
A manager for multiple Claude Code instances with tmux
License: MIT
Requires Python: >=3.12
Keywords: agent, ai, claude, cli, parallel, tmux, worktree


## 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](https://docs.astral.sh/uv/) (recommended) or pip
- git

## Installation

### From GitHub (Recommended)

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

```bash
claude /install-plugin burstMembrane/claude-tmux
```

Then install the CLI tools:

```bash
# 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:

```bash
# 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

```bash
# 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`:

```bash
# 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

```bash
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

```bash
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

```bash
# 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](CLAUDE.md) for architecture details, coding standards, and contributor guidelines.

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

## License

MIT