claude-tmux
| Crates.io | claude-tmux |
| lib.rs | claude-tmux |
| version | 0.3.0 |
| created_at | 2026-01-12 16:42:10.106359+00 |
| updated_at | 2026-01-13 16:44:01.002702+00 |
| description | TUI for managing Claude Code tmux sessions |
| homepage | https://github.com/nielsgroen/claude-tmux |
| repository | https://github.com/nielsgroen/claude-tmux |
| max_upload_size | |
| id | 2038145 |
| size | 218,262 |
Niels Groeneveld (nielsgroen)
documentation
README
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 support.
Installation
Cargo install
Just run:
cargo install claude-tmux
Add the following line to your ~/.tmux.conf:
bind-key C-c display-popup -E -w 80 -h 30 "~/.cargo/bin/claude-tmux"
Reload your tmux configuration.
Press Ctrl-b, Ctrl-c to open claude-tmux from any tmux session.
Build from source
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:
bind-key C-c display-popup -E -w 80 -h 30 "/path/to/claude-tmux"
Reload your tmux configuration.
Press Ctrl-b, Ctrl-c to open claude-tmux from any tmux session.
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
Navigation
| 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