# 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](https://github.com/nielsgroen/claude-tmux). claude-tmux Screenshot claude-tmux Screenshot 2 **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](https://ratatui.rs/) — Terminal UI framework - [crossterm](https://github.com/crossterm-rs/crossterm) — Terminal manipulation - [ansi-to-tui](https://github.com/uttarayan21/ansi-to-tui) — ANSI escape sequence rendering - [anyhow](https://github.com/dtolnay/anyhow) — Error handling - [dirs](https://github.com/dirs-dev/dirs-rs) — Home directory resolution - [unicode-width](https://github.com/unicode-rs/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 ```