Compact tabular view of tmux sessions, windows, and panes with smart renaming.
# Clone the repository to your preferred location
git clone <repository-url> <install-directory>
# Examples: ~/tmux-tools, ~/projects/tmux-tools, ~/dev/tmux-tools, etc.
# Recommended: symlink to ~/.local/bin (no sudo required)
mkdir -p ~/.local/bin
ln -s <install-directory>/tmux-tools ~/.local/bin/tmux-tools
ln -s <install-directory>/tt ~/.local/bin/tt
# Ensure ~/.local/bin is in your PATH (add to .bashrc or .zshrc)
export PATH="$HOME/.local/bin:$PATH"Alternative: Add the repo directory directly to PATH:
export PATH="<install-directory>:$PATH"Alternative: Symlink to /usr/local/bin (requires sudo):
sudo ln -s <install-directory>/tmux-tools /usr/local/bin/tmux-tools
sudo ln -s <install-directory>/tt /usr/local/bin/ttNote: Replace <install-directory> with the actual path where you cloned the repository (e.g., ~/projects/tmux-tools).
The tt command is a short alias for tmux-tools - use whichever you prefer!
tmux-tools # Show status (default command)
tt status # Same as above using short alias
tmux-tools overview # Tree view with summary
tmux-tools rename auto # Clean up default names
tmux-tools help # Show tmux command reference
tmux-tools help sessions # Show session commands| Command | Description | Common Options |
|---|---|---|
status |
Compact table of all sessions (default) | --show-pid, --show-clients, --rename-auto |
overview |
Tree view of sessions | --detailed, --json, -s <session> |
rename |
Rename sessions/windows | sessions, windows, auto |
config |
Manage configuration | show, create, edit |
help |
Show tmux command reference | sessions, windows, panes, layouts |
- Tabular display fits more information on screen
- Smart renaming: cities for sessions, directory names for windows
- Client dimensions shown in WxH format (e.g., 172x53)
- Control mode indication via underlined attachment indicator
- Detailed client view showing TTY, timestamps, and connection info
- Short
ttalias for quick access - Built-in tmux command reference via
helpcommand - JSON output for scripting
- YAML config for custom name pools and themes
- Multiple color schemes
- Backward compatible with original
tmux-status.shandtmux-overviewscripts
View all sessions compactly:
tmux-tools statusSee process IDs and paths:
tmux-tools status --show-pidView client connections:
tmux-tools status --show-clientsTree view with details:
tmux-tools overview --detailedExport to JSON for scripting:
tmux-tools overview --json | jq '.sessions[].name'Rename sessions and windows:
tmux-tools rename auto # Rename sessions to cities, windows to dirs
tmux-tools rename sessions # Rename all sessions to city names
tmux-tools rename windows # Rename all windows to directory namesGet help and command reference:
tmux-tools help # Show full tmux command reference
tmux-tools help sessions # Show session-specific commands
tmux-tools help windows # Show window-specific commands
tt help panes # Show pane commands (using short alias)Compact status:
TMUX STATUS Sun Nov 9 00:08:00 EST 2025
session win name p cmd size
- ------- --- -------------------- - ------- ---------
• oslo 0 tmux-tools 0 bash 172x53
1 apantli 0 fish
2 apantli 0 bash
3 docs 0 fish
rio 0 home 0 bash -
Tree overview:
● oslo • tmux-tools
apantli
apantli
docs
○ rio • home
Client view:
TMUX CLIENTS Mon Nov 10 23:53:44 EST 2025
session tty created activity size ctrl user
------- ----------- ------- -------- -------- ---- ----
lima - - - - x- philip
oslo ttys006 07:53 07:53 74x41 philip
rio ttys011 23:49 23:53 172x53 philip
Optional: Create ~/.tmux-tools.yaml to customize themes, pager, and naming:
display:
theme: "default" # default, vibrant, subtle, monochrome, none
pager: "auto" # auto, glow, bat, less, cat
naming:
session_pool: "cities" # cities, custom
custom_sessions:
- "dev"
- "work"Generate example config: tmux-tools config create
Pager Options:
The pager setting controls how help documentation is displayed:
auto(default) - Automatically usesglowif available, falls back tobat, thenlessglow- Beautiful markdown rendering with syntax highlighting (install:brew install glow)bat- Syntax-highlighted pager (install:brew install bat)less- Standard pager with ANSI color supportcat- Direct output without paging
Environment variables:
| Variable | Default | Purpose |
|---|---|---|
TMUX_TOOLS_THEME |
"default" | Color theme |
TMUX_TOOLS_PAGER |
"auto" | Help pager command |
NO_COLOR |
- | Disable colors |
Sessions: rio, oslo, lima, bern, cairo, tokyo, paris, milan, berlin, sydney, boston, madrid
Windows: Automatically named based on the active pane's current directory (e.g., /home/user/my-project becomes my-project). Directory names are truncated to 20 characters maximum.
Conflicts are resolved by advancing to the next available name. No number suffixes.
Use JSON output for automation:
# Count panes
tmux-tools overview --json | jq '[.sessions[].windows[].panes] | add'
# List commands
tmux-tools overview --json | jq -r '.sessions[].windows[].pane_details[].command'
# Find large sessions
tmux-tools overview --json | jq -r '.sessions[] | select(.windows | length > 2) | .name'- tmux (any recent version)
- bash 4.0+
- Optional: jq for JSON processing
| Problem | Solution |
|---|---|
| "tmux not found" | Install: brew install tmux (macOS) or apt install tmux (Linux) |
| No sessions found | Start session: tmux new-session -s test |
| Colors not working | Disable: export NO_COLOR=1 or check: echo $TERM |
| Config not loading | Create: tmux-tools config create or verify: tmux-tools config show |
| Columns misaligned | Shorten names or increase terminal width |
| Slow with many sessions | Use tmux-tools status instead of --show-pid |
See docs/TROUBLESHOOTING.md for comprehensive troubleshooting including installation issues, display problems, configuration debugging, and platform-specific solutions.
| Document | Description | Audience |
|---|---|---|
| CONTRIBUTING.md | Development setup and guidelines | Contributors |
| docs/ARCHITECTURE.md | Technical architecture with diagrams | Developers |
| docs/DESIGN-PRINCIPLES.md | Design philosophy | Designers, Developers |
| docs/TROUBLESHOOTING.md | Comprehensive troubleshooting | Users, Support |
| docs/ROADMAP.md | Future features and plans | Contributors, Users |
| examples/tmux-tools.yaml | Full configuration example | Users |
Core logic in lib/ modules. See CONTRIBUTING.md for guidelines and docs/ARCHITECTURE.md for technical details.
MIT License