# TmuxTango Development Guide

A modern TUI for managing tmux sessions - dance between your sessions!

## Project Info
- **Language**: Rust 2021
- **Binary**: `tango`
- **Library**: `tmux_tango`
- **Version**: 2.7.1
- **Repository**: https://github.com/kylebeggs/TmuxTango

## Tech Stack
- **Ratatui** (0.28) - Modern TUI framework
- **Crossterm** (0.27) - Cross-platform terminal backend
- **Clap** (4.5) - CLI argument parsing
- **Which** (6.0) - Dependency checking
- **Anyhow** (1.0) - Error context handling
- **Serde/Serde JSON** (1.0) - Claude Code settings.json manipulation

## Architecture
- `src/main.rs` - Binary entry point, CLI subcommands (list, attach, kill, new, rename, hooks)
- `src/lib.rs` - Library root, exports public API
- `src/interactive.rs` - Ratatui-based TUI (App struct, event loop, rendering, key handling)
- `src/tmux.rs` - tmux session/window/pane management, command execution, caching
- `src/status.rs` - Pane status detection (hook-based + content heuristic classification)
- `src/hooks.rs` - Claude Code hook installation, auto-setup, settings.json management
- `src/error.rs` - Error types (`TmuxFzfError` enum)

### Key Design Patterns
- Hierarchical state: Sessions → Windows → Panes with lazy loading on expand
- Dual representation: nested state (`SessionState`) + flattened tree (`Vec<TreeNode>`) for rendering
- Mode-based key dispatch: Normal, CreateSession, Rename, ConfirmKill
- Cached tmux I/O with 500ms invalidation, cleared on mutations
- Split-panel layout: tree view (left) + pane preview (right)
- Status monitoring: two-path detection — Claude Code panes use hooks (primary) with content heuristics (fallback); non-Claude panes use command + content analysis. Hook status files at `/tmp/tango-status/`. Auto-installs hooks on first interactive launch.

## Development Commands

### Build & Test
```bash
cargo build            # Debug build
cargo build --release  # Release build
cargo test             # Run all tests
cargo test -- --nocapture  # Run tests with output
cargo test status::tests   # Test status module
cargo test tmux_operations # Test tmux operations
```

### Run
```bash
cargo run              # Debug mode
cargo run --release    # Release mode
```

### Publishing
```bash
cargo publish --dry-run  # Dry run
cargo publish            # Publish to crates.io
```

## Key Features
- Hierarchical tree view: sessions → windows → panes with expand/collapse
- Real-time pane status monitoring with colored indicators (●/○/?)
- Claude Code hook-based status detection (auto-installed on first launch)
- Pane content preview with ANSI color support
- Session/window/pane management (create, rename, kill, attach)
- Smart attachment (switch-client inside tmux, attach-session outside)

## Keyboard Shortcuts
- `j/k` or `↑/↓`: Navigate tree
- `Tab/Space`: Expand/collapse node
- `h/l` or `←/→`: Collapse parent / expand child
- `Enter`: Attach to selected target
- `n`: Create new session
- `r`: Rename session/window
- `d/x`: Kill (with confirmation)
- `p`: Toggle preview panel
- `s`: Toggle status monitoring
- `J/K`: Scroll preview
- `q/Esc`: Quit

## Dependencies
- **Runtime**: tmux (only external requirement)
- **Build**: Rust 1.70+
- **Dev**: tempfile, assert_cmd, predicates for testing
