TmuxTango 💃

A modern, high-performance TUI for managing tmux sessions with a Claude Code-inspired design. Built with Ratatui and Nucleo for blazing-fast performance and beautiful, responsive interfaces.

✨ Features

🎨 Modern UI Design

• Claude Code-inspired light theme with warm, professional color palette
• Dynamic box sizing - interface adapts to content and centers in terminal
• Split-panel layout - session list on left, detailed info on right
• Responsive design - works perfectly in any terminal size, SSH, or VSCode

⚡ Performance & Technology

• 6x faster search with Nucleo fuzzy finder (from Helix editor)
• Modern Ratatui TUI - smooth, responsive interface with proper Unicode support
• Lock-free streaming for real-time session updates
• Async architecture with Tokio for non-blocking operations

🎯 Core Functionality

• Interactive session selection with real-time fuzzy search 🔍
• Session management with intuitive keyboard shortcuts:
  • Enter: Attach to selected session
  • Ctrl-K: Kill session (with confirmation)
  • Ctrl-R: Rename session
  • Ctrl-N: Create new session
  • /: Search sessions
  • ?: Show help
  • q or Ctrl-C: Exit
• Smart attachment: Handles switching between sessions when inside tmux 🧠
• Live session details: Shows windows, PID, creation time, attachment status 👀
• Modal dialogs: Clean confirmation and input dialogs

🚀 Getting Started

Quick Install

cargo install tmux-tango

Usage

tango

First Time Setup

1. Install tmux (if not already installed):

   # Ubuntu/Debian
   sudo apt install tmux
   
   # macOS  
   brew install tmux
   
   # Fedora
   sudo dnf install tmux
   

2. Create some test sessions:

   tmux new-session -d -s "work"
   tmux new-session -d -s "personal"
   tmux new-session -d -s "development"
   

3. Launch TmuxTango:

   tango
   

🎯 What's New in v2.0

🎨 Complete UI Overhaul

• Ratatui-based interface - Modern TUI framework
• Claude Code light theme - Professional warm color palette
• Dynamic centered box - Floats in terminal center, grows with content
• Split-panel design - Session list + detailed preview

⚡ Performance Revolution

• Nucleo integration - 6x faster than previous skim-based search
• Better Unicode handling - Proper grapheme support
• Async event loop - Non-blocking, responsive interactions
• Real-time updates - Live session information refresh

🎛️ Enhanced Experience

• Visual feedback - Loading states, selection indicators, status icons
• Better error handling - Inline notifications, graceful degradation
• Comprehensive help - Built-in ? help with all shortcuts
• Cross-platform consistency - Works identically everywhere

⌨️ Keyboard Navigation

Normal Mode

• ↑/↓ or j/k: Navigate sessions
• Enter: Attach to selected session
• Ctrl+K: Kill session (with confirmation)
• Ctrl+R: Rename session
• Ctrl+N: Create new session
• /: Enter search mode
• ?: Show help
• q: Quit

Search Mode

• Type: Filter sessions in real-time
• ↑/↓: Navigate filtered results
• Enter: Attach to selected session
• Esc: Exit search mode

📦 Installation Options

From Crates.io (Recommended)

cargo install tmux-tango

From Source

git clone https://github.com/kylebeggs/TmuxTango.git
cd TmuxTango
cargo install --path .

Build Manually

git clone https://github.com/kylebeggs/TmuxTango.git
cd TmuxTango
cargo build --release
sudo cp target/release/tango /usr/local/bin/

🎨 Screenshots

The new interface appears as a clean, centered box that dynamically sizes itself:

┌─ TmuxTango ─────────────────────────────────┐
│                                              │
│  Sessions (3)         │  Session Details    │
│  ─────────────        │  ─────────────      │
│  ▶ ● main    2 win    │  Name: main         │
│    ○ dev     1 win    │  Windows: 2         │
│    ○ server  3 win    │  Status: ● Attached │
│                       │  Created: 2h ago    │
│  ─────────────        │  PID: 12345         │
│  / Search...          │                     │
│                       │  Windows:           │
│                       │  ▶ vim (active)     │
│                       │    shell            │
└─────────────────────────────────────────────┘
 ↵ Attach  ^K Kill  ^R Rename  ^N New  ? Help

🛠️ Development

Tech Stack

• Ratatui - Modern TUI framework
• Nucleo - High-performance fuzzy matcher
• Crossterm - Cross-platform terminal backend
• Tokio - Async runtime
• Rust - Systems programming language

Running Tests

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Specific modules
cargo test ui::tests
cargo test tmux_operations

Building

# Debug build
cargo build

# Release build
cargo build --release

📋 Requirements

• tmux - The only runtime dependency
• Rust - For building from source (1.70+)

🔧 Troubleshooting

Dependencies

Ensure tmux is installed:

# Check tmux
tmux -V

# Install if missing
sudo apt install tmux  # Ubuntu/Debian
brew install tmux      # macOS
sudo dnf install tmux  # Fedora

Terminal Compatibility

TmuxTango works in:

• ✅ Native terminals
• ✅ SSH sessions
• ✅ VSCode integrated terminal
• ✅ Tmux sessions
• ✅ Screen sessions

🆚 Migration from v1.x

Breaking Changes

• New Ratatui-based interface (no more skim dependency)
• Different keyboard shortcuts layout
• Light theme by default

What's Better

• 6x faster search performance
• Better Unicode and grapheme support
• More reliable across different terminals
• Cleaner, more professional appearance
• Real-time session information updates

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Ratatui team for the excellent TUI framework
• Nucleo developers for the blazing-fast fuzzy matcher
• Claude Code design inspiration for the beautiful color palette
• Helix Editor for pioneering modern Rust TUI patterns