claude-tmux

A terminal user interface for managing multiple Claude Code sessions within tmux. claude-tmux provides a centralized view of all your Claude Code instances, enabling quick switching, status monitoring, and session lifecycle management, including git worktree and pull request support.

Installation

Cargo install

Just run:

BASH

cargo install claude-tmux

Add the following line to your ~/.tmux.conf:

BASH

bind-key C-c display-popup -E -w 80 -h 30 "~/.cargo/bin/claude-tmux"

Build from source

BASH

git clone https://github.com/nielsgroen/claude-tmux.git
cd claude-tmux
cargo build --release

Add this to your ~/.tmux.conf to bind claude-tmux to a key:

BASH

bind-key C-c display-popup -E -w 80 -h 30 "/path/to/claude-tmux"

How to use

Reload your tmux configuration. Press Ctrl-b, Ctrl-c to open claude-tmux from any tmux session.

To use pull requests, make sure you have gh installed.

Tmux options

Options:

-E — Close popup when claude-tmux exits
-w 80 -h 30 — Popup dimensions (adjust to preference)

Features

Session Overview — See all tmux sessions at a glance with Claude Code status indicators
Status Detection — Know whether each Claude Code instance is idle, working, or waiting for input
Quick Switching — Jump to any session with minimal keystrokes
Live Preview — See the last lines of the selected session's Claude Code pane with full ANSI color support
Session Management — Create, kill, and rename sessions without leaving the TUI
Expandable Details — View metadata like window count, pane commands, uptime, and attachment status
Fuzzy Filtering — Quickly filter sessions by name or path

Screenshots

View the screenshots at GitHub.

Status indicators:

● — Working: Claude is actively processing
○ — Idle: Ready for input
◐ — Waiting for input: Permission prompt ([y/n])
? — Unknown: Not a Claude Code session or status unclear

Keybindings

Key	Action
`j` / `↓`	Move selection down
`k` / `↑`	Move selection up
`l` / `→`	Expand session details
`h` / `←`	Collapse session details
`Enter`	Switch to selected session

Actions

Key	Action
`n`	Create new session
`K`	Kill selected session (with confirmation)
`r`	Rename selected session
`/`	Filter sessions by name/path
`Ctrl+c`	Clear filter
`R`	Refresh session list

Other

Key	Action
`?`	Show help
`q` / `Esc`	Quit

Status Detection

claude-tmux detects Claude Code status by analyzing pane content:

Pattern	Status
Input prompt (`❯`) with border above + "ctrl+c to interrupt"	Working
Input prompt (`❯`) with border above, no interrupt message	Idle
Contains `[y/n]` or `[Y/n]`	Waiting for input
Otherwise	Unknown

Session Model

claude-tmux identifies sessions containing Claude Code by looking for panes running the claude command. The displayed working directory and preview come from the Claude Code pane when present, otherwise from the first pane.

Sessions are sorted with attached sessions first, then alphabetically by name.

Dependencies

ratatui — Terminal UI framework
crossterm — Terminal manipulation
ansi-to-tui — ANSI escape sequence rendering
anyhow — Error handling
dirs — Home directory resolution
unicode-width — Text alignment

Project Structure

claude-tmux/
├── Cargo.toml
├── src/
│   ├── main.rs        # Entry point, terminal setup
│   ├── app.rs         # Application state machine
│   ├── ui.rs          # Ratatui rendering
│   ├── tmux.rs        # tmux command wrapper
│   ├── session.rs     # Session/Pane data structures
│   ├── detection.rs   # Claude Code status detection
│   └── input.rs       # Keyboard event handling
└── README.md