tmux-tango 2.0.0

A modern TUI for managing tmux sessions with Claude Code-inspired design - dance between your sessions!
Documentation

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